technical-policies icon indicating copy to clipboard operation
technical-policies copied to clipboard

Published 20 hours ago • verified publisher icon openssl

Style guide for manpages

Open kroeckx opened this issue 10 months ago • 5 comments

We need a guide for how to write the manpages. @t8m pointed to man-pages(7), but maybe perlpodstyle(1) is what we want to follow.

kroeckx avatar Jan 13 '25 13:01 kroeckx

perlpodstyle does not talk about C macros or functions. It is convenient only for documenting some of the markers.

t8m avatar Jan 13 '25 13:01 t8m

We do follow perlpodstyle(1) too. There are, however, some things that perlpodstyle(1) doesn't talk about, or that man-pages(7) clarify in more detail.

Have we missed something where perlpodstyle(1) and man-pages(7) contradict each other?

levitte avatar Jan 13 '25 15:01 levitte

So maybe we just need to point to them somewhere?

kroeckx avatar Jan 14 '25 09:01 kroeckx

Yes, that's a good idea

levitte avatar Jan 14 '25 09:01 levitte

... and also to clarify that our use of POD as a format is a choice we've made and are (at least so far) sticking to.

levitte avatar Jan 14 '25 09:01 levitte