linux-kernel - Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems: Convert sysfs-pci to ReST

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: <CABhMZUUqERRO-4EWabuesK5+ZQNzOFQmaND-tw7j4q5D8UX33g@mail.gmail.com>
Date:   Tue, 31 Mar 2020 21:33:03 -0500
From:   Bjorn Helgaas <bjorn.helgaas@...il.com>
To:     Jonathan Corbet <corbet@....net>
Cc:     Vitor Massaru Iha <vitor@...saru.org>,
        linux-kernel-mentees@...ts.linuxfoundation.org,
        Brendan Higgins <brendanhiggins@...gle.com>,
        LKML <linux-kernel@...r.kernel.org>,
        "open list:DOCUMENTATION" <linux-doc@...r.kernel.org>,
        Mathew Wilcox <willy@...radead.org>
Subject: Re: [Linux-kernel-mentees] [PATCH 1/2] Documentation: filesystems:
 Convert sysfs-pci to ReST

On Tue, Mar 31, 2020 at 5:57 PM Jonathan Corbet <corbet@....net> wrote:
>
> On Tue, 31 Mar 2020 19:28:56 -0300
> Vitor Massaru Iha <vitor@...saru.org> wrote:
>
> > Signed-off-by: Vitor Massaru Iha <vitor@...saru.org>
> > ---
> >  .../{sysfs-pci.txt => sysfs-pci.rst}          | 40 ++++++++++---------
> >  1 file changed, 22 insertions(+), 18 deletions(-)
> >  rename Documentation/filesystems/{sysfs-pci.txt => sysfs-pci.rst} (82%)
>
> Please supply a changelog with your patches.
>
> The conversion you have done in this file is incomplete; I suspect that
> you have not actually built the docs and seen what the results look like.
> There are literal blocks that you have not marked as such, as a minimum.
> Please actually do a docs build (after adding this file to index.rst) and
> make sure that the output is what you intended.
>
> One other thing of note...this file dates back to before the Git era, and
> while it has seen numerous tweaks since then, it's clearly outdated.  Look
> at what's actually under /sys/devices/pci* compared to what's documented.
> I will take the conversion without it, but what I would really like to see
> would be an effort to document all of the attributes that appear there
> with current kernels.

If you do go ahead and add/change content (as opposed to simply doing
the .txt -> .rst conversion), please do the conversion and the content
changes in separate patches.  That way the content changes will be
easier to review because they won't be mixed in with a lot of
mechanical .rst changes.

Bjorn