Date: Sun, 23 May 1999 13:03:05 +0200 From: Wolfram Schneider <wosch@panke.de.freebsd.org> To: Greg Black <gjb-freebsd@gba.oz.au>, Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: doc@FreeBSD.ORG, freebsd-translate@ngo.org.uk Subject: Re: FDP Directory Reorganisation Message-ID: <19990523130305.01354@panke.de.freebsd.org> In-Reply-To: <19990523023158.105.qmail@alice.gba.oz.au>; from Greg Black on Sun, May 23, 1999 at 12:31:58PM %2B1000 References: <19990513211458.B70767@catkin.nothing-going-on.org> <19990519214022.D60921@catkin.nothing-going-on.org> <19990520095342.18541.qmail@alice.gba.oz.au> <19990520232510.A54603@catkin.nothing-going-on.org> <19990523023158.105.qmail@alice.gba.oz.au>
next in thread | previous in thread | raw e-mail | index | archive | help
On 1999-05-23 12:31:58 +1000, Greg Black wrote:
> [Re "articles" and "books":]
> > > > I am prepared to replace this with just one directory if someone can
> > > > come up with a good name for it.
> > >
> > > Just because it's a bit difficult to dream up the best name for
> > > this directory is a poor reason to impose an arbitrary division
> > > of similar documents based purely in their length.
> >
> > It's not based on their length.
> >
> > The documentation will exist as documents marked up according to the
> > DocBook DTD. The precise distinction is based upon the element describing
> > the entire document. This will be one of either <article> or <book>. If
> > it's marked up as an article then it goes in articles/, as a book in
> > books/, and as a manual page in man/.
> >
> > An alternative way of expressing this, without getting in to the SGML,
> > is that if it has more than one chapter then it's a book, otherwise it's
> > an article.
>
> This is a semantic distinction based on something that is
> utterly irrelevant to any /user/ of the documentation. If the
> object of the documentation is to provide help to the users of
> the documentation, then the organisation needs to based on
> distinctions that make sense to those users.
Right. Users don't care which different SGML DTD we are using internally
for our documentation.
> I have proposed putting "articles" and "books" into a single
> directory called "doc". I don't particularly care if the name
> is "doc" or anything else, but I am convinced that it makes more
> sense to a user of the documentation to find all the documents
> of this kind in the one place.
The directory name /doc/ is fine.
The location of documents on the web server may differ
from the directory structure of the cvs repository. E.g.
we may have an URL on the web server
/doc/printing/
with links to the documents:
How to print
How to setup a printer
Advanced Printer Setup
How to setup a network printer
Manual pages for printing
FAQ printing
and the directory structure in the repository is
doc/en.8859-1/book/handbook/printing-sysadmin/
doc/en.8859-1/article/faq/printing-trouble/
doc/en.8859-1/article/printing-for-users/
--
Wolfram Schneider <wosch@freebsd.org> http://wolfram.schneider.org
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?19990523130305.01354>