Re: Documentation co-ordinator
"Oliver Elphick" <olly@lfix.co.uk> writes:
> Adam P. Harris wrote:
> >> 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.
Yes, although enabling access to the SGML sources is crucial, say, if
the DDP pages are giong to be also a place where editors can grab the
latest SGML (w/o using CVS) and changing that for submitting diffs to
doc. maintainers.
> 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.
Your scheme sounds like it involves a whole lot of scripting work,
etc. To me, that is bad.
> If you already see clearly how it should work, please set out the
> details...
Here's the scheme. Use your heirarchy, but under
./manuals/doc-base -- checked out with, i.e., cvs -d /cvs/doc-base
doc-base, then run 'cd doc-base ; make'
Do the same with every subdir. Allow the repository to be either on
cvs.debian.org, or whereever. So basically, you have to *require*,
whenever you can, that documenters point you to where the cvs
repository is (or provide them with one if they don't have one), and
mandate that they should have a Makefile on the top level, such that
you can type 'make' and get all of the derived documentation that you
want (HTML, PS, ASCII).
> >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.
Well sgml-base contains our SGML sub-policy. Is that covered?
doc-base contains Documentation sub-policy.
> 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.
Well, the DDP home pages also had a number of manuals for documentors
too, i.e., how to write manuals for Debian, Developers Reference, etc.
I assumed you were continuing to carry that.
> 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.
Yes, I don't want to give you more work than you already have. Nor do
I think we need to think of this as a grand documentation scheme. I'm
trying to make it easier on you!
> So, if anyone has contributions to make, please start typing. I hope
> to be ready to receive them within a week.
Oliver, these ideas are my contributions right now. ;)
--
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: