lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
Open Source and information security mailing list archives
| ||
|
Message-ID: <ZQJ4oFoPFqbr09O7@Laptop-X1> Date: Thu, 14 Sep 2023 11:06:08 +0800 From: Hangbin Liu <liuhangbin@...il.com> To: Stephen Hemminger <stephen@...workplumber.org> Cc: netdev@...r.kernel.org, "David S . Miller" <davem@...emloft.net>, David Ahern <dsahern@...nel.org>, Eric Dumazet <edumazet@...gle.com>, Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>, Ido Schimmel <idosch@...sch.org>, Nikolay Aleksandrov <razor@...ckwall.org>, Roopa Prabhu <roopa@...dia.com> Subject: Re: [RFC Draft PATCH net-next 0/1] Bridge doc update On Wed, Sep 13, 2023 at 04:22:24AM -0700, Stephen Hemminger wrote: > On Wed, 13 Sep 2023 17:28:52 +0800 > Hangbin Liu <liuhangbin@...il.com> wrote: > > > Hi, > > > > After a long busy period. I got time to check how to update the > > bridge doc. Here is the previous discussion we made[1]. > > > > In this update. I plan to convert all the bridge description/comments > > to the kernel headers. And add sphinx identifiers in the doc to show > > them directly. At the same time, I wrote a script to convert the > > description in kernel header file to iproute2 man doc. With this, > > there is no need to maintain the doc in 2 places. > > > > For the script. I use python docutils to read the rst comments. When > > dump the man page. I do it manually to match the current ip link man > > page style. I tried rst2man, but the generated man doc will break the > > current style. If you have any other better way, please tell me. > > > > [1] > > https://lore.kernel.org/netdev/5ddac447-c268-e559-a8dc-08ae3d124352@blackwall.org/ > > > > > > Hangbin Liu (1): > > Doc: update bridge doc > > > > Documentation/networking/bridge.rst | 85 ++++++++++-- > > include/uapi/linux/if_bridge.h | 24 ++++ > > include/uapi/linux/if_link.h | 194 > > ++++++++++++++++++++++++++++ 3 files changed, 293 insertions(+), 10 > > deletions(-) > > > > Not sure this is good idea. > - you are special casing bridge documentation and there is lots of > other parts of iproute2 Yes, the patch's purpose is to save the work for bridge doc(at present). So only the bridge part of iproute2 man page will be updated. I added a tag at the start/end of the bridge part. Other parts will not be touched. > - you are introducing a dependency on python in iproute2 There is no need to build it. I put it in the tools folder. Any one can choose to use or not use it. So I don't think it count for dependency. > - the kernel headers in iproute2 come from sanitized kernel headers. So > fixing the documentation would take longer. It doesn't matter. The python script only grab the attr description from net-next and convert it to man doc. It doesn't care about the kernel header in iproute2. > > What problem is this trying to solve? The bridge doc in kernel[1] is too old. There are a lot of details hide in the kernel code and new developer is hard to catch up. So the kernel bridge doc page need an update. You could say the iproute2 bridge documentation is new and updated. We can take it as the new bridge doc. But iprotue2 bridge doc only contains uAPI. The kernel API doc is still needed. On the other hand, the bridge developers already speed a lot effort on iproute2 bridge documentation. It would introduce more work and complex to maintain the kernel and bridge doc at the same time. So I suggest to only maintain the kernel doc. And convert the kernel part directly to iproute2 man page. With this, we can maintain the doc in one place and update them both on kernel and iproute2. [1] https://www.kernel.org/doc/Documentation/networking/bridge.rst Thanks Hangbin
Powered by blists - more mailing lists