Date: Fri, 30 Jul 1999 23:46:59 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: "Alton, Matthew" <Matthew.Alton@anheuser-busch.com> Cc: "'Nik Clayton'" <nik@nothing-going-on.demon.co.uk>, "'Matthew Dillon'" <dillon@apollo.backplane.com>, "David E. Cross" <crossd@cs.rpi.edu>, freebsd-hackers@FreeBSD.ORG, doc@freebsd.org Subject: Re: DOC volunteer WAS:RE: userfs help needed. Message-ID: <19990730234659.A3260@catkin.nothing-going-on.org> In-Reply-To: <BED2E68B5FB4D21193C90008C7C56836564D4C@STLABCEXG012>; from Alton, Matthew on Fri, Jul 30, 1999 at 04:09:20PM -0500 References: <BED2E68B5FB4D21193C90008C7C56836564D4C@STLABCEXG012>
next in thread | previous in thread | raw e-mail | index | archive | help
[ cc'd to -doc, reply-to points there ]
On Fri, Jul 30, 1999 at 04:09:20PM -0500, Alton, Matthew wrote:
> I prefer to work in flat ASCII. Perhaps the doc project can HTMLize
> the final product.
We can, it just takes longer, that's all.
It would make life simpler if you can follow the general structure, which
basically consists of an overall document, containing zero or more parts,
each part containing one or more chapters, each chapter containing zero
or more sections, each section divided in to zero or more subsections
(and so on, down to sub-sub-sub-sub-sub-sections). Each part, chapter,
and section has a mandatory title.
The Handbook is a good example of a document that uses parts, further
divided in to chapters, and the Doc. Proj. primer is a good example of
a document that dispenses with parts, and just uses chapters and sections.
Generally, something like
Title
Abstract
.....................
.....................
.....................
Chapter 1: Overview
.....................
.....................
.....................
and then further chapters as necessary.
Within the text, set off things that are 'out of band' information, like
notes, tips, and important information.
If you include instructions for the user to follow, please use "#" for
the root prompt, and "%" for the regular user prompt.
Refer to commands as 'command(n)', and assume that in the web (and PDF)
version that will be generated that this will automatically turn in to
a link to the manual page.
The Doc. Proj. primer has a (sparse) writing style chapter that covers
things like contractions, serial commas, and so on.
Of course, you don't have to do any of this, it just makes it harder for
whoever turns it in to DocBook (which will probably be me) to do the
conversion.
Once again, thanks for volunteering to do this.
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
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?19990730234659.A3260>