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

Re: Status of Debian Policy



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

 - 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? 



Christian Schwarz <schwarz@monet.m.isar.de> writes:

> TOPIC 11: policy about including documentation
> ----------------------------------------------
> 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

Version: 2.6.3i
Charset: noconv
Comment: Processed by Mailcrypt 3.4, an Emacs/PGP interface


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: