linux-kernel - Re: [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST markup

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]

Date:   Tue, 13 Sep 2016 05:46:48 -0300
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Joe Perches <joe@...ches.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        Markus Heiser <markus.heiser@...marit.de>,
        Jonathan Corbet <corbet@....net>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        LKML <linux-kernel@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Jean Delvare <jdelvare@...e.de>,
        Manuel Pégourié-Gonnard <mpg@...evir.fr>,
        Thomas Gardner <tmg@...tmail.com>
Subject: Re: [PATCH v2 05/20] docs-rst: CodingStyle.rst: Convert to ReST
 markup

Em Mon, 12 Sep 2016 19:59:00 -0700
Joe Perches <joe@...ches.com> escreveu:

> On Mon, 2016-09-12 at 23:17 -0300, Mauro Carvalho Chehab wrote:
> > - Fix all chapter identation;
> > - add c blocks where needed;  
> 
> Assuming this is really useful and people agree with simple
> conversions of .txt to .rst (and it does have some use),
> there are a couple funky conversions
> 
> 	if (condition)
> 		do_this();
> 	else
> 		do_that();
> 
> do_that() is oddly displayed in the code_block

Yeah, Sphinx uses pygments to colorize C blocks, with seems to be buggy.

We could use a block of type none, forcing it to not using pygments.
The question is: should we do it for just this block, for the entire
file or for all ReST files?

> 
> and in the "Spaces" section, the pointer description is wrong
> 
> "\* is adjacent"
> 
> other than that, looks good to me.

Thanks for review!

The following fixup patch should address the two pointed issues. I took
the shortest path: I just avoided highlights at the if/else block that
looked odd.

If you agree that this is the best solution, I'll fold it with the original
patch on a next version of this patchset.

Regards,
Mauro


diff --git a/Documentation/development-process/CodingStyle.rst b/Documentation/development-process/CodingStyle.rst
index 510063361b04..56f4a42922ab 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -181,7 +181,7 @@ Do not unnecessarily use braces where a single statement will do.
 
 and
 
-.. code-block:: c
+.. code-block:: none
 
 	if (condition)
 		do_this();
@@ -232,7 +232,7 @@ Do not add spaces around (inside) parenthesized expressions.  This example is
 	s = sizeof( struct file );
 
 When declaring pointer data or a function that returns a pointer type, the
-preferred use of ``\*`` is adjacent to the data name or function name and not
+preferred use of ``*`` is adjacent to the data name or function name and not
 adjacent to the type name.  Examples:
 
 .. code-block:: c

Thanks,
Mauro