Time for a Network Handbook?

Murray Stokely murray at freebsdmall.com
Mon Dec 6 21:16:39 UTC 2004


On Mon, Dec 06, 2004 at 07:20:18PM +0000, Nik Clayton wrote:
> Partly to move closer (as others have said) to having a collection of
> Handbooks.  But mainly because I was glancing over the existing content

Yes, we got consensus this summer to move out the system admin part
into an administrator handbook, and I'd still support someone doing
that at the same time as the network <part> is moved out.  It would be
great if this was done in a transparent way...

One thing we should think about is using link entities to allow the
different chapters to be included in different books without breaking
the build due to broken references.  Currently, the single-chapter
builds often fail because xrefs to other chapters can not be looked
up.  If we replaced all xrefs to other chapters with entities like:

&link.chapter.sect;

Then we could define that entity depending on the presence of the -i
parameter entity for the given chapter file.  If the chapter to be
linked to is included in the build (and it's -i entity defined), then
the <xref> is created.  If it is not included in the build, then
descriptive text is used instead 'The Blah Chapter in the Handbook'.

In this way, we could more easily move chapters around between books
without having to update all of the cross-chapter references.

This would also allow us to easily maintain a full version of the
Handbook that includes all of the chapters, in addition to the split
off 'network handbook', 'admin handbook', etc.  It's a stop-gap until
we get proper olink support, basically.

I explored a little of this work for the printed third edition, when
we split it into two volumes, and it worked well for that purpose.  We
created a new links.ent file with the necessary parameters defined as
I specified above.

	- Murray



More information about the freebsd-doc mailing list