linux-kernel - Re: [PATCH 0/5] Documentation: nfs: convert remaining files 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] [day] [month] [year] [list]

Message-ID: <20200117103219.75de4b99@lwn.net>
Date:   Fri, 17 Jan 2020 10:32:19 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Daniel W. S. Almeida" <dwlsalmeida@...il.com>
Cc:     mchehab+samsung@...nel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, skhan@...uxfoundation.org,
        linux-kernel-mentees@...ts.linuxfoundation.org
Subject: Re: [PATCH 0/5] Documentation: nfs: convert remaining files to
 ReST.

On Mon, 30 Dec 2019 02:04:42 -0300
"Daniel W. S. Almeida" <dwlsalmeida@...il.com> wrote:

> This series completes the conversion of Documentation/filesystems/nfs to ReST.

OK, I've made a quick pass through these.  They are mostly OK, with a
couple of exceptions.  One is that it has the "#." problem in enumerated
lists, which needs to be fixed as was done with the previous set.

And then there is:

> Note that I chose csv-table over list-table because csv files are easier
> to export from other software. 

That leads to results that look like this:

> +Operations
> +==========
> +
> +.. csv-table::
> +   :header: "Implementation status", "Operation", "REQ, REC, OPT or NMI", "Feature (REQ, REC or OPT)", "Definition"
> +   :widths: auto
> +   :delim: ;
> +
> +   ;"ACCESS";"REQ";;"Section 18.1"
> +   "I";"BACKCHANNEL_CTL";"REQ";;"Section 18.33"
> +   "I";"BIND_CONN_TO_SESSION";"REQ";;"Section 18.34"
> +   ;"CLOSE";"REQ";;"Section 18.2"
> +   ;"COMMIT";"REQ";;"Section 18.3"
> +   ;"CREATE";"REQ";;"Section 18.4"

...and that is essentially unreadable.  Remember that the plain-text
format matters too, so we can't do it this way.

The original is in something fairly close to the RST multicell table
format already; it shouldn't be too hard to add the tweaks needed to make
sphinx happy...?

Thanks,

jon