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:[EMAIL PROTECTED]:/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
