Doc BoF at EuroBSDCon

Thu Dec 2 20:34:44 UTC 2004

On 2004.11.29 06:03:20 +0000, Nik Clayton wrote:
> 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.

That doesn't seem to really work (it just builds as normal).  "make
article.xml" generate a XML file, but gives a lot of warnings.

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

Indeed, and of course the man doc/ tree will not be converted until
it's verified to actually work correctly.

> You are also aware of doc/share/xsl, right?  And that you can do:
> 
>     make STYLESHEET_TYPE=xsl ...

I know it's there, but I haven't really tested it much myself.

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

Yes, that in general that is a good idea.  The problem is that it
make(1) really does not like subdirectories used in that way.

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

Yes, which is much nicer to deal with in the makefiles...

Please note that moving away from the diretories was an idea.  It
might be that it is not worth the trouble, I havn't had the time to
look more into the real implications, positive and negative.

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

Well, en theory but that hasn't happened yet, so...

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

A long while ago I did start to work on a rewrite and documenting
goals etc. at
http://simon.nitro.dk/freebsd/doc-buildsystem/article.html but I
haven't really looked at it in a while since it (surprise suprise :) )
turned out to be a lot more work than I expected.  I do hope to have
the time to work on this again, but I don't really know when it will
be.  At the moment there are other FreeBSD project I think are more
important.

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

We actually also talked about that, and personally I do agree perforce
would be a good tool for work like this.  I even think Tom Rhodes has
given in and tried it now... :-)

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

Very interesting, I didn't know about that.  Thanks!

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

I don't think these changes will require major rewrite of the Primer,
but of course the Primer need to be updated accordingly.

-- 
Simon L. Nielsen
-------------- 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/20041202/573c38aa/attachment.sig>