Style guide for manpages

[kroeckx]

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.

[t8m]

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

[levitte]

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?

[kroeckx]

So maybe we just need to point to them somewhere?

[levitte]

Yes, that's a good idea

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