mirror of https://github.com/mkerrisk/man-pages
60 lines
1.8 KiB
Plaintext
60 lines
1.8 KiB
Plaintext
|
These are some things that should get done for man-pages, one day.
|
||
|
|
||
|
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 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 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.
|
||
|
While we're at it, we probably better standardise on one version
|
||
|
of English spelling.
|