Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 23 May 1999 12:31:58 +1000
From:      Greg Black <gjb-freebsd@gba.oz.au>
To:        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:  <19990523023158.105.qmail@alice.gba.oz.au>
In-Reply-To: <19990520232510.A54603@catkin.nothing-going-on.org>  of Thu, 20 May 1999 23:25:10 %2B0100
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> 

next in thread | previous in thread | raw e-mail | index | archive | help
[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.

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.

I've made my point and won't pursue it further.

-- 
Greg Black -- <gjb@acm.org> or <gjb@computer.org>
-- 
BSD Unix software development, documentation and consulting.
No Microsoft or Microsoft-compatible products used or supported.



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?19990523023158.105.qmail>