Mailinglist Archive: opensuse-doc (23 mails)

< Previous Next >
Re: [opensuse-doc] LfL question: how-to subdivide very big articles ?
  • From: Thomas Schraitle <thomas.schraitle@xxxxxxx>
  • Date: Mon, 30 Jul 2007 09:11:59 +0200
  • Message-id: <200707300912.00069.thomas.schraitle@xxxxxxx>
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: opensuse-doc+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-doc+help@xxxxxxxxxxxx

< Previous Next >
List Navigation