Re: [Monotone-devel] monotone man page

[Thomas Keller]

Am 22.06.2010 03:08, schrieb Aaron W. Hsu:
> On Sunday 20 June 2010 18:47:19 Thomas Keller wrote:
>> Hey there!
>>
>> I've just pushed some initial work to nvm.man-page to let monotone
>> auto-generate its own man page. If you compile this, a new hidden
>> "manpage" command will be available, which dumps the command tree and a
>> few additional information in (g)roff format, so you can then basically
>>
>>      mtn manpage | groff -man -Tascii - | less
>>
>> to view the generated page. This is work-in-progress, as I'm fighting
>> with some of groff's macros still (f.e. the indentation is not always
>> correct). Also I need to tweak the output of our description methods a
>> bit, because a couple of unwanted newlines are inserted as well,

[this has been fixed]

>> and I
>> need a fancy / catchy DESCRIPTION for the program itself (proposals
>> welcome!) - but basically it works.
>>
>> I haven't yet touched the build process part for that, so no, the man
>> page will not be automatically generated / installed when you hit make
>> install now...

[this has been implemented in the meantime]

> I love this! I'm quite excited to get a man page with mtn. 

Cool :)

> Is there a chance 
> that we could move to using mandoc instead of just the normal man pages? This 
> will have positive benefits on the BSD systems, such as OpenBSD, which favors 
> the mandoc system. 

I haven't heard of mandoc before, I have to admit its the first time I
tried to write a man page at all. After looking at asciidoc and other
similar projects which required too many tools in between or didn't
produce the results I wanted, I sticked to the normal groff output.

Could you elaborate a bit more about the "positive benefits" on these
systems?

> Is there a reason that the documentation needs to be generated from the 
> existing help documentation? Sometimes I find that it is nice to put much 
> more 
> information into a proper man page than what you get from the help command in 
> monotone.

Well, we had a dedicated man page years ago, but it was hard to take
care of that and the manual, so it was not updated a lot. The main drive
for this auto-generated man page is now to have the complete command set
searchable / scannable and readable in one page. The main documentation
source is of course the (info) manual we also supply, but if you're
missing particular information in certain commands, then I'd love to see
your patches for the CMD* macros :) - if the need arises, we could also
add another (optional) parameter there which lets us describe things
which then only pop up in the man page, but before that happens I'd
rather see the command descriptions we have right now improved.

The problem with all that is just that we do not have enough man power
to do both things, manual and man page, by hand, given the fact that
monotone is still very much in flux.

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