[opensuse-doc] LfL question: how-to subdivide very big articles ?
Hi all ! I have LfL question: how-to subdivide very big articles ? That is: I have "VirtualBox" article - a big guide actually. I want to have it's chapters to be available as links at the top of the article. Thomas once told me about using chapter IDs, but I didn't understood then. I will try now... So, can you help with example XML code ? -- -Alexey Eremenko "Technologov" --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hi Alexey, On Samstag, 28. Juli 2007, Alexey Eremenko wrote:
I have LfL question: how-to subdivide very big articles ? That is: I have "VirtualBox" article - a big guide actually.
I want to have it's chapters to be available as links at the top of the article.
Thomas once told me about using chapter IDs, but I didn't understood then. I will try now...
So, can you help with example XML code ?
Sure. You will see, it's pretty easy after you get the idea behind. For example, you want to link from a paragraph to a chapter. These are the steps that you need: 1. Determine the ID value of the chapter that you want to link to. You can also link to sections, figures, tables, appendices, etc. the method is the same. It should look like this: <chapter id="chap.foo"> <!-- ^^^^^^^^_____ Your ID value --> <title>Something about Foo</title> ... 2. If you do not find an ID value, "define" your own ID value. Insert an attribute "id" with your ID value in the respective element. The ID value should be legible so that any writer have at least some idea what is this chapter about. :) Look for other examples. Be careful, the definied ID value must be unique (appears only once in the whole document), otherwise you get validation errors. 3. Go back to your paragraph and insert a xref element. This is the cross reference to your ID and looks like this: <para>... See <xref linkend="chap.foo"/> for more information ... </para> You can insert as many xrefs to your chapter as you like. That's all! The stylesheets take care of how the xref appears in your text. Usually you get something like this: See Chapter 1, »Something about Foo« for more information. Does it help? Have fun, Tom -- ---------------------------------------------------------------------- SUSE LINUX Products GmbH >o) Maxfeldstrasse 5 /\\ Documentation Specialist 90409 Nuernberg, Germany _\_v http://en.opensuse.org/Documentation_Team SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
Hi Alexey, On Samstag, 28. Juli 2007, Alexey Eremenko wrote:
Thanks a lot !
I chapterized my whole guide, except that I used
I committed the changes to LfL.
Probably I misunderstood your intention, but I have some problems with your commit (virtualbox.xml, r307). :) Ok, I see the following issues: 1. "Mini tocs" as paras with xrefs are not the preferred way in DocBook. If I am right, in HTML they are generated automatically and you end up with two versions of TOCs. 2. Maintenance: Do not underestimate the maintenance of mini tocs. If you move sections, delete or insert a new one, you have to update the mini TOC *by hand* as well! 3. As I described in (1), "mini TOCs" can be easily customized in the DocBook stylesheets. You can control the depth, the appearance through CSS or suppress it, if you do not like them. If you manually engrave your mini TOCs into your document, you have lost the opportunity to customize it to your needs. It should be always the preferred way: Leave automatically generated content to the stylesheet but provide the necessary information for it. 4. It is inconsistent with other articles. So my conclusion is: Please remove the mini TOCs from your chapter. :)
side note: Thomas: Please make sure that LfL RPM gets updated for BETA1. (Alpha6 contains ancient RPM from Mar 2007, instead of Jun/Jul 2007 !) Also, I believe that incomplete articles must be "disabled" from building.
I will take care of this.
Such incomplete article, that must be disabled is: "Managing ^^^^ (?) Digital Images with digiKam"
Leave it to the maintainer of this article. :) Bye, Tom -- Thomas Schraitle ---------------------------------------------------------------------- SUSE LINUX GmbH >o) Documentation Specialist Maxfeldstrasse 5 /\\ 90409 Nuernberg _\_v http://en.opensuse.org/Documentation_Team --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-doc+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-doc+help@opensuse.org
participants (2)
-
Alexey Eremenko -
Thomas Schraitle