Re: [PATCH RFC libnetfilter_queue 1/1] src: doc: supply missing SYNOPSIS in pktbuff man pages

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]


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

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 with a
post-processing section that only runs if Q is available.

Cheeers ... Duncan.

[Index of Archives]     [Netfitler Users]     [Berkeley Packet Filter]     [LARTC]     [Bugtraq]     [Yosemite Forum]

  Powered by Linux