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

Re: RFS: crotch



On Wed, 24 Jan 2007 16:08:14 +0100
schönfeld / in-medias-res <schoenfeld@in-medias-res.com> wrote:

> >>   - Your package does not include a manpage for a binary. Thats not an
> >>    'error', but is highly recommended and the fact that there is none,
> >>    results in a lintian warning.
> >
> > Ahem, correct. That's for two reasons: firs crotch only understands
> > two arguments, no options in only uses STDIN and STDOUT, therefore I
> > thought I could omit a manpage. Second, I do not know how to write
> > manpages... :o(
>
> About writing of man pages. It is easier then writing applications.
> Just open up an existing manpage in an editor and look at it. On the
> first sight it might look a little bit obscure, but it isn't. Even I am
> able to write manpages (but I cannot code much C)

There are plenty of tools that help create manpages without having to
understand the Groff/troff format. help2man can take your STDOUT usage
message and convert that to a usable manpage, doclifter can then take
that manpage and create XML that is easier to edit and gives you
instructions on how to use xsltproc to turn the XML back into a
manpage. dh_make creates an example manpage (groff, xml and sgml
formats) which you probably deleted and which you can recreate in any
temporary directory. There really is no excuse for not being able to
write a manpage. If you can write a ChangeLog entry, you can write a
manpage. OK, it may not be the most verbose or comprehensive manpage in
Debian but it is a start. Some packages don't need more than a single
screen of manpage output - many packages could do with splitting their
overly verbose manpages into separate files. Generating a simple
manpage is trivial compared to all the other packaging tasks.

When generating a manpage, ensure you package the original XML/SGML so
that if there are bug reports against your manpage, people can submit
patches that you can actually use. Converting a patch for a manpage
into a patch for the generating XML is not trivial. You don't have to
generate the manpage during the package build process, just update the
manpage when the XML/SGML changes.

--


Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/

Attachment: pgpgGXvlOoD2D.pgp
Description: PGP signature


Reply to: