Re: doc directory of the web pages
In article <[🔎] 19981125115159.X430@debian.org>, "James A. Treacy" <firstname.lastname@example.org> writes:
> You have brought up the two items I was interested in: structure and
> document readiness. As far as structure is concerned, it would be
> helpful to those writing documentation if the location of documents
> is consistent between the different areas that use them, ie. the
> archive, debian web pages and /usr/doc/ on machines at home. With
> that in mind the location of Debian documentation was following the
> structure of /doc in the archive (there seems to have been some
> divergence over time though).
Good point. Here we start to see the start of the debian developer's
documentation guideline document, I guess. Suppose that the <package>
is the kicker, so we say:
* install the package and get /usr/doc/<package>/<package>.html
(wouldn't /usr/doc/<package>/index.html be better?)
* also find it at http://www.debian.org/<package>/<package>.html
(wouldn't http://www.debian.org/<package>/index.html be better?)
* find devel copy at <DDP-ROOT>/<package>/<package.html
> I would much prefer it if the doc people told us how to organize the
> doc/ directory on the web site. Links from sections that need to
> reference them can do so by pointing to the location under doc/
> . Also, there is at least one link from a Debian doc into another
> one. That link is currently broken. Having a known structure to the
> doc/ directory should alleviate that kind of problem.
What do you think abou the above? Seems simple and transparent and
all that. I like doc/<package>/index.html, and the DDP install system
can be made to do this automatically pretty easily (not quite yet).
> As far as document readiness goes, isn't this one of the uses of
> branches in CVS? Development branches are split off and when a new
> release is desired, you simply merge branches. Those only interested
> in the stable branches can simply follow those.
Yes... I guess I"m lazy. I guess I shoudl branch when I start a
little unstable branch, and then merge it back into the main branch
for a "release version" ? Never really tried it...
>> The final issue is that if we're going to do this, we might as well
>> propogate it into http://www.debian.org/devel/ as well, since many
>> manuals can go there also.
> As mentioned above, this is unnecessary. We can just link the
> location under the doc/ directory.
Yes, good idea, more consistent; see above!
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>