Doc BoF at EuroBSDCon

[Marc Fonvieille]

On Thu, Dec 02, 2004 at 08:57:39PM +0100, Simon L. Nielsen wrote:
> > 
> > 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.
>

You're right, DSSSL is not easy to deal with, I don't know if a XSLT
solution can replace our DSSSL system.

> > > - 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 just had a look to 2 recent/rewritten sections that I know a bit
(the sound card one and the scanner one), and I ended to this opinion:
it's possible to do "release versions" without pain when text is written
in a clean way (by "clean" I mean in thinking about branches version).
For example with the scanner section, it's really easy cause I tried to
write it in separating the specific release version informations.
With the sound card section we will end up to quite 2 differents sections.
So most of time it should be easy to do release versions of docs.
I think we will also need to be able to specify the release version for
some inline element like filename 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/20041202/0d19d5b5/attachment.sig>