Re: Documentation co-ordinator
Adam P. Harris wrote:
...
>This looks good. Try to keep it pretty flat, the structure that is.
>Marcus has a pretty good Debian Docuemntation Heirarchy which you can
>probably use if you like for organization (i.e., replacing the current
>major categories in
>http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-doc/manuals.html). A
>sk
>me and I can shoot you a copy, but Marcus says it's not ready yet and
>will be ready later this week or so.
So send it along when it is ready, please. [But see below.]
>
>> Generated web pages will not be checked in with CVS but will exist in
>> a separate tree, with links to it from the CVS-managed pages. The managed
>> pages will be copied or linked to the web server
>
>This is very unclear to me. I suspect you may be intending to use CVS
>the wrong way. Yes yes and yes! the web pages should be in cvs,
>that's great. But why the links? I would just use 'cvs co' then 'cvs
>update -d' nightly (i.e., from cron), and maybe hide the CVS subdirs
>from Apache serving them up.
I'm thinking that the HTML, text and postscript versions will need to
be regenerated whenever new versions of the SGML files are checked in.
These generated versions do not themselves need to be controlled by CVS.
More permanent pages, such as `index.html', will be checked in and will
refer to the proper locations for the generated pages. The
SGML source need not be referenced directly any more, since it can easily
be checked out to the user's own system.
A cron job will have to run regularly to check for CVS changes and
rerun the documentation build. Since this is a process that could
fail, its result code must be checked before the output is allowed to
replace the current on-line version.
I don't know what permissions DDP will have in relation to the main
web pages, so I don't yet have any definite plans about how
pages are propagated from the repository into the webserver. I do
envisage having a separate directory for each manual, so it could be as
simple as moving that directory aside and replacing it with the newly
generated one. If there is any question of using CGI or the like, it
would have to be co-ordinated with the webmaster.
If you already see clearly how it should work, please set out the details...
>But are you intending to serve up the manuals from CVS? Many manuals
>are already in cvs elsewhere, and/or part of larger packages, such as
>emacsen-common, doc-base, etc. Can you have the directory for each
>manual just be a checked out version of the manual from CVS if
>possible? Even this might be tricky because it might not be trivial
>to check out only the manual and nothing else.
The DDP does not encompass all Debian documentation; in the long run,
it would be a good thing to unify some of the documentation that is
scattered around various packages, but that is not the immediate aim.
Any documentation from other packages would have to be edited before
being incorporated; for the most part, documentation is not in SGML
format, and it will have to be converted before we can use it.
Our present goal is to produce some documentation to give users an
overview of Debian and some basic instruction in how to use it and how
to develop with it. For the intimate details, users will still need to
use man, info, dwww and so on. For now, I propose to work with the
scheme that we have inherited; anyone who has a master scheme to
reorganise everything is welcome to tell us about it and work it out,
whether privately or on the list, but we can't afford to wait for it.
I would like to have all the presently planned manuals ready for 2.1.
So, if anyone has contributions to make, please start typing. I hope
to be ready to receive them within a week.
--
Oliver Elphick Oliver.Elphick@lfix.co.uk
Isle of Wight http://www.lfix.co.uk/oliver
PGP key from public servers; key ID 32B8FAA1
========================================
"Because he himself suffered when he was tempted, he
is able to help those who are being tempted."
Hebrews 2:18
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: