Re: Writing manpages
The Fungi <fungi@yuggoth.org> writes:
> I, too, had resolved recently to start maintaining all my project
> documentation in reST. Not that I find building/editing manpages
> directly in vi to be that hard, but it's still laborious and
> time-consuming. I'll be happy to contribute fixes to this for any bugs
> I find. Thanks for the rcommendation!
Great. Both I and the upstream author are not supremely familiar with
proper *roff markup and the nuances of manpage rendering, so reasoned
suggestions for improvement are definitely welcome.
I'm also looking for a new sponsor for the ‘rst2man’ package (though
there's currently nothing waiting for upload), so if anyone wants to
step up for that, please feel free to get in touch.
Rogério Brito <rbrito@ime.usp.br> writes:
> Well, it seems that we have two strong contenders: POD and reST.
> Things look brighter for a more documented Debian. :-)
Now if only we can convince more package maintainers. Hopefully the
ability to use these source formats, with steady evangelisation about
the available rendering tools, can lower the resistance to following
policy on providing manpages for all commands.
> And regarding the Emacs mode for POD, that's simply great! My POD
> files were interpreted before as comments in Perl documents, but with
> this mode, things are much more comfortable! :-)
To bang the reST drum, I'll point out that Emacs has a good ‘rst-mode’
as well, which of course works fine for manpage sources in reST.
--
\ “We are human only to the extent that our ideas remain humane.” |
`\ —_Breakfast of Champions_, Kurt Vonnegut |
_o__) |
Ben Finney
Reply to: