[TxMt] writing man pages
dan at tangledhelix.com
Tue Sep 19 22:17:31 UTC 2006
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
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
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
ls -- list directory contents
ls [-ABCFGHLPRTWZabcdefghiklmnopqrstuwx1] [file ...]
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
and non-directory operands are sorted sepa- rately and in
The following options are available:
List all entries except for . and ... Always set for the super-user.
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.
Force multi-column output; this is the default when output is to a
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),
More information about the textmate