[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Writing manpages (was: Re: Man and UTF-8.)

On Wed, Nov 18, 2009 at 05:30:33AM -0200, Rogerio Brito wrote:
> On Nov 17 2009, Roger Leigh wrote:
> > However, TTBOMK UTF-8 manpages should be OK as well, though I have
> > found some issues with more esoteric characters.  I would suggest
> > reporting bugs or contacting the maintainer or groff upstream if
> > you run into problems here.
> OK, since the project strongly advises for the availability of manpages
> (and I love manpages), comes the question: what do you people use to
> type manpages?
> Using troff is simply nasty and hard, with all the typesetting getting
> in the way of seeing the content that one has typing (that's not to even
> mention the need to memorize the black magic-esque mnemonics).

Just for the record (and I know I'm resurrecting an already pretty much
closed discussion), I personally am quite used to writing mdoc manual
pages.  Well, okay, so that shows my FreeBSD alignment ;)  But IMHO
mdoc is a *lot* more readable (and writeable) than plain troff with
the "an" macros.  All the utilities that I've developed (e.g. confget,
pslist, and timelimit in Debian) have their manpages in mdoc format, and
when I need to write a manpage for something else, I use it too (like
I converted the wmanager manpages to mdoc when I took over the package).

Of course, I like both reST and POD too, it's just that mdoc is a bit
closer to the manpage structure than POD, and reST just wasn't around
ten years ago :)  And I'm pretty much used to mdoc by now :)


Peter Pentchev	roam@ringlet.net    roam@space.bg    roam@FreeBSD.org
PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint	2EE7 A7A5 17FC 124C F115  C354 651E EFB0 2527 DF13
This sentence every third, but it still comprehensible.

Attachment: pgp148hewAd9N.pgp
Description: PGP signature

Reply to: