Re: first implementation of doc-base
>
> [I CC this mail to the maintainers of menu, dwww, and dhelp since I don't
> know who of them is subscribed to debian-policy. Just tell me and we'll
> drop the CCs.]
I'm subscribed, but my backlog of (mostly debian related) procmail filtered
mail is by now about 70 M. So I appreciate being CC-ed for now.
> 1. We have to get a consensus about which document information is required
> for the online menus. Currently, dhelp and dwww require different fields
> (e.g., dwww can handle a `longtitle' which is not supported by dhelp).
If dhelp also uses a /etc/menu-methods/dhelp file, then adding support
for a "longtitle" is trivial.
> Simply using all fields required either for dhelp or dwww is not enough,
> IMHO. Remember, that the solution has to be simple for the maintainers!
With respect to the "longtitle" point (assuming dhelp doesn't change):
one should simply create a menu file with both "title" and "longtitle"
set to the best title available (longtitle if available, title otherwise).
This is basically what the dwww menu-method does anyway (it will use
the longtitle if available, title otherwise).
> 2. We've to define a policy about the preferred document directory (i.e.,
> for possible values for the `Section:' field above). Currently, dhelp and
> dwww use different menu structures. This is not acceptable.
Absolutely.
> 4. doc-base currently supports registering to dhelp and dwww (via menu
> only). There is one problem, though:
>
> When doc-base installs a menu/dwww entry for a manual, it installs the
> file /usr/lib/menu/doc-base-<docid> and uses "?package(doc-base)" in the
> file for menu. (doc-base does not know which package registered the
> document. This should not be a problem since when the package is removed
> later, doc-base will automatically remove that file.)
>
> Obviously, this does not work with the /usr/lib/menu/default files, since
> menu compares the filenames in menu/default with those in menu/ . For
> example, there is a file `menu/default/dpkg', but once dpkg supports
> doc-base, the documents will also be included in `menu/doc-base-<docids
> for dpkg documents>', which will result in the documents appearing in the
> menus twice.
The easy solution to this is: I just remove all /usr/lib/menu/default files
that refer to documentation. I'll move them to /usr/doc/menu/examples
or something.
> Should the default entries be removed for packages which support doc-base,
> or is there a better solution?
Doing it step-by-step (removing .../default/dpkg when dpkg starts to support
it, etc) is not very good, I'd say, as it requires a lot of menu releases,
and each time you upgrade dpkg (or that other package that starts to support
doc-base), you also have to upgrade to this new menu version. Better just
get rid of all of them at once, I'd say.
That makes me think of another point: Does doc-base have a way for the
systemadmin to override package defaults? (maybe I want a different Emacs
www page or something my system than the one supplied with emacs.deb)
The menu system makes this really easy (just put those files in /etc/menu).
Would it be difficult to add something like this to doc-base (doc-base
would then first read files in /etc/doc-base, and then go to
/usr/lib/doc-base, but in that directory skip the ID's it already read
in /etc. Next could be /usr/lib/doc-base/default).
This last (.../doc-base/default) is why I ask this: it would be rather
easy to convert all .../menu/default/ files that refer to documentation
into doc-base format (a symple /etc/menu-method file could do that), and
then move thise new doc-base files out of the menu pacakge, into the
doc-base package 's .../doc-base/default directory. That would solve both
your 4th problem, and make the system more flexible for local adoptations.
> I really appreciate _any_ comments about doc-base
Ah, that's what you're after. OK, I'll set off then:
I'm thinking about whether it is needed to create this whole new
doc-base file format (for the files in /usr/lib/doc-base/<doc-id>).
I agree that the format of the menuentry files (/usr/lib/menu/) is
suboptimal for the following reasons:
- Having to have this "\" at the end of every line is annoying
(noted by others too, but this was done for better support of
mixtures of old-style menufiles an new-style)
- It at the moment only allows the registering of one document
per entry (thus only html, or only info, etc). A second, or third
document type is possible, and the menu-method files have easy
ways to specify what document type they prefer. However, to do this
one has to repeat the whole menuentry for every document type.
I'm not sure I oversee everything here, but if this is all, then
I think it may be worthwhile to consider improving menu so that the above
mentioned drawbacks don't apply any more. The advantage of this would be:
- the above mentioned ability to localy adjust the system
- "update-menu" can be used to convert the doc-entry files to
www pages rather flexibily (quite easy to change the whole structure
of the resulting www pages). And appart from www pages, one could
possible generate a bash script that shows the doc pages with less.
(just to mention one possibility)
Personally, what I see that doc-base needs to do is convert the various
documentation formats into each other, that is something that is badly
needed. It may also provide a way to show what doc files are installed
on the system, but with menu this is already really easy (just add an
/etc/menu-method script that creates a file like the one in
/var/lib/dpkg/info/status, and then use grep &c to get the right lines).
--
joost witteveen, joostje@debian.org
Potentially offensive files, part 5: /dev/random.
`head -c 4 /dev/random` may print 4-letter words (once every approx 4e8 tries).
Reply to: