Re: [PATCH 00/13] Convert vfs.txt to vfs.rst

From: Randy Dunlap
Date: Sun Mar 17 2019 - 21:47:02 EST


On 3/12/19 9:09 PM, Tobin C. Harding wrote:
> Hi,
>
> This set converts the VFS overview documentation to RST format. I think
> I'm slowly getting better at structuring these conversions to ease
> review, if you disagree or you notice any way to further improve please
> say so.

Hi Tobin,

What does this patch set apply to? Maybe Jon's git tree?

I applied it to 5.1-rc1 with some forceful (minor) editing and ran
'make htmldocs' successfully, so

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

although there is at least one new field in struct file_operations: iopoll.

cheers.

> Patch set introduces no new warnings/errors to the html docs build
>
> $ make htmldocs 2> ../docs-pre-vfs.stderr
>
> Apply patch set
>
> $ make cleandocs
> $ make htmldocs 2> ../docs-post-vfs.stderr
> $ diff ../docs-pre-vfs.stderr ../docs-post-vfs.stderr
>
>
> Patch 1-4 - Whitespace fixes.
> Patch 5 - Adds the document title adornments (above and below)
> Patch 6 - Adds a SPDX license identifier
> Patch 7 - Fixes some custom indentation at the top of the file that will
> cause Sphinx to warn when we switch to .rst
> Patch 8 - Converts custom list format to use RST formatted lists, this
> is in preparation for switching to .rst
> Patch 9 - Adds '.. code-block:: c' and fixes indentation of code
> blocks. We rename the file to .rst in this patch (introducing
> some new warnings).
> Patch 10 - Adds back ticks to all the list items. This is in
> preparation for fixing the indentation in the next patch.
> This was found to help when reading both plain text and HTML.
> Patch 11 - Cleans up the lists, indentation and missing periods. This
> was kept separate to assist review. This patch is benign,
> the less meticulous reviewer could safely skip over this one
> quickly (this was the intention of separating these changes).
> Patch 12 - Fixes a few minor grammar mistakes I notice while reading the
> file, I'm taking bonus points for actually reading every word
> of the file and not just trying to haphazardly do the
> conversion like I have previously done :)
> Patch 13 - Fixes two remaining Sphinx warnings.
>
> If/when this goes in perhaps I, or someone else, will update the content
> to document a newer kernel version.
>
>
> thanks,
> Tobin.
>
>
> Tobin C. Harding (13):
> docs: filesystems: vfs: Remove space before tab
> docs: filesystems: vfs: Use uniform space after period.
> docs: filesystems: vfs: Use 72 character column width
> docs: filesystems: vfs: Use uniform spacing around headings
> docs: filesystems: vfs: Use correct initial heading
> docs: filesystems: vfs: Use SPDX identifier
> docs: filesystems: vfs: Fix pre-amble indentation
> docs: filesystems: vfs: Use list character for lists
> docs: filesystems: vfs: Add code-block and txt->RST
> docs: filesystems: vfs: Use ticks for listed items
> docs: filesystems: vfs: Clean up lists
> docs: filesystems: vfs: Do minor grammar fixes
> docs: filesystems: vfs: Use backticks to guard star
>
> Documentation/filesystems/index.rst | 1 +
> Documentation/filesystems/vfs.rst | 1279 +++++++++++++++++++++++++++
> Documentation/filesystems/vfs.txt | 1261 --------------------------
> 3 files changed, 1280 insertions(+), 1261 deletions(-)
> create mode 100644 Documentation/filesystems/vfs.rst
> delete mode 100644 Documentation/filesystems/vfs.txt
>


--
~Randy