Doc BoF at EuroBSDCon

[Nik Clayton]

On Sun, Nov 28, 2004 at 09:26:57PM +0100, Simon L. Nielsen wrote:
> - 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...

In case you're not aware, 'xml' is a supported output FORMAT.  You
should be able to do

    make FORMAT=xml

in any of the document directories and get book.xml or article.xml
generated as appropriate.

I strongly recommend that you do this and experiment with getting an
XML/XSL toolchain in place *before* doing a full cutover to XML.

You are also aware of doc/share/xsl, right?  And that you can do:

    make STYLESHEET_TYPE=xsl ...

?

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

Don't do that.  The point of the subdirectories is so that all the files
associated with a chapter (images, example files, and so on) are kept
together with that chapter.

Otherwise you'll end up down the road with filenames like

   vinum-foo.png
   vinum-bar.png
   x11-foo.png
   x11-bar.png

and so on.  All you've done is swapped the '/' for a '-'.

It also lets you split up the chapter.sgml files in to smaller files,
with a single chapter.sgml 'driver' file (in the same way that things
like book.sgml include all the chapter.sgml files).

> - Redoing the build system (make files), because it clearly shows its
>   age and several things are broken, e.g. OBJDIR.

Makes sense.  I'd be happier seeing a comprehensive list of the things
that are broken though, so we can measure the replacement and make sure
it solves the problems.

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

Rather than branch it in CVS I'd say use Perforce for this work.

> - 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 was suggested to handle this with (SG|X)ML attributes on like
>     done in the release documentation for different architectures.
>     simon was volunteered to implement this.

The DocBook XSL stylesheets call this 'profiling'.  See 

    http://docbook.sourceforge.net/release/xsl/current/doc/html/rn19.html

for more details.

All the changes discussed so far will also require updates to the
Primer.  Who volunteered to keep that up to date?

N
-- 
FreeBSD: The Power to Serve      http://www.freebsd.org/               (__)
FreeBSD Documentation Project    http://www.freebsd.org/docproj/    \\\'',)
                                                                      \/  \ ^
   --- 15B8 3FFC DDB4 34B0 AA5F  94B7 93A8 0764 2C37 E375 ---         .\._/_)
-------------- 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/20041129/f4b02e83/attachment.sig>