Re: docpolicy.html update
On Tue, Oct 15, 2002 at 10:59:58AM +0200, Javier Fernández-Sanguino Peña wrote:
> On Mon, Oct 14, 2002 at 02:33:58PM -0700, Osamu Aoki wrote:
> > * 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 appropriate than the GPL in some cases
> (not all documentation). This should be discussed at
> debian-legal, however.
Yes. GFDL is acceptable as a part of DDP but it does not mix (borrowing
contents) with GPL ones. I do not think it is urgent issue. TBD item.
> > * 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>.
point taken.
> 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 '-'?
This is something we need to explicitly spell out if this "documentation
policy" becomes "mini-policy" like others. But for now, let spell "best
practice". Use '-' as the current best practice, I think.
> > 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.
I knew something like this was discussed and I implemented it. Then
people complained. joey's comment was convincing and that was newer
than your argument.
> Note: having /usr/share/doc/Debian/<packagename>/<LANG>/ also
> helps if we want to help people use locale-purge for documentation too.
There are pros and cons for this. Having all the language in one
directory is more compatible with apache server for HTML.
BTW, FREEBSD does like /usr/share/doc/en_US.?????/.... There are few
ways to do it. All have pros and cons. I think it is most important to
be consistent. This is the only point people differ significantly and I
think you need to convince others (joey, rob). As you pointed out in
private mail /usr/share/doc/ and WWW are separate issue. But
consistency between them are nice. I like argument by joey and reverted
my build to joey's style proposal. (Maybe, you start new thread focusing
on this issue on both d-doc and d-www).
For me, my current one is incremental update to current policy while
yours are total change which you need to convince others.
So update as I proposed and keep discussing your concern. (Acceptable?)
> > WWW server (stable version):
> > http://www.debian.org/manuals/<packagename>/index.html (optional)
>
> Agreed here. We want content negotiation :)
Yes for DDP server but it will be nice to have the same files for
/usr/share/doc/ too. More consistent.
> > CVS server (DDP, SGML 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...
I see. TBD items.
> > 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).
I think there is some misunderstanding here. We *can* install all
languages in the proposed format for each <manualname> without
conflicts. I was not clear what I try to say. Let me try again:
Binary package:
This contain 4 generated formats: plain text, HTML, PS, and PDF.
(No SGML contained)
<packagename>_<version>_all.deb (virtual package to install all)
<packagename>-<LANG>_<version>_all.deb (language specific portion)
<packagename>-common_<version>_all.deb (language independent portion)
> <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.
Yep. That what I do for mine.
> > <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.
That contain changelog.gz copyright and README.Debian. ( I make
README.Debian as symlink to save few bytes)
> > * 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 preferred 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*"
OK.
> and
>
> "Other DDP documentation might be provided in other formats (even if
> sgml and docbook are preferred). Preferred format for slides is MagicPoint.
Yep.
> > * We thrive to publish documents in 4 formats from SGML source.
> ^^^^^^
> Thrive? Should it be "try"
I thought. "try hard to" == "thrive to". (Am I wrong?) Native speakers.
> > index.<LANG>.html as the starting page but these are discouraged
> > practices since they hide other files.
>
> I don't understand this.
debiandoc2html without "-t" option creates starting page
index.<LANG>.html. with "-treference", starting page is
reference.<LANG>.html.
> > 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 prioritized,
> 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 switches
> 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?
Good but this is too long compared with other portion. Some sectioning
to separate from the developer oriented content may be good.
> > * 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.
OK.
> > 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?
TBDs.
> IMHO we should create an infrastructure 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
> infrastructure so that doc maintainers and translators can
> handle DDP files as we currently do for wml files (in the
> website), gettext files, debconf files...
Let's keep bureaucratic overhead minimal. Focus on technical elegance
and practical merits. XML conversion is one to think about.
> This obviously does not mean that it needs to be included *now* in
> the policy. But it should in the future.
Yep.
> 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?
If we get ready, yes. But realistically for near future, let's keep
current document well organized and leave those to whoever working on
it.
> You have your comments, pardon me for not doing the doc-policy
> document myself.
I SPAMed you with copies of the old key postings I saw on the list while
you were away. Have fun :-)
Osamu
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki @ Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://www.debian.org/doc/manuals/reference/ also http://qref.sf.net
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Reply to: