Re: [Monotone-devel] Re: monotone man page

[Thomas Keller]

Am 30.06.2010 07:58, schrieb Gour:
> On Sat, 26 Jun 2010 23:13:59 +0200
>>>>>>> "Thomas" == Thomas Keller <address@hidden> wrote:
> 
> Thomas> What do others think? Is it worthwhile to go down this route
> Thomas> any further?
> 
> Have you thought about using Pandoc?
> 
> (http://johnmacfarlane.net/pandoc/)
> 
> It enables you to use one source (e.g. markdown/reST) and then convert
> to plethora of formats.
> 
> From the homepage: "Pandoc can read markdown  and (subsets of)
> reStructuredText, HTML, and LaTeX, and it can write plain text,
> markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook
> XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, groff man
> pages, and S5 HTML slide shows. PDF output (via LaTeX) is also
> supported with the included markdown2pdf wrapper script."
> 
> 
> Here I plan to use it to write markdown (or reST) and then generate
> user manual docs via sphinx and gt PDF as well.
> 
> You can generate Texinfo which is presently used by monotone.
> 
> (I do not like Asciidoc since it involves DocBook toolchain...)

Well, if I can avoid any other tool, then this should be preferred.
After all the solely reason for this work is to generate a man page, I
don't want texinfo, PDF, HTML output or whatsoever from it. We have a
great online manual, that should be enough.

What I meant with or rather hoped to get feedback for when I asked "is
it worthwhile to go down this route any further?" was if the
_information_ in their current form as they're provided by the current
mechanism is suitable for a decent man page. A few things come into my
mind here:

a) command / group ordering cannot be ordered in a custom way, therefor
API commands may come before the really important stuff

b) its not possible (yet) to add additional information for certain
commands or groups which should only popup in the man page

c) I'm still missing a well-written description - nobody has provided
any so far

Anything else?

Thomas.

-- 
GPG-Key 0x160D1092 | address@hidden | http://thomaskeller.biz
Please note that according to the EU law on data retention, information
on every electronic information exchange might be retained for a period
of six months or longer: http://www.vorratsdatenspeicherung.de/?lang=en

signature.asc
Description: OpenPGP digital signature