Hi, Javi and Adam.
I was waiting for Javi's response :-)
On Tue, Jan 28, 2003 at 10:58:50PM +0100, Javier Fernández-Sanguino Peña wrote:
> > Um, why start there? Right in 1.1, Scope, we read "all your
> > documents belong to us". We need to get the new, restricted scope
> > down in the policy under section 1.1.
Adam, thanks for pointing out. I think as follows:
Although Debian Documentation Project (DDP) wishes to improve all
aspects of documentation on Debian, its current focus activity centers
around providing well organized documents addressing *Debian specific
issues*.
Current Policy Proposal regarding DDP will aim to define consistent
rules for these documents provided by DDP.
...
> Please feel free to revise it. It's in CVS, if we hadn't want
> people to change it we wouldn't have added it there (as some DDs do, see
> below)
I suggest to use branch until all Adam's writing are done. Then we
review them. If everyone generally agree on most portion of new
version, we switch branch. (I anticipate not much issues.)
> > Personally I think in view of our revised ideas about our scope, the
> > idea of /usr/share/doc/Debian becomes a little dubious. Not all
> > Debian documents are covered by the DDP policy.
1. Non package name directory in /usr/share/doc/ should contain upper
case (de facto standard)
2. HOWTO, RFC, ...: good examples exist for this type of centralized
directory for easy access by file browsers (mc, w3m, ...).
> No. That's the main point. If it's a Debian document why on earth
> is it not under the DDP CVS. I'm sure I'm stepping on many people shoes,
> many have been handling their documents in other (different) ways, such as
> the Installation manual, the Developers Reference...
>
Javi, the only way to get these existing documents to come under DDP is
not by forcing through policy but by coercion. I think we successfully
advocated for "Installation manual" but we still need to convince
"Developers Reference" author. I mean Adam needs to be coerced ;-)
I think if we start establishing nice consistent infrastructure, people
will join. Remember, Debian is volunteer project and coercion plays
very important role. I think it will be nice to have Developers
Reference in CVS but it is not critical at this moment. We should
focus on file location of installed package and choice of file/package
name, ...
Let's define DDP as the document in CVS and policy to be
written only for the document in DDP at this stage. If external
documents follow part of this policy, it is good too. I think it is
premature for us to tell non-DDP people what to do when we have not
finished our own work yet. We can expand scope of DDP in the next step.
The only exception is translation. If original is in DDP CVS,
translation shall be in DDP CVS with version tracking feature.
> Take a look at Bug #64278 or Bug #118592, or Bug #172482 or Bug
> #106492....
#64278: doc-debian-es: Documents are not provided in the FTP archive
It is fair to ask any translation of DDP document to use our CVS or keep
copy in our CVS.
#118592: Java policy is not in the DDP (nor uses debiandocsgml)
Outside of our current discussion scope for now.
(I think jadetex is fine. Policy needs to have CVS but it can be
outside of DDP. If it is included, I am fine too.)
#172482: /debian/doc does not offer sufficient content
#106492: Find semi-automated way to provide doc-debian-NN info
Once we make DDP CVS consistent and cover all these packages such as
doc-debian and their translation, then we can talk about these. Next
step.
> This separation into multiple "islands" each handled by their own
> DD makes it difficult to have a way to:
>
> - make translations and keep them up-to-date
> - publish documentation on the ftp/web site (both original and
> translations)
> - provide packages for offline reading (for both too)
As far as up-to-datedness of translation, I use bin/doc-check script.
po-debiandoc is also good tool and I am thinking to start using it soon
if I do not move to docbook-xml first. Due to the long nature of DDP
document, translation is best done by dedicated volunteers in my
experience.
In short, translation frame work issues is a complicated issue which is
secondary priority for the current DDP policy proposal. Let us keep it
out side of current discussion scope. For now, we can continue ad-hoc
structure as we have been using :-)
...
> We _need_ a common infrastructure, I can't stress that enough. And
> we need DDs to accept and use that infrastructure, not provide whatever
> they feel is best when it usually is not.
True, but let us keep that as next step for DDP.
> > I guess this raises a point. If the scope of the DDP Policy is DDP
> > documents, there might be items in there that we wish to raise to the
> > level of Debian Policy of Developer's Reference materials (general
> > Debian documentation best practices, not just applying to DDP).
> >
> > I'm happy to incorporate things like this in the Developer's
> > Reference, although I'd like to review the discussions on
> > /usr/share/doc/Debian. We might even be able to share text between
> > the two documents (using CVS and shared included modules).
I disagree, Adam. I do not like having long "shared" module between 2
key documents. Reason:
1. Redundant
2. Unclear separation line between "policy" and "best practice".
Also, this best practice parts of DDP things are too narrow scope to be
in the main text of "Developer Reference". I think it can deserve to be
a part of appendix, though.
> > On /usr/share/doc/Debian/, I'm not sure if it's really necessary,
> > since collection of Debian documentation is already done in a single
> > section in the doc-base registration and things of that nature.
> > Again, pointers to discussion on this list or elsewhere would be
> > appreciated.
> >
> Doc-base is not good enough. Excuse me for saying this, but
> document registration, if not integrated with GNOME/KDE help system as
> a subsystem is not enough. Please look around in /usr/share/doc to find
> stuff. Literally.
I agree, Javi.
> > developers-reference-en
> > developers-reference-fr
>
> This one is preferred. Some DDP documents might be available only
> on a given language and that might just not be English (see the fr/ section
> under manuals.sgml). The broader Debian gets the more documents that will
> be written by non-native English speakers (I believe one such proposal for
> a Spanish document was made a while back).
I got a bug report from a person who installed debian-reference which
depends on all the debian-reference-*. Although he realized later that
the package description was correct, I wonder I should do this or not.
I use following
debian-reference : Install all
debian-reference-en : English original, depends on debian-reference-common
debian-reference-fr : French Translation, depends on debian-reference-common
...
debian-reference-common : common examples etc.
I can not decide which is better :-(
> > If you don't mind some radical surgery, I might be able to go through
> > the document, trimming the scope, and marking sections which should be
> > destined for policy or best practices as appropriate.
Please for DDP-policy.
I want to see developer-reference update proposal too.
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki <osamu@debian.org> Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://qref.sf.net and http://people.debian.org/~osamu
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Attachment:
pgpeQrWF2hrj5.pgp
Description: PGP signature