Re: [Chicken-hackers] Using mandoc for chicken manual pages?

[Peter Bex]

On Tue, Jul 19, 2016 at 10:53:07AM +0300, Timo Myyrä wrote:
> Hi,
> 
> Chicken manuals are currently little sparse and use older man(7) format.
> Would it make sense to update the manual pages and switch to using mdoc(7)
> format in them? Mdoc(7) format is easier to work on and the manual pages need
> attention in any case. Currently they just recommend to run the command with
> `-h' flag to get the information.
> 
> On chickens user side this wouldn't cause anything new, better manuals I 
> hope. I
> think most platforms can view mdoc(7) pages just fine.

I think this would be great.  The main problem with manpages is
maintenance, because most of this is duplicated in the online help and
the "manual" dir.

> On build side it would make mandoc a build dependency. It would also require a
> check in build scripts so that platforms which are not able to view mdoc(7)
> files would be able to generate man(7) formatted manuals out of the mdoc(7)
> using mandoc command.

I don't know if that's necessary; we could pregenerate these just like
we do for the .c and .html manual files.  Only if you want to build CHICKEN
from git sources you'd need mandoc proper.  Or am I misunderstanding what
you're saying?

Cheers,
Peter

signature.asc
Description: Digital signature