2006-07-11 11:43:23 +00:00
|
|
|
These are some things that should get done for man-pages, one day.
|
|
|
|
|
2007-06-05 05:32:25 +00:00
|
|
|
POSIX.1 pages
|
|
|
|
=============
|
|
|
|
|
|
|
|
Separate POSIX.1 pages into another package.
|
|
|
|
|
2007-09-05 22:36:50 +00:00
|
|
|
Migrate pages into kernel source tree
|
|
|
|
=====================================
|
|
|
|
|
|
|
|
Perhaps split glibc stuff out into a separate tree?
|
|
|
|
Would also need to migrate some .3 pages to .2 and vice versa.
|
|
|
|
Some Section 5 and 7 pages probably belong rather with the glibc pages.
|
|
|
|
|
2007-06-09 15:36:57 +00:00
|
|
|
Public SCM
|
|
|
|
==========
|
|
|
|
|
2007-09-05 22:36:50 +00:00
|
|
|
Set up a public source code repository.
|
2007-06-09 15:36:57 +00:00
|
|
|
|
2006-07-11 11:43:23 +00:00
|
|
|
Website
|
|
|
|
=======
|
|
|
|
|
|
|
|
Set up a website for the man-pages project. Aside from describing the
|
|
|
|
project, and how to contribute to it, the site should also:
|
|
|
|
|
|
|
|
* provide hyperlinked versions of the manual pages
|
|
|
|
* provide a web interface to the subversion repository in which
|
|
|
|
the manual pages have been maintained since version 2.00
|
|
|
|
* provide a (searchable) archive of the mailing lists
|
|
|
|
|
|
|
|
Once the web site is up, it may be worthwhile putting its URL into
|
|
|
|
the header or footer of every manual page; this would allow people
|
|
|
|
to easily determine where to submit bug reports and suggestions.
|
|
|
|
|
|
|
|
Bugzilla
|
|
|
|
========
|
|
|
|
|
|
|
|
Set up a bugzilla for reporting bugs in the manual pages.
|
|
|
|
|
|
|
|
Markup language
|
|
|
|
===============
|
|
|
|
|
2007-06-09 15:36:57 +00:00
|
|
|
The existing man-pages set is an unfortunate mixture of pages written in
|
2006-07-11 11:43:23 +00:00
|
|
|
two formats: 'man' and 'mdoc' (BSD). Neither is optimal, since they
|
|
|
|
don't encode sufficient semantic detail about the elements of a page.
|
2007-05-11 20:01:16 +00:00
|
|
|
What is perhaps required is a new markup language (probably some form
|
|
|
|
of docbook) that:
|
2006-07-11 11:43:23 +00:00
|
|
|
|
|
|
|
a) is unintrusive: the raw page source should remain very readable
|
|
|
|
b) applies markup by function, not by effect
|
|
|
|
c) can be easily processed to generate the present nroff from it
|
|
|
|
d) can be easily processed to generate HTML from it
|
|
|
|
e) be simple to learn and use
|
|
|
|
|
|
|
|
And of course, the existing pages would need to be converted to
|
|
|
|
the new format.
|
|
|
|
|
|
|
|
A big job...
|
|
|
|
|
2007-10-08 19:58:21 +00:00
|
|
|
Devise (or adopt) a style guide
|
|
|
|
===============================
|
2006-07-11 11:43:23 +00:00
|
|
|
|
2007-10-08 19:58:21 +00:00
|
|
|
This should describe formatting, terminology, and grammar conventions.
|
2007-06-09 15:36:57 +00:00
|
|
|
In the meantime, there is at least man-pages(7).
|