Re: Menu policy: undefined categories in use for documentation
On Fri, Oct 21, 2005 at 09:53:18PM +0200, Frans Pop wrote:
> While wondering where to put documents from the new Installation Guide
> packages, I noticed that on my system the menu presented by dwww does not
> comply with menu policy [1] (the documentation for doc-base refers to
> menu policy for acceptable categories).
> I have filed 3 minor bugs against obvious mistakes [2], but there also
> seem to be some cases where maybe policy should be extended.
Hello Frans,
The menu sub-policy does not pretend to cover doc-base section. The
doc-base documentation does reference the menu sub-policy which create
some semantic clash. We could fix that by renaming 'menu sub-policy' to
'menu and doc-base sub-policy' and include three lists of sections, one
shared, one menu-specific and one doc-base specific.
> Examples listed are only from my own system, so not very representative.
>
> - Apps
> Has undefined subcategory Mail (package: mailx)
> IMO having a category Mail for documentation makes sense as we
> also have a category mail in the archives, otherwise this should
> probably go to Net. OTOH, allowing Mail would also lead to Web.
In my opinion, there is no much point allowing Mail for doc-base but
not for menu. So I would put it in Net. My personnal plan is to split
Net in Net/Mail and Net/Web etc and allow menu to merge them if they are
nearly empty, but adding a new menu section Mail can be evaluated.
> - Admin
> Undefined category which holds documentation from grub-doc
> Should probably be moved to Apps/System
There is a widely used section Apps/System/Admin
(whose name is translated).
> - Debian
> Undefined category which holds quite a lot of Debian specific
> documents; some documents included both here and under Apps
>
> - FAQ
> Undefined category which holds a reference to the Linux FAQ
> - HOWTO
> Undefined category which holds a reference to the Linux HOWTOs
> - Manpages
> Undefined category with a link to man2html
This one is dwww specific, not from doc-base.
> Having both FAQ and HOWTO on the top level seems a bit redundant to me,
> especially if unused for other documentation. It could also lead to
> random packages putting their FAQs and HOWTOs there.
> The same argument goes for Manpages really.
> Would it make more sense to define a category "Linux" where such
> documentation can be grouped?
>
> - Tex
> Undefined category holding documentation from several TeX packages
> IMO this makes sense as a separate category, although that could be
> seen as a precedent for Perl, Python and other categories.
I don't think we should allow TeX as a top-level category, but we can
consider adding Apps/TeX.
> - Web
> Undefined category holding documentation from packages linklint
> and wdg-html-reference.
> It also has a subcategory W3c holding documentation from libwww-ssl0.
> IMO having a separate category Web is OK but should probably be moved
> below Apps. Not sure if the subcategory W3c is waranted.
I think Web should be in Net, like Mail. Note that according to
menu standard, it is OK to use 3rd level sections for a specific
applications if the rule of "0 or 3+" below is likely, for example
if you ship 5 documents in a package.
> I can understand if new categories for documentation would not be included
> in section 2.1 of the policy manual as that would also allow these for
> the application menu. Instead maybe a section 2.2 could be added defining
> additional categories acceptable in doc-base for documentation.
My criterium for adding a section is whether on most systems the section
will not have one or two entries. Zero entries is OK since in this case
the section will not be displayed. Three is barely sufficient to make the
section worthwhile but does not look ugly.
I will extend my statictics about menu sections to cover doc-base,
so we will see what sections are currently in use.
Cheers,
--
Bill. <ballombe@debian.org>
Imagine a large red swirl here.
Reply to: