LfL question: how-to subdivide very big articles ?

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

LfL question: how-to subdivide very big articles ?

Alexey Eromenko
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL question: how-to subdivide very big articles ?

Thomas Schraitle-2
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: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL question: how-to subdivide very big articles ?

Alexey Eromenko
Thanks a lot !

I chapterized my whole guide, except that I used <sect2 id= instead of:
 <chapter id="chap.foo">

I committed the changes to LfL.

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.

Such incomplete article, that must be disabled is: "Managing Digital
Images with digiKam"


--
-Alexey Eremenko "Technologov"
---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: LfL question: how-to subdivide very big articles ?

Thomas Schraitle-2
Hi Alexey,

On Samstag, 28. Juli 2007, Alexey Eremenko wrote:
> Thanks a lot !
>
> I chapterized my whole guide, except that I used <sect2 id= instead
> of: <chapter id="chap.foo">
>
> 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: [hidden email]
For additional commands, e-mail: [hidden email]