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

[Christian Kellermann]

* Peter Bex <address@hidden> [160719 10:08]:
> 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?

That's correct imho. We would add the mandoc requirement when building
a release / snapshot / git version only. I could live with that.

Thanks!

Christian

--
May you be peaceful, may you live in safety, may you be free from
suffering, and may you live with ease.