Date: Tue, 10 Jul 2001 11:40:34 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: State of the Handbook Message-ID: <20010710114034.E16152@clan.nothing-going-on.org>
index | next in thread | raw e-mail
[-- Attachment #1 --]
Hi folks,
[ WRS == WindRiver Systems ]
WRS intend to produce a second printed edition of 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 an initial list 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, an 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 <*info> sections in the
document (<chapterinfo>, <partinfo>, 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.
Comments and suggestions are, as ever, sought.
N
--
FreeBSD: The Power to Serve http://www.freebsd.org/
FreeBSD Documentation Project http://www.freebsd.org/docproj/
--- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 ---
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (FreeBSD)
Comment: For info see http://www.gnupg.org
iEYEARECAAYFAjtK26EACgkQk6gHZCw343WXDgCeLO7c0kDSl1z+Z3Vm0xQsgTsv
nyIAoI1Fo2iE9s+prKaqsTJCGrRSgkau
=72IT
-----END PGP SIGNATURE-----
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010710114034.E16152>