Re: Bug#144456: ITP: qref -- debian quick reference.
On Fri, May 03, 2002 at 08:27:02PM -0700, Osamu Aoki wrote:
> Hi folks,
>
> We (me and Ramakrishnan) need help from you on "Best Practice for
> Documentation Packaging."
(...)
Well. There is currently none, as you have guessed.
> developers-reference. They just generate only one packages for all the
> languages.
Not good. IMHO, we could get to the problem of locales (that was
"fixed" with apt-localepurge)
>
> My observation are:
> APT-HOWTO seems to have one source with many language specific .deb
> packages. But file name convention for language is totally unusual.
> I think separate language .deb package is a good idea.
Why do you say filename convention is unusual?
>
> FAQ seems to have separate .deb and souces for separate languages.
As a matter of fact, doc-debian-es contains the FAQ translation
(which is not in CVS), and doc-debian-fr contains some documents but *not*
the FAQ translation. Also, there are no russian or polish doc-debian-XX
packages (but arre in CVS)
>
> Also install location for html seems to vary.
>
Yes. Some include them in the same directory as text files
, some in a separate directory and some as a tar.gz
> Any policy to follow?
>
None currently :(
> Or it is anarchy or Javier or Josip are thinking something.
>
Well. I do have ideas, have not expressed them in public.
Here we go (out of my head):
- all documentation that is Debian specific should be in the DDP CVS
(that is reasonable, there is currently one exception: installation
manual, but seems like a reasonable exception to me)
- documentation packages should *not* include the documentation, they
should just do a "cvs co" from the DDP CVS (see harden-doc for example,
or the java-common package)
- (if the layout for languages in the DDP CVS is homogeneus -sp?- this
can easily be done) each documentation package creates one package for
every language that the documentation is available in.
- the packages publishes the documentation using standard doc-base/dhelp
stuff
- documentation is always available under /usr/share/doc/package_name
/usr/share/doc/package_name-XX (XX is the iso reference for a given
language) contains a symlink to the documentation there. Translations
(I assume English is *always* the reference language, per policy)
are under /usr/share/doc/package_name/XX
Now, there is also an interested (but unused) idea in the doc-debian-fr
package which makes /usr/share/doc/package_name/XX a symlink to
/usr/share/doc/LANG/XX/package_name
This could be useful if packages provided *all* the translations to be
able to remove unuseful translated documentation (similar to cleaning the
locale with localepurge). *But* at the same time provides an easy way for
users to find translated documentation (since everything under
/usr/share/doc/LANG/es/ is, for example, in spanish).
These layout could be used, not only by Debian's documentation but also by
other packages which include documentation which might be translated (for
example, if apache-doc or postgresql-doc did so which IIRC is not the
case).
The layout under the directory is IMHO simple: text files in the
same directory, HTML under a subdirectory name 'html'. HTML files should
not be provided as tar.gz's to be able to browse with dwww. If
documentation is provided in other formats for easy printout (ps, pdf or a
single HTML file) they should be provided in another package (this files
tend to double the package's size....): package_name-XX-printout (??)
Uff.. (done)
Well, those are only some ideas out of the top of my head (no more time
now since I have an appointment in 5')
Regards
Javi
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: