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

Re: strange behavior of dh_dhelp

Marco Budde <mbudde@sms.antar.com> wrote:

> RR> It is always a good idea to use a generic format which can
> RR> automatically converted to all useful formats instead of using
> RR> one special format.

> No, sorry, but this is wrong. Why should we convert files during the  
> installation process? There#re two better solutions: 1) All programs use  
> the same file format.

Okay, simply change dhelp to use the doc-base directly and were are done.

> 2) You can convert the files during dpkg-buildpackage offline.

That's a bad idea, because this restricts you from adding new
documentation systems which use another new format.  Have a look how
many packages still only support dwww and not dhelp.  So you see, that 
creating these files at build time is a bad idea, while using a
generic format like doc-base is much more flexible, because you only
have to extend install-docs to support new formats and you're done
(okay when installing the new documentation system the first time, you 
will have to run the new install-docs for all existing doc-base files
once, but this shouldn't be a problem).

> RR> documentation system next to dwww and dhelp (both are horribly
> RR> broken at the moment, so another one may be a good idea) without
> RR> changing all the packages.

> Why is dhelp broken?

Because it doesn't support /usr/doc symlinks in the /usr/doc tree when 
the .dhelp file (created by a doc-base file) mentions the real
(/usr/share/doc) path.

> RR> If you think, that install-docs is too slow and dhelp-parse in

> One reason to write dhelp was the speed of dwww.

Why do you mix the speed of install-docs and dwww here?  The first one 
is run at install time, while the latter one is run at documentation
browsing.  As far as I can see one has nothing to do with the other.

> RR> combination with dhelp2dwww.pl is so much faster, why don't you
> RR> simply rewrite install-docs in C?  Then we have a generic and
> RR> fast solution.

> Because some authors are not interested to solve problems :(. We
> don#t need something like doc-base.

When I read the second sentence, it seems that you're talking about
yourself in the first one =;-)

> We need only a small shell script, that calls dwww and
> dhelp_parse. And we need *one* file format for dwww and dhelp.

So why not use doc-base as this one file format?
All file formats (doc-base, dhelp, menu,...) will have advantages and
disadvantages.  As far as I can see doc-base is a little bit more
flexible than dhelp (the latter only supports HTML and no other
formats) and doc-base is widely used and supported by debhelper and
dh_make for a long time now.  So doc-base may be a good compromise as
the "one file format".

> RR> I just installed it, but as far as I can see this doesn't
> RR> integrate FHS and FSSTND

> Right, because this is not possible.

I think that it is possible, proposed that all packages which use only 
/usr/share/doc at the moment, will soon add a symlink in /usr/doc, to
follow the technical committee decision.  Than you only have to
support /usr/doc with one problem: the doc-base and .dhelp files point 
to the real location in /usr/share/doc, while the files are also
accessible via the symlink as /usr/doc/<package>.  There needs to be
some work around for this, but this should be possible with some Perl
or Shell knowledge.

> There#s no solution for this problem, because dhelp supports reading
> documents via the local file system and via the http protocol.

No problem when you see /usr/doc as the one and only directory for
accessing the files.  The documentation of every package should be
available as /usr/doc/<package> in potato (this will change in the far 
future, but now we are working on potato).

> RR> possible for most packages, because the tech-ctte decided that every

> Were can I read this?

In the debian-ctte and debian-policy mailing lists and in the Debian
weekly news as of September 7th, 1999:

 The technical committee has [8]spoken: /usr/doc/<package> will be
 provided as a symlink in FHS compliant packages. This started an
 avalanche of updated, FHS compliant packages. For implementation
 details, see [9]this message (debhelper will handle most of this

 8. http://www.debian.org/Lists-Archives/debian-ctte-9909/msg00023.html
 9. http://www.debian.org/Lists-Archives/debian-ctte-9908/msg00038.html

> I#ve found nothing about this in the latest policy.

The policy 3.0.1 is broken in this point.  It was a fault to change
the complete policy to FHS without thinking about how to handle the
migration from /usr/doc to /usr/share/doc.  We couldn't find a
compromise in debian-policy so the technical committee had to decide
and they decided to create a farm of symlinks in /usr/doc to make
every package documentation available as /usr/doc/<package> in potato.
The symlinks have to be created and deleted by postinst and prerm,
because otherwise dpkg will have problems with this.

We are all waiting for the new policy, which will realize this
decision.  Maybe you noticed, that newer versions of debhelper and
lintian already support this way to handle this.

> RR> package that uses /usr/share/doc/<pkg> has to create a symlink
> RR> /usr/doc/<pkg> pointing to /usr/share/doc/<pkg>.  So all
> RR> documentation should be available as /usr/doc/<pkg>.

> No. A http daemon will never follow this symlinks. They#re 100% useless  
> when using the http protocol.

That's not true.  At least apache supports following symlinks when you 
activate this with "Options FollowSymLinks" in access.conf for the
/usr/doc directory.  Other web servers will support this in a similar

> RR> In the past we had two places where the user had to look for
> RR> documentation on programs: http://localhost/doc/HTML/ and
> RR> http://localhost/dwww/menu.html

> ??? You only need one of this systems.

Both systems have advantages and disadvantages and many packages
support only one of these systems.  For me (personally) this means,
that both systems are quite unusable, so I directly access the
documentation files without using dhelp/dwww.  But if you want to
access all package documentation, you will have to use both systems.



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