netdev - Re: [RFC Draft PATCH net-next 0/1] Bridge doc update

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

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date: Wed, 20 Sep 2023 13:38:44 +0300
From: Nikolay Aleksandrov <razor@...ckwall.org>
To: Hangbin Liu <liuhangbin@...il.com>, Roopa Prabhu <roopa@...dia.com>
Cc: "David S . Miller" <davem@...emloft.net>, netdev@...r.kernel.org,
 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>,
 Stephen Hemminger <stephen@...workplumber.org>
Subject: Re: [RFC Draft PATCH net-next 0/1] Bridge doc update

On 9/20/23 12:19, Hangbin Liu wrote:
> Hi Nikolay, Roopa,
> 
> Do you have any comments for this RFC?
> 
> Thanks
> Hangbin
> On Wed, Sep 13, 2023 at 05:28:52PM +0800, Hangbin Liu 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(-)
>>
>> -- 
>> 2.41.0
>>

Hi Hangbin,
I support all efforts to improve documentation, but I do share the same 
concerns that Stephen has already voiced. I don't think we should be 
generating the man page from the kernel docs, IMO it would be simpler
and easier for everyone to support both docs - one is for the user-space
iproute2 commands, the other could go into the kernel api details. All
attribute descriptions can still be added to headers, that would be very
valuable on its own. I prefer to have the freedom to change the docs 
format in any way, generating them from comments is kind of limiting.
The purpose of each document is different and it will be difficult
to combine them for a man page. It would be much easier for everyone
to add user-related command descriptions and examples in iproute2's 
documentation, and to add kernel-specific (or uapi) documentation to the
kernel doc. We can add references for each with a short description.
W.r.t the kernel doc topics covered, I think the list is a good start.

Thank you,
  Nik