State of the Handbook
WRS intend to print the Handbook in late fall 2001. To that end, they
are "sponsoring" some ongoing work in order to address the comments
received from the last printing, and improve the quality of the Handbook
for all FreeBSD users.
In talking with Murray Stokely we've identified a number of things that
need to happen to the Handbook before it's ready for primetime. Some of
these are things that WRS can do, and contribute back to the community.
Others are discussions we need to have on the -doc list, and, as ever,
people to stand up and do the work :-)
The expected changes are:
1. Generate an index.
WRS are putting a lot of effort in to this, and expect to have it
finished by the end of July.
2. Supplement the ASCII art with images.
Something else on WRS' todo list, although it doesn't prevent anyone
else with an artistic bent from picking some of the existing ASCII art
and producing images for it as well. WRS expect to have this done by
the end of August.
3. Stylesheet and wordlist
We're quite inconsistent about the use and spelling of terms,
and the stylesheet for authors is quite small. We're talking to
O'Reilly about the licensing behind their stylesheet and wordlist
at http://www.oreilly.com/oreilly/author/stylesheet.html and the
possiblity of making this available to all open source documentation
projects (probably as a guide).
[ "We're talking to O'Reilly"? OK, Murray and I were sat discussing
this at Usenix, got up to leave, and the chap next to us introduced
himself as Chuck Torporek, and editor at O'Reilly. Serendipity at
its best. ]
We probably also need a stylesheet for images that talks about size,
fonts that we use, and so on. I know much less about this, so I'll
hand wave at this point, and anyone with any experience should feel
free to chime in.
4. Spelling corrections
'nuff said.
5. Integration of Randy Pratt's install guide to replace much of the
existing material in chapter 2.
6. Licensing
Some sections of the Handbook are under inconsistent copyrights
and licenses. I (nik) would like the entirety of the Handbook (and
indeed, the FreeBSD docs as a whole) to be available under a consistent
license, with the copyright transferred to a single entity --
probably the FreeBSD Foundation. Where sections of the Handbook do
not do this, we will be contacting the original authors to ask them
whether they would consider relicensing their work. If they are not
happy for this to happen then we will need to replace the content
with text under a 'free-er' license.
[ "we" in this context means the Doc. Proj. We haven't really
discussed licenses in any great detail before, and it's a
discussion we should have -- it's going to form part of the
O'Reilly doc. summit in a few weeks time, and I'd like to go
there knowing that I'm accurately representing the views of the
community. ]
7. Attribution.
Content in the Handbook is currently attributed in a number of
different ways.
Murray and I are considering;
1. Moving the existing attribution in to sections in the
document (, , and so on, as necessary).
2. Writing tools to collate this information and automatically
generate a "Contributors" section in the Handbook, in much the
same way that the Index is automatically generated. This
might look something like:
Author: Contribution:
J. Bloggs Wrote much of the original
networking section.
F. Bloggs Rewrote the networking section
to talk about IPv6.
and so on.
The intention is always that attribution information is retained in
the .sgml, and that we have flexibility in determining how it is
presented (and that it should never be ommitted).
8. Removing some content to other documents.
As a minimum, we expect to move the following chapters and/or
sections
Source Tree Guidelines and Policies -> Developer's Handbook
Kernel Debugging -> Developer's Handbook
PC Hardware Compatability -> Book in its own right (?)
Bibliography -> Book in its own right (?)
In addition, for printing, it is envisaged that the PGP keys section
will list individual key fingerprints, but not the whole key (unless
we can print this section in 4 point type. . .) The PGP key info
won't be removed, but it will just be excised for printing.
9. Adding additional content
Chern Lee is working on a chapter for "Configuration and Tuning",
and Chris Shumway is working on extending the X11 chapter.
10. Use admonition graphics.
Cute little icons to go next to Tips, Notes, Warnings, and so on.
The icons that come with the DocBook stylesheets are serviceable,
but boring. I've singularly failed to get replacements for these,
WRS might be able to spare some time from a designer for a set.