Date: Mon, 12 Apr 1999 21:22:14 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Greg Lehey <grog@lemis.com> Cc: FreeBSD Documenters <doc@FreeBSD.org>, "Robert A. Bruce" <rab@cdrom.com> Subject: Re: Publishing the FreeBSD handbook Message-ID: <19990412212213.B9344@catkin.nothing-going-on.org> In-Reply-To: <19990412125145.J2142@lemis.com>; from Greg Lehey on Mon, Apr 12, 1999 at 12:51:45PM %2B0930 References: <19990412125145.J2142@lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
How do,
On Mon, Apr 12, 1999 at 12:51:45PM +0930, Greg Lehey wrote:
> I've been looking at the handbook for a while, and have tidied up some
> rough edges, as you may have noticed. But basically it's clear that
> the handbook isn't really ready for printing in its current form, and
> Bob Bruce has agreed to postpone the matter until it can be tidied up
> a bit. We're hoping to be able to get it in printable shape by about
> August or September, and then he's talking about having a new edition
> printed about twice a year, so the handbook would be subjected to a
> release cycle similar in nature to the software release.
I've been thinking about this a bit, and I've got a few questions.
1. Does the Handbook need a 6 month release cycle? The majority of
the content doesn't change that much in 6 months. Wouldn't a
threshold of "changes made since last printing" make more sense,
perhaps with a minimum 6 month wait between prints.
2. What's the Walnut Creek reaction been to my ideas about splitting
the Handbook up into smaller books? After "FreeBSD in 21 days"
gets done that's my next big project. If the Handbook suddenly
becomes 12 or 15 smaller handbooks in 8 or 9 months time that's
obviously going to affect whatever they're thinking of.
3. Are there plans for any additional content to be "Print version only"?
> I've done some thinking about what needs to be done. I've
> deliberately held off while the previous discussion about the future
> of the handbook, but it now looks as if we haven't come to any
> conclusions which would affect my issues.
See point 2 above.
> As I see it, in order to print the handbook, we need to:
>
> 1. Remove the "to be written" sections. Maybe there's a style
> sheet option which can help here (Nik?). Otherwise it might
> make more sense to just comment out these sections and create a
> document "to be done" which describes where they are.
SGML marked sections. Essentially, you create an entity (call it 'foo'
for the sake of argument) and put
<!ENTITY foo "IGNORE">
in the DTD. Then, around content you want to ignore for this printed
version you wrap it in
<![ %foo; [
...
]]>
If you want to include that information, you normally include "-ifoo" on
the command line of your SGML tools, otherwise they'll ignore it (the
default).
That's a simplistic approach (in reality you'll probably have a number of
entities relating to this printing of the Handbook, turned on or off with
one other entity) but that's the basic idea.
> 2. Update some old and mouldy sections. Some parts are so old as
> to be misleading, and if we don't update them we should
> eliminate them. If *you* have contributed in the past, now
> would be a good time to check over your contribution and
> consider whether you should update it.
>
> Of course, if you want to overhaul a contribution you didn't
> write, that's a great idea too, though I suppose it would be a
> good idea to check with the author first.
This could well be a case of throwing $$$ at the problem.
> 3. Add an index, and generally improve the format. I'm planning to
> do this myself, but if anybody else wants to join in (or even
> take over), I'll be more than happy.
Take a look around http://www.docbook.org/, in particular the bits that
talk about how you can automatically generate an index.
> 4. Remove some sections for the printed version only. For example,
> Bob suggested that most people who want to send core teams
> encrypted messages won't copy the key out of the book, they'll
> get it online, so we don't need to publish them. I also wonder
> whether we really need to publish 37 pages of contributor names
> and (possibly incorrect) mail addresses.
Without getting in to the ins-and-outs of what to leave out, and what
to include, you use marked sections as details in point 1 to do this
at relatively fine detail. If you want to omit entire chapters, you
can do this by creating an alternative to the current top level
handbook.sgml which only includes the appropriate chapters in the
appropriate order.
As to which sections to leave out -- I'd be loathe to remove the list of
contributors. Possibly the e-mail addresses, yes, but not the names.
2 pages (small type, 3 columns?) of names is, I think, a small price to
pay in recognition of the effort of an awful lot of people.
> There are a couple of things which I think we don't need to do, but
> I'm willing to listen to opinions:
>
> 1. Don't change the style. Sure, it's a hodgepodge, but that can
> be explained, and I don't think that it will concern the target
> audience too much. I do wonder about emoticons and such, but a
> real style overhaul would be a very difficult job, and I'd
> anticipate a number of clashes of viewpoint in the process.
For emoticons, look for <!-- smiley --> in the SGML source. It was one
of the things I noted when I was going through it. I haven't decided yet
whether to remove them, or use entities:
<!ENTITY smiley.generic ":-)">
<!ENTITY smiley.wink ";-)">
<!ENTITY smiley.sad ":-(">
and replace them. Then you can redefine those entities if you want to go
all corporate.
(Yes, I am serious about this &smiley.generic;)
> 2. Don't change the overall format. I don't like it yet, but it's
> an area that Nik has been working on, and I don't want to get in
> his way.
Seconded. Heavily. The Handbook (and soon to be the FAQ, and the
tutorials, and so on) do not contain formatting markup. The correct
approach to decide the formatting is in the stylesheets.
I think I've grokked the solution to the main problem you've been having
(which I'll go through in a private message). If it works for you, I'll
commit it.
N
--
Bagel: The carbohydrate with the hole
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990412212213.B9344>