On Mon, Sep 11, 2023 at 09:51:07AM +0200, Pablo Neira Ayuso wrote: > On Mon, Sep 11, 2023 at 03:54:25PM +1000, Duncan Roe wrote: > > This is a call for comments on how we want the documentation to look. > > In conjunction with the git diff, readers may find it helpful to apply the patch > > in a temporary branch and check how the web page / man pages look. > > To get web & man pages, do something like > > > > ./configure --enable-html-doc; make -j; firefox doxygen/html/index.html > > MANPATH=$PWD/doxygen/man:$MANPATH > > > > Some changes are documented below - I'll post more later > > > > --- Preparation for man 7 libnetfilter_queue > > The /anchor / <h1> ... </h1> combo is in preparation for making > > libnetfilter_queue.7 from the main page. mainpage is morphed to a group > > (temporarily) so all \section lines have to be changed to <h1> because \section > > doesn't work in a group. The appearance stays the same. > > > > ---1st stab at commit message for finished patch ** ^^^^^^ > > libnetfilter_queue effectively supports 2 ABIs, the older being based on > > libnfnetlink and the newer on libmnl. > > Yes, there are two APIs, same thing occurs in other existing > libnetfilter_* libraries, each of these APIs are based on libnfnetlink > and libmnl respectively. > > > The libnetfilter_queue-based functions were tagged DEPRECATED but ** s/libnetfilter_queue/libnfnetlink > > there is a fading hope to re-implement these functions using libmnl. > > So change DEPRECATED to "OLD API" and update the main page to > > explain stuff. > > libnfnetlink will go away sooner or later. We are steadily replacing > all client of this library for netfilter.org projects. Telling that > this is not deprecated without providing a compatible "old API" for > libmnl adds more confusion to this subject. I suggest there's bound to be confusion whilstever libnetfilter_queue and the other libraries support two APIs. The question is how to minimise this confusion. 3 suggestions: 1. Split out the old API functions to their own library, say libnfnetlink_queue. 2. Don't tag functions at all, but put something very obvious at the head of mainpage(*) explaining thare are 2 ABIs and the pros & cons of each. 3. Tag the libnfnetlink-based functions with something other than DEPRECATED. "OLD API" was my suggestion, do you have another? How about this re-worded paragraph (in the COMMIT message, *not* the documentation!): The libnfnetlink-based functions were tagged DEPRECATED but they are not. Change DEPRECATED to "OLD API" and update the main page to explain the difference. I was really hoping for comments on the rest of the patch. Would you find time to take a look? > > If you want to explore providing a patch that makes the > libnfnetlink-based API work over libmnl, then go for it. Others have tried. Recall this conversation: On Thu, Jan 20, 2022 at 01:15:22PM +0100, Pablo Neira Ayuso wrote: > On Thu, Jan 20, 2022 at 01:01:45PM +0100, Florian Westphal wrote: > > Pablo Neira Ayuso <pablo@xxxxxxxxxxxxx> wrote: > > > > > > The documentation is tagging the old API as deprecated which is not, > > > this needs to be reverted. > > > > Hmm, IIRC i tried to reimplement it on top of libmnl but there were too > > many libnfnetlink implementation details leaked into the old api. > > I guess these two are the problematic ones to move to libmnl: > > - nfq_open_nfnl() > - nfq_nfnlh() With regard to nfq_open_nfnl() and nfq_nfnlh(): neither of these are documented. Anyone using them has found them in the source. They are also using libnfnetlink directly. My first step in moving to libmnl would to to make those two static, or at least remove EXPORT_SYMBOL for them. If anyone complains, tell them to copy from source into their application. (*) Soon to double as libnetfilter_queue.7, if you apply that patch once I've finished it. Cheers ... Duncan.
