[TxMt] writing man pages

[Dan Lowe]

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