One thing I would like to comment on...the intra-doc links are a bit difficult to work with, esp. if you add/delete chapters and sections or just move them around. As soon as you do this a like like <uri link="#doc_chap15_sect2" easily becomes invalid during the editing process. BTW, #doc_chap_15_sect2 doesn't work at all even though both do exist...looking at the generated HTML, it looks like the sections aren't getting "defined" at the top of the document as the chapters are. Anyway, not to get off track from the first problem...I think this would work much better if we can explicitly name the chapters and sections in the documents...i.e. instead of: <chapter><title>Installing a Bootloader</title>.... we do this: <chapter name=bootloader><title>Installing a Bootloader</title> Then no matter where that final chapter ends up, when we say <uri link="#bootloader">Installing a Bootloader</uri>, we are assured that the link works as long as we don't delete the chapter or arbitrarily rename it. Ditto for sections. Another thought: If we do shorthand <uri>#bootloader</uri> Then the transformer should automatically plug in the title of the chapter...if for some reason a chapter title doesn't exist, then plug in "Chapter 1", etc.. The nice thing about this is that the author no longer cares what the chapter title is and doesn't have to carefully proofread the final work to ensure all references to that chapter match the chapter title exactly.
I'll add this soon.
this bug still alive and well ?
I am not sure. I have not seen changes in a long time... //ZhEN
Noted, I will try and include this in the doc dev guide. //ZhEN
Did anyone ever add this to the xsl? //ZhEN
Peit, could you do this, or show me how to do this? Thanks, //ZhEN
I'll take a look, expect it soonish(possibly :P)
?
Perhaps this can be set as a project for the infrastructure? It isn't a small change, as it requires: - guide.xsl / handbook.xsl updates - guide.dtd / book.dtd updates - updates on hundreds of documents (documentation-team) and website pages (infrastructure).
It could be easier as you think, SwifT. The link-attribute can be added as #IMPLIED and the guide.xsl changed, so that it will take link when it is present or else do an automated numbering. I'm not really sure, but I think you can give multiple anchors to one element. So, maybe both can be applied and old links inside a document or from outside won't run to nowhere.
Is it even intelligent to add such an attribute? The numbering scheme is easy and logical. Adding attributes enlarges the document, and might make it more difficult to find out where to link to. It will also make it less readable imho because such attributes will then be usable in <chapter>, <section> and <pre>s... I think we shouldn't enhance the GuideXML further -- the main goal of GuideXML was to make it easy to develop documentation. If we continue to enhance it, we might be better of using a more tested format that is widely used. Just my idea.
IMHO Michael has a good case. "Adding attributes [...] make it more difficult to find out where to link to" It quite the opposite. At the moment you need to count chapters and sections to know where to link to. This is cumbersome and error prone. I am about to update the translation of faq.xml, 20+ intralinks to check and at least one link from another document that I know of from memory. A name would help I believe. Having a name attribute would also prevent messing up links when a document is reorganised. Keep in mind that there are also a few inter document links and that those links might point to a different chapter than expected and not be broken making it difficult to notice the mistake. IMHO it would be a bonus rather than extra complexity as long as we don't have to update all current links. According to lars it would be possible. my
IMHO Michael has a good case. "Adding attributes [...] make it more difficult to find out where to link to" It quite the opposite. At the moment you need to count chapters and sections to know where to link to. This is cumbersome and error prone. I am about to update the translation of faq.xml, 20+ intralinks to check and at least one link from another document that I know of from memory. A name would help I believe. Having a name attribute would also prevent messing up links when a document is reorganised. Keep in mind that there are also a few inter document links and that those links might point to a different chapter than expected and not be broken making it difficult to notice the mistake. IMHO it would be a bonus rather than extra complexity as long as we don't have to update all current links. According to lars it would be possible. my 0.02
Then this (easier vs cumbersome) is where we disagree. For instance the Gentoo x86 Installation Guide: if I want to link to the section on "Manual kernel compilation" I can quickly find out that the chapter is 16 and section 3. So #doc_chap16_sect3. If I want to link to it using an attribute, I first have to find the place of this section in the sourcecode (which, if you don't have any words to search for, is far more difficult as the chapters/sections aren't numbered), then verify if there already is an attribute. If so, then I should use that value, and otherwise I have to create one. Another reason why I am hesitant to implement this is my vision on such links. I believe that they should be formed like this: <uri link="#doc_chapX_sectY"> (title of referenced part) </uri> For instance <uri link="#doc_chap16_sect3">Manual kernel configuration</uri>. This has several reasons: 1. It is logical and structured; there is no room for misinterpretation. 2. It is still usable for non-HTML documents (printed PDFs, txts, etc.) Perhaps I can provide a sort-of consensus: If the <uri>...</uri> does not have a link attribute, and does not begin with http:// in its text(), then the XSLT should search for this title and automatically use the #doc_chapX_sectY numbering, like this: <uri>Manual kernel configuration</uri> results in <a href="#doc_chap16_sect3">Manual kernel configuration</a> This way looking up in the sourcecode is not necessary (just look at the generated page and use the title), changes in chapter/section structure are automatically propagated, and the known numbering remains. There is only one problem, namely that this provides an undeterministic state: many chapters/sections can have the same title. I feel however that this problem (1) shouldn't exist as it would reflect bad documentation construction, and (2) is not fatal to the proposal. Any thoughts? I can implement this easily (I can actually implement everything you want :). (PS Bugzilla is a PITA again... it again refuses to wrap the comments; I'm typing this with extra returns...)
Now, see it from another side. You have your doc_chap16_sect3 linked from several other documents, because it's an important section. Now you edit your document and add a section, so that doc_chap16_sect3 becomes doc_chap16_sect4. You have to find every appearence of doc_chap16_sect3 and change it to doc_chap16_sect4 in all the other documents, that link to that section. With the help of additional consistent names, like id="important_section" (usually we should choose better names than this example) we can still link to this section without editing the links in other documents, even when we reorder the sections or chapters. As I wrote before, both is possible at the same time.
Okay, looks like I'm in the minority here. The following patches include support for an id-attribute in <chapter>, <section>, <pre> and <fig> (which are the tags that have names, like "doc_chapX", "doc_chapX_sectY", "doc_chapX_sectY_preZ" and "doc_chapX_sectY_figZ") of which the content is used to create <a name="..."/>s for.
Created attachment 20778 [details, diff] Patch to guide.xsl Include <a name="{@id}"> tags for {chapter,section,fig,pre}.
Created attachment 20779 [details, diff] Patch to guide.dtd Adds id as attribute for the chapter|section|fig|pre entities.
Okay, I've committed the necessary changes to add id-attribute-support to <chapter> and <section> for guides, and <part>, <chapter>, <section> and <subsection> for the handbook. I haven't done this for fig's or pre's, but if it is necessary I can do so too. However I believe the above entities should cover what seems to be needed. The applied changes work at my local node so should work on all the official ones too. I'll update the guide.xsl for local usage to include support for this too.
Okay, local guide.xsl is updated; xml-guide.xml is updated. I'm closing this one off now.
