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

[Timo Myyrä]

Peter Bex <address@hidden> writes:

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

Hmm, mandoc can output HTML from mdoc. Could the HTML page be generated from
mdoc file? That would keep those in sync? But that step could be worked on 
later.

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

Yeah, better that way, ship csi.man and csi.mdoc files in the release files and
copy one of them to csi.1 on install step. Just use Makefiles to decide which
file to copy. 

Timo