mirror of https://github.com/mkerrisk/man-pages
Things still to do for man-pages
This commit is contained in:
parent
3b26077915
commit
729a10315f
|
@ -0,0 +1,59 @@
|
|||
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.
|
Loading…
Reference in New Issue