On Thu, Jul 22, 2021 at 07:10:15PM +0200, Pablo Neira Ayuso wrote:
> The existing autogenerated manpages are still a bit distant to usual
> Linux Programmer's Manual manpages at quick glance.
I guess doxygen-generated man pages will always be a little bit "distinctive".
Looking carefully, I see a number of doxygen artefacts that can be
post-processed away.
And I do see one substantive difference: the NAME section should have a list of
functions instead of the (internal use only) module name. So:
> pktbuff - User-space network packet buffer
should be
> pktb_alloc, pktb_data, pktb_len, pktb_free, pktb_mangle, pktb_mangled - User-space network packet buffer
The rest is window-dressing. Here's a list of changes (from top down (mostly)):
- Fix NAME entry as above
- If there is a "Modules" section, delete it
- If "Detailed Description" is empty, delete "Detailed Description" line
- otherwise rename it "Overview" maybe, since Function Documentation
contains detailed descriptions
- Reposition SYNOPSIS line through 1st blank line to before "Functions" line
- Delete "Functions" line
- Delete all "Definition at line nnn" lines
- Delete "Author" section (or should I leave that?)
My sed-fu is not up to doing this. I'll be using the rather more programmable
but little-known Q editor. Q is available at
https://sourceforge.net/projects/q-editor/ or from
https://github.com/duncan-roe/q
I'll put together a Q-macro suite to implement the above. Then I'll post
before/after samples of a short and a long page, say icmp & pktbuff.
If you think the changes are worth having, can then update Makefile.am with a
post-processing section that only runs if Q is available.
Cheeers ... Duncan.
