On Mon, Oct 14, 2002 at 02:33:58PM -0700, Osamu Aoki wrote:
>
> I bcced to people who had opinion on this isuue previously. (sorry
> SPAMing you to get extra attention. Response can be only to the list.)
Yes. I promised to have something quite a long time ago. Real Life
(tm), however, has gotten in the way.
>
> * All manuals of the Debian Documentation Project (DDP) will be released
> under DFSG-compliant licenses, most likely GPL.
We have to tackle the issue of documentation licenses. Such as the
GFDL, which are more appropiate than the GPL in some cases (not all
documentation). This should be discussed at debian-legal, however.
>
> * We'll use the following directory structure in the filesystem and on
> our servers:
You are using <packagename> all over the place. I do not agree
with it, it should be <manualname>. Also we should say how are
manual-names assigned. Does anyone with CVS write access create whatever
he likes? (that's the situation now which leads to some confusion in some
file naming). There should be a convention on how to select (or ask for)
manualnames (which should be used for package names). Example: use '_' or
'-'?
>
> Filesystem (installed by Debian packages):
> Index page for the archive contents (optional, auto generated):
> /usr/share/doc/Debian/<packagename>/index.html
> HTML:
> /usr/share/doc/Debian/<packagename>/<packagename>.<LANG>.html
(...)
We've discussed this before. I do not agree with having
all language files in the same directory, tends to clutter directories and
might lead to confusion. It should be:
/usr/share/doc/Debian/<packagename>/<LANG>/<packagename>.html
also
/usr/share/doc/<packagename>-<LANG>/html
should point there (as a symlink). Since we do need to have (per policy)
the <packagename>-<LANG> directory if we are going to make packages per
language.
Note: having /usr/share/doc/Debian/<packagename>/<LANG>/ also
helps if we want to help people use locale-purge for documentation too.
> WWW server (stable version):
> http://www.debian.org/manuals/<packagename>/index.html (optional)
Agreed here. We want content negotiation :)
>
> CVS server (DDP, SGMML source):
> CVSROOT=:pserver:anonymous@cvs.debian.org:/cvs/debian-doc
> Repository: ddp/manuals.sgml/<packagename>/
We need to acknowledge other documentation that "belongs" to the
DDP, including:
- articles (there is a ddp/articles area)
- slides/presentations (no area yet but will get created)
- manpages...
>
> Debian package:
> Source package: (SGML source only)
> <packagename>_<version>_all.tar.gz
> <packagename>_<version>_all.dsc
> Binary package: (4 generated formats, plain text, HTML, PS, and PDF, only)
> <packagename>_<version>_all.deb (install all languages)
We *cannot* install all languages in the proposed format or you
are going to have conflicts all over the place (since they are going to
put the same files in the same places). <packagename>_<version> should be
avoided. We should have <package>-<LANG> only IMHO (and English be
<package>-en). If you want an "english-centered" view, then
<package>_<version> should be the English version *only* and <package>-en
should Depends: on it.
> <packagename>-<LANG>_<version>_all.deb (for each language)
See here. If we have a <LANG> then we need a
/usr/share/doc/<package>-<LANG> and some users will look there first.
>
(...)
> * We use SGML as the source format. Currently, SGML format compatible
> with debiandoc-sgml tool chain is chosen to be our document format.
> This source file format is expected to move toward DocBook-XML in the
> future when infrastructures are ready.
>
> The other options were: LaTeX, HTML, texinfo, and several other minor
> formats. These are not accepted anymore.
I do not agree here. You might need to use LaTeX for some other
(non manuals) format. We need to decide also which prefered format to use
for slides. You are talking about the whole DDP project or the Manuals? If
so you should change it into:
"We use SGML as the source format for *manuals*"
and
"Other DDP documentation might be provided in other formats (even if
sgml and docbook are prefered). Prefered format for slides is MagicPoint.
>
> * We thrive to publish documents in 4 formats from SGML source.
^^^^^
Thrive? Should it be "try"
(..)
> index.<LANG>.html as the starting page but these are discouraged
> practices since they hide other files.
I don't understand this.
>
> Bug reports are encouraged to provide the diff file to the SGML source
> but the diff file to the generated plain text file is accepted by the
> document maintainers. This means that users do not have to learn SGML
> to submit changes to our documents.
¿? You should first tell in the policy how/when/where to submit bugs. If
we have packages for the source/languages you should say:
"Bug reports in documentation include:
- errata
- new information to be included
- request for clarification
- whichever other comments the user might think useful
As for packages bug reports for documentation should be priorised, request
for changes should always be 'wishlist' (unless its an errata).
Documentation maintainers are subscribed to the bug tracking system of the
packages generated with the documentation they maintain (even if they do
not maintain the packages themselves) so they will receive whatever bug
reports are sent to them. Please do not send bugs regarding documentation
do the debian-doc mailing list unless you want to discuss some issue
before submitting a bug report. Also avoid sending bugs to the
documentation's maintainer mail address, since the Bug Tracking system is
better suited to track bugs. Otherwise, your requests/suggestions might be
lost if the document swithces maintainers. You can also, using the BTS,
see when the bug is fixed and a new document version is released.
In order to submit bug reports readers are encouraged to send diff files
against the SGML/XML sources. If you are not sure on how to make diff
files, please submit bugs indicating clearly the location of the errata
(usually citing text in the document) Otherwise it's more difficult for
documentation maintainers to determine what exactly needs to be fixed.
It is recommended to send translation-related bugs against the
<package>-<LANG> package instead of the package itself."
Better?
>
> * Every Debian document will have a single person listed as the Author
> and optionally a single person listed as the Translator.
More: Authors must be subscribed, at least, to the BTS for the source
packages and the original language package of the documentation they
maintain if they are not the maintainers of those packages themselves.
Translators must also be subscribed to the BTS for the translated package
versions.
> Please send all comments, criticisms and suggestions about these web pages
> to the mailing list of the Debian Documentation Team.
>
Some issues that have not been tackled in this document which I
wanted to include too where:
- how DDP documents are published in the FTP area (/doc) and thus in the
CD-ROMS (iso images).
- how to manage automatically state of Documents (we need a database to
follow when translations are out-of-date as well as to determine when
documents are under development)
- new WNPP tags for documentation: ITD (intend to document), RFD (request
for documentation), OD (orphaned documentation)
- how to automatically extract CVS information to close bugs when a new
package gets created
- who should make the packages? should they be made automatically using
cvsbuildpackage on a cron job?
IMHO we should create an infraestructure for documentation
maintainers to just use CVS and have packages built the same way we are
compiling them in the WWW. We also need to have an infraestructure so that
doc maintainers and translators can handle DDP files as we currently do
for wml files (in the website), gettext files, debconf files...
This obviously does not mean that it needs to be included *now* in
the policy. But it should in the future.
Ah! And we should say which documentation is handled by the DDP
team. Are manpages in Debian handled (IMHO they should)? Are TexInfo
files? Are GNOME/KDE manuals?
You have your commments, pardon me for not doing the doc-policy
document myself.
Javi
Attachment:
pgpcdFKxQIesr.pgp
Description: PGP signature