Re: Documentation co-ordinator
Adam P. Harris wrote:
>"Oliver Elphick" <olly@lfix.co.uk> writes:
>> 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.
If that is required, we can provide the current version in a separate
sgml directory.
>...
>> 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.
I think I agree. However, I would not go so far as to call it a scheme,
yet; I tend to think with the keyboard...
>
>> 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).
So a single make on cvs.debian.org will produce up-to-date documentation
in all the published formats? It sounds good!
>...
>> 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.
I hadn't thought about it. Part of the current exercise is making it
clear what the scope of the project is. Where packages contain
documentation, we will have to depend on their maintainers' cooperation
in integrating everything.
>
>> 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.
Yes; but these are generally mature, whereas the administrator's and users'
manuals are not. Furthermore, these are the ones most urgently needed
by refugees from MS. Therefore I should like us to focus on producing
this integrated documentation for users and administrators. At the same
time we can incorporate existing documentation into the scheme.
>
>> 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!
Thank you!
--
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: