Doc BoF at EuroBSDCon

[Simon L. Nielsen]

On 2004.11.28 22:14:44 +0100, Marc Fonvieille wrote:
> 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?

The main reason would be that a lot of new tools work with XML.  We
already use some e.g. for the mirror section, and having the DocBook
as real XML should make it less painful to add more like that.  Also,
rumor has it that the XML based DocBook tools is a lot faster.

Also it's really nice to be able to do preprocessing using XSLT, which
is, while not perfect, far less painful that DSSSSSSL/Scheme.

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

Well, I don't know how many places it would apply, but what I was
thinking of was doing someting like this :

	<para>To restart sshd run:</para>

	<screen rel="4">kill -HUP `cat /var/run/sshd.pid`</screen>

	<screen rel=">4">/etc/rc.d/sshd reload</screen>

Or something like that.  When we don't want to support a release more
it should be trivial to remove stuff for an old branch.

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

Well, this was a list of stuff we talked about, not prioritized and
certainly not a complete doc TODO.  That said, I agree the FAQ is
something that should be dealt with.

-- 
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/0a778b25/attachment.sig>