Date: Wed, 26 May 1999 11:34:15 +1000 From: Greg Black <gjb@acm.org> 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: <19990526013416.12841.qmail@alice.gba.oz.au> In-Reply-To: <19990524100236.V12185@lehman.com> of Mon, 24 May 1999 10:02:36 %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> <19990523023158.105.qmail@alice.gba.oz.au> <19990524100236.V12185@lehman.com>
next in thread | previous in thread | raw e-mail | index | archive | help
> > [Re "articles" and "books":]
> > 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.
>
> Disagree. Here's why.
>
> The organisation *within the repository* is (or should be) of zero
> interest to the end user of the documentation. There's no reason why the
> directory hierarchy within the repository, and the directory hierarchy of
> the installed documentation should map to each other one to one.
>
> [...]
>
> For example, something that lives in the books/printing directory might
> have
>
> CATEGORIES= books sysadmin printing mswindows
>
> in the Makefile, indicating that the formatted documentation should be
> installed in to /usr/local/share/doc/FDP/{books,sysadmin,printing,mswindows}
> directories because
>
> 1. It's a "book"
> 2. Printing is a "Sys Admin" topic.
> 3. Printing is deemed to be important enough to have it's own top level
> category as well.
> 4. It explains how Windows hosts can print to printers attached to
> FreeBSD boxes.
>
> This gives the end-user much more freedom when it comes to finding the
> documentation they need.
I have no problem with this -- but it was not spelled out in the
proposal that I was commenting on, hence my repeated attempts to
have the problem that I saw addressed.
I am quite happy to see semantic distinctions internal to the
documents determining their location in the source (where they
are accessed by the documentation maintainers), so long as the
organisation that is visible to users allows them to find things
by criteria that make sense to those users. Your latest answer
indicates that this will be done. Thanks.
--
Greg Black -- <gjb@acm.org> or <gjb@computer.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?19990526013416.12841.qmail>