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] [day] [month] [year] [list]

Date: Wed, 20 Sep 2023 22:17:48 +0800
From: Hangbin Liu <liuhangbin@...il.com>
To: Nikolay Aleksandrov <razor@...ckwall.org>
Cc: Roopa Prabhu <roopa@...dia.com>,
	"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 Wed, Sep 20, 2023 at 01:38:44PM +0300, Nikolay Aleksandrov wrote:
> > 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/
> > > 
> 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.

Hi Nikolay,

Thanks for the feedback. I agree that it's more reasonable to have
different docs for user-space and kernel api. As long as our bridge developers
satisfied to maintain these 2 docs at the same time, I'm totally OK to drop
this bloated convert tool.

> W.r.t the kernel doc topics covered, I think the list is a good start.

Thanks, I will add more parts and re-post it next month.

Regards
Hangbin