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]
Message-ID: <e6b9ed8b-7044-0fab-a735-fa9cbeeb97c1@blackwall.org>
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

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ