mirror of https://github.com/mkerrisk/man-pages
69 lines
1.9 KiB
Plaintext
69 lines
1.9 KiB
Plaintext
These are some things that should get done for man-pages, one day.
|
|
|
|
POSIX.1 pages
|
|
=============
|
|
|
|
Separate POSIX.1 pages into another package.
|
|
|
|
Public SCM
|
|
==========
|
|
|
|
Set up a public subversion repository.
|
|
|
|
Mailing lists
|
|
=============
|
|
|
|
Set up mailing lists for the manual pages:
|
|
|
|
* A low-volume, broadcast list announcing new manual page releases,
|
|
and other events of similar significance.
|
|
|
|
* A general discussion list used for submitting manual page suggestions,
|
|
fixes, etc.
|
|
|
|
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
|
|
===============
|
|
|
|
The existing man-pages set is an unfortunate mixture of pages written in
|
|
two formats: 'man' and 'mdoc' (BSD). Neither is optimal, since they
|
|
don't encode sufficient semantic detail about the elements of a page.
|
|
What is perhaps required is a new markup language (probably some form
|
|
of docbook) that:
|
|
|
|
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...
|
|
|
|
Devise a style guide
|
|
====================
|
|
|
|
This should describe formatting, terminology and grammar conventions.
|
|
In the meantime, there is at least man-pages(7).
|