Steve M. Robbins writes:
Hi,
1. organize by endeavour rather than form, and
2. remove "catch all" sections like "miscellaneous".
3. keep the tree balanced, and
4. use the "menu" section when applicable.
Agree. The hierarchy will be based on the menu's one, which should make
it easy to meet your expectations.
choice than me. I'm starting to wonder whether a more web-like
approach where a document could appear in multiple sections might
work.
This could be a great idea, I'll add this point to the TODO list.
Pragmatically, I wouldn't expect a sudden, radical change to be
tolerated well. I expect a lot of maintainers would be annoyed and
simply ignore the issue if you told them that their doc-base file had
to be fixed.
That's why doc-base implemented the section mapping, which already
reduced a mass we have in doc-base sections. At the last paragraph, you
wrote that this can't be done fully automatically, and I agree with
this - each maintainer should probably review their doc-base file
against the new sections list.
Perhaps a gradual approach is best. For example, start
with documenting the preferred first- and second-level sections. This
addresses the proximal cause of me filing this bug: package
apt-dpkg-ref is in section Doc rather than Debian mainly because the
documentation for doc-base doesn't describe Section Debian (#153404).
Yeah, but the Doc section wasn't described either.
In tandem, you might consider trying to fix only the most egregious
violators of the preferred sections. In my mind, these are the
generics (principle #2): Docs, Doc, Misc, Tools, Utilities, Utils, and
Viewers.
The sections won't be included in the doc-base manual, except for
Viewers, which is also in menu hierarchy. However they will stay in the
mapping file only because it's impossible to do sensible automatic mapping.
Regards,
robert
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
