Re: Notes for DDP writers
On Mon, Feb 15, 1999 at 11:06:15AM -0500, James A. Treacy wrote:
> > CVS admins: can we arrange that all Debian documentation gets included
> > somewhere 'closer' to the web CVS tree?
> >
> > For start, I'm asking:
> > - to copy everything from the directory /cvs/debian-doc/ddp/webpages/
> > to a new directory /cvs/webwml/webwml/doc/ddp/
> > - can I (account is 'joy') get write permission in /cvs/webwml/webwml/doc/
> > directory.
> >
> I see no reason for the CVS to be moved.
The directory mentioned is *not* CVS location of debian-doc documents,
but only the DDP web pages.
> Even more, different people are
> working on the docs and the web pages so this would actually inconvenience
> many people. The important thing here is that the documentation be
> made available in a consistent way.
I said 'for start'. We still need a consistent way to access all the docs
in their *current* locations.
Now we have www.debian.org/doc/index.html, and www.debian.org/~elphick/ddp/
that aren't very well connected or conistent. And there are more places
with such links, like /devel. I meant to collect all these links, in few
WMLs with recognizable web layout under /doc. As a first step.
> There is no reason to convert to using wml. Don't make this more work than
> it needs to be.
I have not proposed converting *all* debian-doc pages to wml,
not at all. Just the index files of DDP, that would actually
become a part of the web site, as they should be after all.
> From the web pages point of view, we are simly looking for
> a doc directory that has a well defined structure and pages that can be
> served using content negotiation. Once that is set up, you don't need to
> do anything until new docs are added or docs are rearranged.
>
> The rest of the web pages can then create links into the doc directory
> as needed. We do need to be notified as to the status of different docs
> (developmental versus stable) so we know whether to link them.
>
> The webmasters don't have the time to delve into every aspect of Debian - this
> is a big project after all. That's why we need someone to say 'mirror this
> set of files from here which are content negotiation ready' and 'the following
> list of docs in that directory are ready for public release'.
What we could now, is to create the preffered directory structure under
/doc/, and making a small symlink farm ( :) ) in these directories that
would point to the current locations of debian-doc documents.
That would enable all the stuff you are saying, without actual moving
of the HTML documents from their current locations (we'd do that later).
Lets say first:
/doc/ -- the toplevel index files
stable -- index files for 'stable' docs
tutorial -- index.$LANG.html -> symlink to $LANG/index.html
en -- \
fr --- language specific versions of docs
de -- /
...
policy
...
...
unstable
tutorial
...
policy
...
...
The documents in 'stable' directory would be picked either by the version
in current stable release, or by stability of the doc. We could rename
these to 'finished' and 'current' or something else.
That way, when /devel/index.html would need to reference Debian Policy
document, then you'd point it to http://www.debian.org/doc/stable/policy
(or relative link), and not have to worry, since the debian-doc group
would actually pick the doc to put on that location(s).
You'd have to give us some time to work out the actual implementation.
Any opinions on this are welcome, and encouraged.
--
enJoy -*/\*- http://jagor.srce.hr/~jrodin/
Reply to: