From: MikkelFJ <mikkelfj-anti-spam@...>
Date: 2003-05-27T07:43:05+09:00
Subject: Re: Project Directory Structure


"Jim Freeze" <jim@freeze.org> wrote in message
news:20030526164554.C60771@freeze.org...

> > I happen to have doc directories already and they contain source
> > documentation. How about 'rdoc' for rdoc directories, or 'browse' for
> > processed documentation in general.
>
> Are your doc directories browsable or do they just
> contain documentation source?

They contain document source, but are human readable. They are intended to
be readable without a special tool. docbook is a bit controversial - I think
it would be better off in in a 'docbook' directory because it isn't really
that readable, or doc/docbook, doc/latex, ...
I have my own format I'm working on called step. It's mostly very readable,
but can be categorized in line with xml-doc, so I guess it would be either
../doc or ./doc/step (in analogy with ./src or ./src/ruby).

> I think this is the stickiest issue. If we use
>
>     doc  # doc source
>     rdoc # rdoc - browsable
>
> Where to you put your browsable source?
>
>     man/  ??

perhaps it should be generalized - it's not really important that the
browsable html is generated by rdoc, so I guess my rdoc proposal isnt' that
clever after all.

../browse/html
../browse/xml (this is browsable xml, as in xhtml, not doc-book).
../browse/man (or ./browse/text)

or replace ./browse with ./view/... or ./help/... or ./online/... or
../read/...
I guess there is no established standard.
'./processed-doc/...' may be more informative.


> > 'examples' are usually listed as 'samples', although I don't know why.
>
> I've seen both. There is also the issue of plurality.
> Let's take a quick vote. Make your choice:
>
>   sample
>   samples
>   example
>   examples

I prefer examples but tend to find samples more widely used, so I won't
argue either way.

Mikkel