Re: [Monotone-devel] monotone man page

[Aaron W. Hsu]

On Tuesday 22 June 2010 03:39:31 Thomas Keller wrote:

> 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?

mandoc is basically a better man macro set for Roff that is used by the BSDs 
and I think that comes with Groff by default. See this link for a bit of story 
about what OpenBSD is doing:

        http://www.undeadly.org/cgi?action=article&sid=20100604082319

> > 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.

Hrm, maybe there is something I might be able to do to help that. I don't 
know. :-) I don't have the C++ know how to contribute directly to the code 
base, but documentation is something I do care a lot about, and I for one 
almost never use info manual pages, and use man pages as my primary means of 
documentation. I'll play around with some things if I get the time and maybe 
there will be something I can do to help the problem.

        Aaron W. Hsu

signature.asc
Description: This is a digitally signed message part.