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

[Samuel GOUGEON]

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.
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 ? 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)

Suggestion & question about the SEP:
 - renaming CHAPTER into CHAPTER.txt (is CHAPTER mandatory to follow
   any DocBook convention ?)
 - /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 ?
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).

Best regards
Samuel

PS:The wiki page http://wiki.scilab.org/howto/scilab_documentation_kit
is nice. However, i haven't found any example in the wiki, nor of source
help file to imitate, in the Scilab tree of the distributed release. 
Where is it
possible to find a source page example containing
 - a See also section with cross references,
 - inclusion of an image (i just know that such an inclusion is possible 
since an
   image is included in the segs_properties page. But how to do),
 - other external hyperlinks
 - etc
Users who can spend a quite appreciable amount of time to go deep inside the
/DocBook definitive reference Guide/ to find these infos (imageobject, 
imagedata,
etc & main syntaxes and options), while they are mainly interested by 
Scilab
programming, are likely rare.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.scilab.org/pipermail/dev/attachments/20090430/29d92331/attachment.htm>