Re: Bug#144456: ITP: qref -- debian quick reference.
On Sun, May 05, 2002 at 12:35:31PM -0700, Daniel Quinlan wrote:
> I realize I'm only being asked about the post-installation directory
> structure of your documentation, but I'll take the liberty of commenting
> on a few other things as a Debian user, only bear in mind that I'm
> coming into the discussion just now.
Will do :)
>
> Javier Fern?ndez-Sanguino Pe?a wrote:
>
> >> - 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)
>
> Do you mean source packages or .deb packages? Either way, this is a
> problem for installation and development of Debian when a network
> connection is not handy or is too slow to be desirable.
Yes. It was badly phrased I meant source packages.
>
> It's also a problem that CVS may not always be in a usable state. I
> don't even think this is desirable for source development in all cases.
> What if someone wants to customize documentation for their local site
> against, for example, the version that came on their CD-ROM.
>
Well. That could really depend, but some documentation that is
more "stable" could be provided in the package but synched with the CVS
(i.e. the package could do a 'cvs update' on debian/rules build). I cannot
stress how much the need for all the documentation (regardless of format)
to reside in the CVS. If this was not the case we could not provide:
1- automatic extraction of information on the documents to make a database
of documents for publishing in w.d.o/doc automatically (not currently
done) along with versions and translations
2.- automatic generation of formats for publishing on w.d.o
3.- automatic generation of formats for publishing in f.d.o (and on
release, on the CDs)
> Makes sense.
>
> >> - 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
>
> I don't think you want "/usr/share/doc/package_name-<language>/".
I meant that, since the package's name for a translation is
package_name-XX there should be a /usr/share/doc/package_name-<language>/
with its copyright/changelog (per policy). However, it would *not*
contain the documentation, as you say below:
>
> I think you want "/usr/share/doc/<language>/package_name/" and/or
> "/usr/share/doc/package_name/<language>/". If both, then one is a
> symbolic link to the other.
I suggest both, with /usr/share/doc/<language>/package_name/
being the main place (i.e. no symlinks)
> Would a good interface for users would be something like this? Have a
> top-level documentation i18n package which asks the user on installation
> for a prioritized list of languages. Someone could then say, I want
> "all of es fr en" or "es with en only as fallback", etc. I still think
> you want to download each translation separately, though.
That is a nice idea but we do not have a proper way to do this.
Maybe this "feature" could be introduced in a package management GUI as a
specialised "documentation" search. That is, this is not a functionality
that, in our layered model, either dpkg or apt should provide. Maybe in a
GUI, with a "Documentation search" along with "Package search".
>
> I would be very happy to accept a proposed patch to FHS (and it would be
> fastest if someone from Debian could contribute it). I would recommend
> using the above plus the /usr/share/man specification as a starting
> point.
Ok. Lets see if we get to a consensus. That would also mean
changing http://www.debian.org/doc/docpolicy.en.html (updating it)
and probably introducing it into the main Debian Policy (run!).
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: