Re: Status of Debian Policy
-----BEGIN PGP SIGNED MESSAGE-----
Hi,
I have another policy issue which is related to topic 11 (see below).
The current layout of Info entries in the main Info menu (in the file
/usr/info/dir) looks rather messy. I found the following "descrepencies":
- not all packages are placed in an appropriate section
- the descriptions are not formatted consequently
- some sections are somewhat large (this is personal)
- some descriptions are somewhat large (this is personal too)
I believe we can do better. Therefor, I propose an extension/change to
Section 3.2.3 of the Debian Policy Manual:
- During install of an Info documents you MUST specify a section.
Preferably use the section the package belongs to in the Debian
distribution. As a starting point the "dir" file in the base-files
package could already contain these sections, albeit empty.
We could also use a different, sometimes more logical grouping. E.g.,
I'm using the following sections for the development packages:
- compilers
- linkers
- interpreters
- generators (i.e. bison, flex, gperf, etc.)
- libraries
- development tools (i.e. make, gdb, etc.)
- internals (i.e. gdb-internals, stabs, etc.)
If the Info doc has a lot of subentries, make a separate section
for it, as has been done for the GNU file, text, shell, and shar
utilities.
- Start the description at a to-be-determined fixed position, e.g.
first line at position 41 and second and subsequent lines at position
43. This unclutters the layout, but the positions should be such
to leave enough room for a short, one-line, to-the-point decription.
- Instead of using the upstream provided description, provide an own
one-line one which fits on the same line as the menu entry. A three
line description for awk may be nice but clutters the layout, e.g.
In the light of topic 11 the above may be not that important anymore,
but if we plan to keep Info docs around (I have not heard otherwise
yet) I believe we should discuss the above.
I was also wondering whether we plan to organize the documentation
under dwww in a way similar to the Info docs (sectioning, layout,
etc.). Anybody some thoughts on this?
Greetings,
Ardo
Christian Schwarz <schwarz@monet.m.isar.de> writes:
>
> TOPIC 11: policy about including documentation
> ----------------------------------------------
> STATUS: DISCUSSION
>
>
> The current policy concerning docs is:
>
> - HTML is the preferred format
> - if the package includes docs than can be converted into HTML,
> the maintainer should do so
> - if the doc files are to big, they should go into a seperate
> package
>
> There are a few problems, though:
>
> - .info files can be converted into HTML on-the-fly by the CGI
> script "info2www". However, the output of ``texi2html'' is
> much better. Should we ship only HTML by default and put
> .info in a seperate package? (cf. bug #7890)
> - how "large" may doc files be until they are moved into a
> seperate package?
>
>
- --
Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl
home page: http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp: 3B 1F 21 72 00 5C 3A 73 7F 72 DF D9 90 78 47 F9
-----BEGIN PGP SIGNATURE-----
Version: 2.6.3i
Charset: noconv
Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface
iQCVAwUBM6Q5ST6XMRfcxSjpAQG9DAP+P7QAIjwtkwnPNzTd+GWRwoP4tK1BWXle
EXNic9qqB1W16qALB6YXNsXAqngNXcIf79C9ZuF2sZiWd+XuPl7ALYwDJWIopGEl
woFCcm1XMvX2Gr4mGVErq7iV1H60KOpPiOK4V3xFw/V+cZXL+SezdYsWRyV1Dt70
siOjdaOsHsg=
=zTMP
-----END PGP SIGNATURE-----
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: