Doc BoF at EuroBSDCon

Marc Fonvieille blackend at FreeBSD.org
Sun Nov 28 21:14:19 UTC 2004


On Sun, Nov 28, 2004 at 09:26:57PM +0100, Simon L. Nielsen wrote:
[...]
> 
> Discussed:
> 
> - Changing doc from SGML to XML (yes, really do it this time)
> 
>   - des agreed to make a script for the actual conversion of the files
>     from SGML to XML.
> 
>   - With SGML -> XML conversion we will loose the "IGNORE"
>     functionality from SGML, but it is not widely used, and where such
>     functionality is needed it can e.g. be handled in other ways.
>     This is used to be able to build sub directories in the Handbook,
>     but this has been broken for a while and nobody has complained
>     about that yet...
> 

Why?  Why a move to XML?

> - It was suggested to move chapter files to the main directory e.g.
>   en_US.ISO8859-1/books/handbook/x11/chapter.sgml ->
>   en_US.ISO8859-1/books/handbook/x11.sgml, since there does not seem
>   to a big point in all the sub directories, and make does not like
>   the sub directories well..
> 
> - Redoing the build system (make files), because it clearly shows its
>   age and several things are broken, e.g. OBJDIR.
> 
> - To be as little disruptive as possible to normal doc work it was
>   suggested to branch the doc/ tree for the work, and do the work in a
>   separate branch, to be merged into the main branch later again.
> 
> - Handling multiple FreeBSD release branches (4.X/5.X/6.X) in Handbook
>   to get rid of notes about "For 4.X do....".  There should be
>   multiple build Handbook versions on website, and perhaps one
>   complete one with "This section is for 4.X only..." and so on
>   automatically added.
> 
[...]

It's true that when a new major version appears there are problems of
multiple syntaxes, procedures for the same thing, etc.
This multiple branches scheme seems to be really difficult to manage
especially for persons who write the docs, I can't imagine the pain of
having to deal with 3 versions of the same document because the reality
is not so simple: a text cannot be simply divided in 3 versions or
divided in a general overview part then in major version parts.

I see one important thing missing in this list, an important thing for
the reader: the merge of the FAQ in the Handbook.  I'd put that on top
of the list, very important informations are in the FAQ and people often
miss them cause they are in another document, etc.

Marc
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20041128/87873532/attachment.sig>


More information about the freebsd-doc mailing list