Doc BoF at EuroBSDCon

[Simon L. Nielsen]

Hello doc people

At EuroBSDCon we held a little Bird-Of-Feather (BOF) were we talked a
bit about ideas for future doc work.  Below is a summary of what we
talked about.  If anything is unclear, please don't hesitate to ask,
and I (or hopefully some other BOF attendee) will try to elaborate.

This will certainly not something that will happen overnight, and I do
expect that there are other people who have comments.

EuroBSDCon was a while ago, I just haven't gotten around to actually
posting it in public, sorry about that.

Personal note: While I still very much think the issues we talked
about are important, and are the way to go, I have a few other large
FreeBSD related projects that is taking up a lot of my time, so it
will be a bit before I have the time to seriously work on the topics
presented below...

---------------------------------------------------------------------
FreeBSD "Spontaneous" Doc BOF, Saturday evening 2004/10/30

Attending: brueffer, ceri, des, mheinen, ru, simon, trhodes.

Note: A more formal doc BOF was scheduled earlier Saturday, but it was
announced to late, so not enough people showed up, so it was
postponed.  The second BOF just happened since we realized that we
were at lot of doc people gathered.

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

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

---------------------------------------------------------------------

-- 
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/20041128/d61d77a7/attachment.sig>