netdev - Re: [PATCH net v2 1/2] docs: networking: convert DIM to RST

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: <20200409160658.1b940fcf@kicinski-fedora-PC1C0HJN>
Date:   Thu, 9 Apr 2020 16:06:58 -0700
From:   Jakub Kicinski <kuba@...nel.org>
To:     Saeed Mahameed <saeedm@...lanox.com>
Cc:     "davem@...emloft.net" <davem@...emloft.net>,
        "jacob.e.keller@...el.com" <jacob.e.keller@...el.com>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>,
        "netdev@...r.kernel.org" <netdev@...r.kernel.org>,
        "rdunlap@...radead.org" <rdunlap@...radead.org>,
        Tal Gilboa <talgi@...lanox.com>,
        "leon@...nel.org" <leon@...nel.org>
Subject: Re: [PATCH net v2 1/2] docs: networking: convert DIM to RST

On Thu, 9 Apr 2020 22:46:55 +0000 Saeed Mahameed wrote:
> On Thu, 2020-04-09 at 14:21 -0700, Jakub Kicinski wrote:
> > Convert the Dynamic Interrupt Moderation doc to RST and
> > use the RST features like syntax highlight, function and
> > structure documentation, enumerations, table of contents.
> > 
> > Signed-off-by: Jakub Kicinski <kuba@...nel.org>
> > Reviewed-by: Randy Dunlap <rdunlap@...radead.org>
> > ---
> > v2:
> >  - remove the functions/type definition markup
> >  - change the contents definition (the :local: seem to
> >    not work too well with kdoc)
> > ---
> >  Documentation/networking/index.rst            |  1 +
> >  .../networking/{net_dim.txt => net_dim.rst}   | 90 +++++++++------
> > ----
> >  MAINTAINERS                                   |  1 +
> >  3 files changed, 45 insertions(+), 47 deletions(-)
> >  rename Documentation/networking/{net_dim.txt => net_dim.rst} (79%)
> > 
> > diff --git a/Documentation/networking/index.rst
> > b/Documentation/networking/index.rst
> > index 50133d9761c9..6538ede29661 100644
> > --- a/Documentation/networking/index.rst
> > +++ b/Documentation/networking/index.rst
> > @@ -22,6 +22,7 @@ Linux Networking Documentation
> >     z8530book
> >     msg_zerocopy
> >     failover
> > +   net_dim  
> 
> net_dim is a performance feature, i would move further down the list
> where the perf features such as scaling and offloads are .. 

I mean.. so is msg_zerocopy just above ;-)  I spotted slight
alphabetical ordering there, which may have not been intentional,
that's why I put it here. Marking with # things out of order, but 
based on just the first letter:

#  netdev-FAQ
   af_xdp
   bareudp
   batman-adv
   can
   can_ucan_protocol
   device_drivers/index
   dsa/index
   devlink/index
   ethtool-netlink
   ieee802154
   j1939
   kapi
#  z8530book
   msg_zerocopy
#  failover
   net_dim
   net_failover
   phy
   sfp-phylink
#  alias
#  bridge
   snmp_counter
#  checksum-offloads
   segmentation-offloads
   scaling
   tls
   tls-offload
#  nfc
   6lowpan

My feeling is that we should start considering splitting kernel-only
docs and admin-only docs for networking, which I believe is the
direction Jon and folks want Documentation/ to go. But I wasn't brave
enough to be the first one. Then we can impose some more structure,
like putting all "performance" docs in one subdir..?

WDYT?