[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-doc-english
Subject:    [kde-doc-english]Re: bloated docbook files
From:       Frederik Fouvry <fouvry () CoLi ! Uni-SB ! DE>
Date:       2001-01-15 13:30:33
[Download RAW message or body]

[I propose to move this thread to the appropriate lists, so if you
reply, don't include kde-i18n-doc.]

(Re the subject line: you probably meant: "documentation" instead of
"DocBook files"?  Just a matter of who's responsible for it ;-)

| 1) A significant part of the "aktion" documentation
| (roughly 1000 lines!) describes the C++ classes used
| by the program - technical stuff like this should be
| put into a separate plain text document.    

All documentation was originally planned to go in one file.  The
documentation template template.docbook contains a section for
technical documentation.  If it really gets big, then it may be a
good idea not to provide it for everyone.  There are several issues
(more complicated than "just throw it in a different file"):
1. From the table of contents it's easy to skip the technical part,
   but it's harder to exclude from a printed version.
2. Even so, it's less confusing for new users not to see that
   information.  Possible solutions:
   a. Provide two files, one for technical info, and one for people
      ;-)
   b. Use the userlevel attribute in the markup, and generate several
      versions of the documentation.
   The second one is the nicest one, but more complicated: the
   attribute needs to be added, the style files need to be modified to
   take the attribute into account, and the make procedure should
   somehow find out which level of documentation needs to be made
   (when the documentation display is created on the fly, this might
   be easier to realise).
   Having said that, for the first solution, changes in the Makefile
   procedure are needed too for a second documentation file.

[...]

(The rest of your message is entirely a matter for the FAQ maintainers
- you make several points worth the consideration.)

--
Frederik Fouvry		-	fouvry@coli.uni-sb.de
KDE DocBook Team	-	kde-docbook@master.kde.org

[prev in list] [next in list] [prev in thread] [next in thread]