[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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: