Re: [f2fs-dev] [PATCH] docs: f2fs: fix a broken table

Re: [f2fs-dev] [PATCH] docs: f2fs: fix a broken table

[Eric Biggers]

On Mon, Jun 22, 2020 at 07:39:07AM -0600, Jonathan Corbet wrote:
> Commit ed318a6cc0b6 ("fscrypt: support test_dummy_encryption=v2") added an
> entry to the massive option table in Documentation/filesystems/f2fs.txt.
> The option was too wide for the formatting of the table, though, leading to
> a verbose and ugly docs-build warning starting with:
> 
>     Documentation/filesystems/f2fs.rst:229: WARNING: Malformed table.
>     Text in column margin in table line 126.
> 
> Fixing this requires formatting the whole table; let's hear it for Emacs
> query-replace-regexp.  No changes were made to the actual text.
> 
> Fixes: ed318a6cc0b6 ("fscrypt: support test_dummy_encryption=v2")
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
>  Documentation/filesystems/f2fs.rst | 312 ++++++++++++++---------------
>  1 file changed, 156 insertions(+), 156 deletions(-)
> 

Someone already sent out a fix for this:
https://lkml.kernel.org/linux-doc/52f851cb5c9fd2ecae97deec7e168e66b8c295c3.1591137229.git.mchehab+huawei@kernel.org/

Is it intentional that you're sending out a different fix rather than applying
that one?

- Eric


_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel

Re: [f2fs-dev] [PATCH] docs: f2fs: fix a broken table

[Jonathan Corbet]

On Mon, 22 Jun 2020 10:11:06 -0700
Eric Biggers <ebiggers@kernel.org> wrote:

> Someone already sent out a fix for this:
> https://lkml.kernel.org/linux-doc/52f851cb5c9fd2ecae97deec7e168e66b8c295c3.1591137229.git.mchehab+huawei@kernel.org/
> 
> Is it intentional that you're sending out a different fix rather than applying
> that one?

It wasn't, actually, I'm just finding myself more than usually challenged
these days.

That said, removing the table entirely seems ... excessive.  It's not
terrible the way it is, or we could make it:

	test_dummy_encryption[=%s]

if we really want to.

jon


_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel

Re: [f2fs-dev] [PATCH] docs: f2fs: fix a broken table

[Mauro Carvalho Chehab]

Em Mon, 22 Jun 2020 11:22:09 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon, 22 Jun 2020 10:11:06 -0700
> Eric Biggers <ebiggers@kernel.org> wrote:
> 
> > Someone already sent out a fix for this:
> > https://lkml.kernel.org/linux-doc/52f851cb5c9fd2ecae97deec7e168e66b8c295c3.1591137229.git.mchehab+huawei@kernel.org/

No problem from my side.

> > 
> > Is it intentional that you're sending out a different fix rather than applying
> > that one?  
> 
> It wasn't, actually, I'm just finding myself more than usually challenged
> these days.
> 
> That said, removing the table entirely seems ... excessive.  It's not
> terrible the way it is, or we could make it:

Jon,

I actually tried a patch close to yours before the patch I actually sent
upstream.

On my previous version, I was doing:

======================== =======================================================
...
test_dummy_encryption
test_dummy_encryption=%s Enable dummy encryption, which provides a fake fscrypt
			 context. The fake fscrypt context is used by xfstests.
			 The argument may be either "v1" or "v2", in order to
			 select the corresponding fscrypt policy version.
...
======================== =======================================================

The problem with the above is that Sphinx understood the first line as one row,
and the second one as a different one. So, the HTML output would be like:

<table>
...
<tr><td>test_dummy_encryption</td></tr>
<tr><td>test_dummy_encryption=%s</td>
<td>Enable dummy encryption, which provides a fake fscrypt
    context. The fake fscrypt context is used by xfstests.
    The argument may be either "v1" or "v2", in order to
    select the corresponding fscrypt policy version.</td>
</tr>

(e. g. it would look like the first parameter lacks description)

Which is not the intended result. I was unable to identify a way 
to teach Sphinx that the second line was a continuation of the
first (A ReST equivalent to placing a \ at the end of a line).

Still, the html output with the above is not that bad, and it should be clear
for readers that the description of the second parameter is also valid for the
first.


Thanks,
Mauro


_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel