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

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*" 
> and 
> "Other DDP documentation might be provided in other formats (even if
> sgml and docbook are preferred). Preferred format for slides is MagicPoint.
> >      * 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

> >        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.

> >    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 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.
> 	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

> 	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 :-)

~\^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: