On Sep 19, 2006, at 4:04 PM, Lewis Overton wrote:
Or ... what are other people doing so write these pages. I know there are dedicated editors, but learning another editor isn't where I want to spend my time. Maybe that's the best answer. That's why I'm asking this obviously knowledgeable group. A man writing bundle? A different editor? Suffer? Give it up and switch to ... no, I can't go on. ;)
I've used Perl's POD (Plain Old Documentation) for this in the past. It's very easy to learn and can export to many formats (man, text, html and so on) so if you decide to publish HTML later you can do so easily.
Assuming your system has Perl installed, see perlpod(1) for more information. Basically you write a file in the POD syntax and can export to man format with pod2man (which you can read about in pod2man (1)).
I've included a small sample below, based on an excerpt of ls(1). You can save this in a file and run "pod2man file.txt" to see the output. To see it formatted do:
pod2man file.txt | nroff -man | more
-dan
---------------------------
=head1 NAME
ls -- list directory contents
=head1 SYNOPSIS
ls [-ABCFGHLPRTWZabcdefghiklmnopqrstuwx1] [file ...]
=head1 DESCRIPTION
For each operand that names a file of a type other than directory, ls displays its name as well as any requested, associated information. For each operand that names a file of type directory, ls displays the names of files contained within that directory, as well as any requested, asso- ciated information.
If no operands are given, the contents of the current directory are dis- played. If more than one operand is given, non-directory operands are displayed first; directory and non-directory operands are sorted sepa- rately and in lexicographical order.
The following options are available:
=over
=item B<-A>
List all entries except for . and ... Always set for the super-user.
=item B<-B>
Force printing of non-printable characters (as defined by ctype(3) and current locale settings) in file names as \xxx, where xxx is the numeric value of the character in octal.
=item B<-C>
Force multi-column output; this is the default when output is to a terminal.
=back
=head1 EXAMPLES
The following is how to do an ls listing sorted by size (and shows why ls does not need a separate option for this):
ls -l | sort -n +4
Additionally, the -r flag to sort(1) may be used to get the results sorted from largest to smallest (a reverse sort).
=head1 SEE ALSO
chflags(1), chmod(1), sort(1), xterm(1), compat(5), termcap(5), symlink(7), sticky(8)
=cut