[Scilab-Dev] SEP #24: Introduce an easy way to manage sub chapters in the documentation

[Sylvestre Ledru]

Hello Samuel,

Le jeudi 30 avril 2009 à 20:55 +0200, Samuel GOUGEON a écrit :
> Hello Sylvestre,
> 
> ----- Message d'origine ----- 
> De : Sylvestre Ledru 
> Date : 27/04/2009 10:26: 
> > Hello,
> > 
> > Pierre and I wrote a SEP about the introduction of the sub chapters into
> > the documentation.
> > 
> > As usual, don't hesitate to comment it.
> > 
> > Pierre & Sylvestre 
> >   
> As previously discussed with Serge and you through some bugzilla &
> requestzilla 
> comments, yes, this new feature will be very great. 
Indeed. Pierre has done some work on it and it sounds great!

> In these discussions, a topic strongly related to sub-chaptering has
> been evoked: 
> capability to show a topic in different places in the help tree (alias
> management).
> 
> For instance, derivat() would deserve appearing into a "polynomials"
> sub-directory,
> as well as into another "differential calculus" sub-directory.
> 
> Does DocBook manage this feature ? 
I don't know. Maybe it is written in the docbook documentation, I
haven't dig deep enough to find it...

> Will it be possible to build the doc with
>  - help files with inode having more than one link ?  (Linux / Unix)
>  - shortcuts pointing to an help file ? (Windows)
I don't think this solution would work. I believe the ID is unique for
each page and this solution would conflict.
> 
> Suggestion & question about the SEP:
>  - renaming CHAPTER into CHAPTER.txt (is CHAPTER mandatory to follow 
>    any DocBook convention ?)
No sure to understand your point here ?!

>  - SEP Proposal section: "As in the rest of the help build process, if
> help files 
> are not available in a specific languages, the system will copy all of
> them from
> the english one. Including all the subdirectory"
> 
> Does this mean that DocBook cannot manage a partially translated
> sub-directory ?
It can, we are just saying that if a page help/fr_FR/plop.xml is missing
in the french localization, we will use the english one
(help/en_US/plop.xml) as reference.

> What about such a processing: A list of declared files may be given in
> the CHAPTER
> file. While building the doc, this list is parsed. If a file is
> missing (from the locale directory), 
> its en_US release is used (together with available files already
> translated from en_US 
> to the locale).
File lists are often a bad idea. Too oftently, people forget to add a
new file (or remove an other). 

> Best regards
> Samuel
> 
> PS:The wiki page http://wiki.scilab.org/howto/scilab_documentation_kit
> is nice. 
This page is outdated. We should write a new documentation explaining
how to use easily the documentation system.
Thanks for reminding this!

Sylvestre