Re: strange behavior of dh_dhelp
Marco Budde <mbudde@sms.antar.com> wrote:
> ROTFL, why should I change dhelp to support a broken file format?
Can you give a short summary where the doc-base format is broken?
Sorry, I didn't read debian-doc so I didn't know what the problem is.
> Please tell me what for do we need doc-base? We need a file format
> and not a converter!
As far as I can see, the doc-base format described in
/usr/doc/doc-base/doc-base.html/ch2.html#s2.1 is a file format. Okay,
it could be specified more accurate, but it seems that most people
understand what is meant (on my system I find 2 packages supporting
dwww and dhelp directly, 7 packages supporting dhelp only, 17 packages
supporting dwww only, and a great majority of 64 packages supporting
doc-base). So the package maintainers have spoken: doc-base is an
accepted "standard".
> Of course the first solution is a lot of better. But how should we
> solve problems when the authors are not interested to find one file
> format :(?
That's a bad situation, sure.
Maybe you could write an alternate documentation and offer it to
debian-policy? I think, that the policy should define the "official"
format. The actual situation is somewhat problematic, because
everybody does what he personally prefers. That's why doc-book (the
only definition, which looks like a standard) is used as the standard.
> Why is doc-base a generic format? It#s as generic as the dhelp/dwww
> formats.
doc-base supports other formats than HTML.
> In fact the format has got a lot of disadvantages.
What explicitly?
> RR> > Why is dhelp broken?
> RR> Because it doesn't support /usr/doc symlinks in the /usr/doc
> RR> tree when the .dhelp file (created by a doc-base file) mentions
> RR> the real (/usr/share/doc) path.
> Example, please.
Take xfig-doc. This package comes with documentation in
/usr/share/doc/xfig-doc/html/ and a symlink /usr/doc/xfig-doc pointing
to /usr/share/xfig-doc.
/usr/share/doc-base/xfig-doc says:
Document: xfig-doc
Title: XFIG Users Manual
Author: T.Sato and Brian V. Smith
Abstract: This manual explains the interactive drawing tool xfig,
which runs under the X Window System. It explains how to start and
use xfig, helps you with some examples and informs you about the
technical issues of this program.
Section: Graphics
Format: html
Index: /usr/share/doc/xfig-doc/html/index.html
Files: /usr/share/doc/xfig-doc/html/*.html
This creates the following /usr/share/doc/xfig-doc/html/.dhelp:
<item>
<directory>graphics
<linkname>XFIG Users Manual
<filename>index.html
<description>
This manual explains the interactive drawing tool xfig,
which runs under the X Window System. It explains how to start and
use xfig, helps you with some examples and informs you about the
technical issues of this program.
</description>
</item>
And adds this document to /usr/share/doc/HTML/graphics/index.html:
<DT><IMG SRC="../../dhelp/text.gif"> <A
HREF="../../xfig-doc/html/index.html"><FONT FACE="Helvetica,
Arial"><B>XFIG Users Manual</B></FONT></A><P></DT>
<DD>This manual explains the interactive drawing tool xfig,
which runs under the X Window System. It explains how to start and
use xfig, helps you with some examples and informs you about the
technical issues of this program.
</DD>
But it doesn't add the document to /usr/doc/HTML/graphics/index.html
which is the primary documentation path for potato (according to ctte).
> RR> Why do you mix the speed of install-docs and dwww here?
> Because install-docs slows down the speed of dhelp :(.
What speed are you talking about: speed of installation or speed of
browsing?
> RR> > Because some authors are not interested to solve problems
> RR> > :(. We don#t need something like doc-base.
> RR> When I read the second sentence, it seems that you're talking
> RR> about yourself in the first one =;-)
> Why? What for do we need doc-base?
I'm not sure, whether we need doc-base or any similar format, but
doc-base is there, and most packages use it. So I don't see why we
should stop using it now. You can see on /usr/share/doc which
problems are implied by changing standards, so if you want to change
from doc-base to something other, give us a smooth migration way
first.
> RR> So why not use doc-base as this one file format?
> Why? doc-base has been developed later that dhelp/dwww
So why use dhelp, it was developed later than dwww. This is no
argument.
> and it#s useless.
It is heavily used. So it isn't completely useless.
> So why should we move to it#s file format? This makes no sense.
Maybe you missed the facts. We already moved to doc-base format, so
if you don't like it, you have to give us a way to move to some
different format now. Maybe it was a fault to change to doc-base, but
that's history. If you want to change this now, you have to give use
some migration path.
> RR> As far as I can see doc-base is a little bit more flexible than
> RR> dhelp (the latter only supports HTML and no other
> dhelp supports all formats.
I cannot see this in /usr/share/doc/dhelp/dhelp.html. There you are
only talking about HTML:
<linkname>
This short text appears as link text in the index. This is
typical the filename without the .html suffix.
^^^^
<filename>
The filename of the HTML file with a path relative to the .dhelp
^^^^
file. If your document is called /usr/share/doc/dhelp/test.html
and the .dhelp is installed in /usr/share/doc/dhelp you must use
test.html.
> And doc-base has got a lot of disadvantages: for example absolute
> file names, where dhelp uses relative file names like the html
> format does.
Ah, I see the problem. But is it really a problem? In combination
with dwww this gives us the chance to access /usr/doc and
/usr/share/doc files, so it may have some advantages, doesn't it?
> RR> doc-base is widely used
> In fact a lot of packages don#t use doc-base, dhelp or dwww.
As you can see on my little statistic (only for my local system)
above, the great majority of packages use doc-base.
> example the libc maintainer closed such a bug report without adding
> support for these programs.
I don't know the facts of this, so I don't want to decide what happend
here. But when a maintainer closes a bug which is still existing you
should discussion this with the maintainer and bring the discussion to
debian-devel if necessary. The problem here is, that our policy
doesn't mention what documentation system should be used, so you have
no right to require a package supporting dwww, dhelp or doc-base.
This should be changed, maybe with a different, but optimal, file
format.
> No. We need a decision: which one is the *main* doc directory. Which
> one should the user use. At the moment I would suggest
> /usr/share/doc.
The decision was done by the technical committee and the main doc
directory for potao is /usr/doc. This isn't already in the policy but
it will be there before potato is released. No further discussion
about that point.
> RR> the doc-base and .dhelp files point to the real location in
> RR> /usr/share/doc,
> .dhelp does not point to this directory. Here you see one advantage
> of my format: dhelp uses relative file names. In fact you could add
> the same .dhelp file to both: /usr/doc and /usr/share/doc.
The .dhelp file is available in both directories, because there is a
symlink available. But it is only included in the
/usr/share/doc/HTML/ index file, but not into /usr/doc/HTML/. Maybe
install-docs should call dhelp_parse_fsstnd in addition to
dhelp_parse? But at least "dhelp_parse_fsstnd -r" should find the
packages which are available in /usr/doc via symlinks.
> RR> while the files are also accessible via the symlink as
> RR> /usr/doc/<package>.
> One again: they are *not* accessible via these symlinks!
They are.
> This may work sometimes but not always -> hack.
ctte decided, that this has always to work. If it doesn't, this is a
bug in the package.
> A good configured http daemon will not follow these symlinks.
So debian has to be come with badly configured http daemons for
/usr/doc. The decision was made, that it has to be done this way.
You told me, that you don't like endless discussions, you stop
discussing this any longer but simply accept the ctte decision.
> RR> some work around for this, but this should be possible with some
> RR> Perl or Shell knowledge.
> dhelp is a offline system. dhelp doesn#t convert things during
> runtime like dwww does.
It's much easier than I thought in the referenced mail. Simply do the
following:
- Replace dhelp_parse by dhelp_parse_fsstnd (the only entry point for
documentation in potato is /usr/doc).
- Fix dhelp_parse to follow symlinks from /usr/doc/<package> to
/usr/share/doc/<package>.
Then all documentation is available from /usr/doc/HTML/index.html
(partly via symlinks). This works for local file access as well as
via HTTP, if the server supports symlinks (which the server should
already support, because there are many symlinks to follow in /usr/doc
for a long time (long before the FHS transition was planned)).
> RR> No problem when you see /usr/doc as the one and only directory
> RR> for accessing the files.
> ??? But we use /usr/share/doc. Read the policy.
The technical committee decided to go a different way. Let's quote
http://www.debian.org/Lists-Archives/debian-ctte-9909/msg00023.html:
Short form:
When moving to FHS, we need to provide /usr/doc/<package> ->
/usr/share/doc/<package> symlink for backwards fsstnd compatability.
The policy doesn't implement this decision at the moment, but that's a
bug in the policy, which hopefully will be fixed soon.
> RR> The documentation of every package should be available as
> RR> /usr/doc/<package> in potato (this will change in the far
> RR> future, but now we are working on potato).
> Great and the next Debian release will have the same or even more
> problems.
No. See the complete proposal in
http://www.debian.org/Lists-Archives/debian-ctte-9908/msg00038.html:
1. Policy 3.X mandates that packages that move the docs to
/usr/share/doc must provide a compatibility symlink in /usr/doc.
This shall allow packages to incrementally move to policy 3.X,
while providing compatibility with older systems.
(/usr/doc/package symlink is handled by package)
Thus, potato ships with a full /usr/doc/ (some of which is symlinks),
and a partial /usr/share/doc.
2. Post potato, we continue the transition, with the symlinks in
place. Before freeze, we file important bugs against any
package that has not been moved over (in one and a half
release periods, we may be actually able to accomplish this),
with NMU-fests to bring over the others.
Thus, potato+1 (woody) ships with a full /usr/share/doc, and a
/usr/doc full of symlinks.
3. At a later date, another policy (say, 4.X) shall ask for
packages to no longer provide the link (and possibly remove
links from /usr/doc). We can also provide a script (possibly
in base-files postinst) that rm's symlinks from within
/usr/doc. woody+1 may ship with such a script. (there was a
proposal as well that potato+2 (woody+1) ships with just the
prerms, and not the base file script, and potato+3 ships
with the base-file script, but I am not sure this long a
reversion period is required).
No dependency on this base-files shall be required, since they shall
work with or without a symlink in /usr/doc (and /usr/share/doc shall
be fully populated by then).
> I don#t like such hacks.
Nobody really likes them, but they are the only way to realize a
smooth transition. One of Debians primary goodies is, that you can
upgrade every single package without problems as long as you follow
the dependencies. So many people only upgrade some packages but not
all at the same time (and don't forget, that it is nearly impossible
to rebuild all packages with /usr/share/doc before potato is released)
and this shouldn't break the systems. So a hack like the above is the
smallest evil.
> In fact I don#t understand why we should not simply move our
> documentation to the new directory.
Because this breaks consistency of the systems, which have
documentation distributed over two directories. As you can see at the
actual situation with dhelp, this is really annoying.
But please stop this discussion, we had it for many weeks in
debian-policy other mailing lists without a compromise. So the
technical committee was asked to find a decision and they did so. It
doesn't help Debian if you start this discussion again or if you try
to change it by simply ignoring it.
> RR> That's not true. At least apache supports following symlinks
> RR> when you activate this with "Options FollowSymLinks" in
> RR> access.conf for the /usr/doc directory. Other web servers will
> RR> support this in a similar way.
> Will apache follow symlinks in /usr/doc or symlinks to all possible
> files?
As far as I see, the latter.
> Using this feature could course real security problems.
But it is the default configuration of apache in slink and also in
poato.
BTW: The real problem is, that the documentation is automatically
accessible world-wide and not only to local users. It isn't optimal
that everybody can see what packages are installed here and in which
version.
> And of course there#re other http daemons than apache.
There are also http daemons which don't support CGI. But you still
provide /usr/lib/cgi-bin/dsearch in the dhelp package. This isn't a
real argument.
If someone uses a http server which doesn't support symlinks, he's
free to switch over to apache, if he wants to read the documentation
via HTTP.
Tschoeeee
Roland
--
* roland@spinnaker.de * http://www.spinnaker.de/ *
PGP: 1024/DD08DD6D 2D E7 CC DE D5 8D 78 BE 3C A0 A4 F1 4B 09 CE AF
Reply to: