Message-ID: <20160818174630.4abdf25d@lwn.net>
Date:   Thu, 18 Aug 2016 17:46:30 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Christoph Hellwig <hch@...radead.org>
Cc:     Daniel Vetter <daniel.vetter@...ll.ch>,
        Jani Nikula <jani.nikula@...el.com>, linux-doc@...r.kernel.org,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

On Tue, 9 Aug 2016 01:31:06 -0700
Christoph Hellwig <hch@...radead.org> wrote:

> On Tue, Aug 09, 2016 at 10:28:38AM +0200, Daniel Vetter wrote:
> > The point is to make the docs more discoverable by being able to
> > cross-link them. Old hats like us don't need that, but it definitely
> > has value in bringing new folks on board.  
> 
> But do that in a way that keeps the old hats happy.  The crazy use of
> punctuation and the weird quotes is an absolute no-go.

So would the old hats be happier with a patch that looks like this?  The
quality of the formatted output suffers slightly, but it's not a big
deal...

Thanks,

jon

>From d228af5bcb60fda50f8b3a100c0539c4994df040 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@....net>
Date: Sun, 7 Aug 2016 15:09:14 -0600
Subject: [PATCH] docs: sphinxify sparse.txt and move to dev-tools

Fold the sparse document into the development tools set; no changes to the
text itself beyond formatting.

Signed-off-by: Jonathan Corbet <corbet@....net>
---
 Documentation/{sparse.txt => dev-tools/sparse.rst} | 39 +++++++++++++---------
 Documentation/dev-tools/tools.rst                  |  1 +
 2 files changed, 25 insertions(+), 15 deletions(-)
 rename Documentation/{sparse.txt => dev-tools/sparse.rst} (82%)

diff --git a/Documentation/sparse.txt b/Documentation/dev-tools/sparse.rst
similarity index 82%
rename from Documentation/sparse.txt
rename to Documentation/dev-tools/sparse.rst
index eceab13..8c250e8 100644
--- a/Documentation/sparse.txt
+++ b/Documentation/dev-tools/sparse.rst
@@ -1,11 +1,20 @@
-Copyright 2004 Linus Torvalds
-Copyright 2004 Pavel Machek <pavel@....cz>
-Copyright 2006 Bob Copeland <me@...copeland.com>
+.. Copyright 2004 Linus Torvalds
+.. Copyright 2004 Pavel Machek <pavel@....cz>
+.. Copyright 2006 Bob Copeland <me@...copeland.com>
+
+Sparse
+======
+
+Sparse is a semantic checker for C programs; it can be used to find a
+number of potential problems with kernel code.  See
+https://lwn.net/Articles/689907/ for an overview of sparse; this document
+contains some kernel-specific sparse information.
+
 
 Using sparse for typechecking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
-"__bitwise" is a type attribute, so you have to do something like this:
+"__bitwise" is a type attribute, so you have to do something like this::
 
         typedef int __bitwise pm_request_t;
 
@@ -20,13 +29,13 @@ but in this case we really _do_ want to force the conversion). And because
 the enum values are all the same type, now "enum pm_request" will be that
 type too.
 
-And with gcc, all the __bitwise/__force stuff goes away, and it all ends
-up looking just like integers to gcc.
+And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all
+ends up looking just like integers to gcc.
 
 Quite frankly, you don't need the enum there. The above all really just
 boils down to one special "int __bitwise" type.
 
-So the simpler way is to just do
+So the simpler way is to just do::
 
         typedef int __bitwise pm_request_t;
 
@@ -50,7 +59,7 @@ __bitwise - noisy stuff; in particular, __le*/__be* are that.  We really
 don't want to drown in noise unless we'd explicitly asked for it.
 
 Using sparse for lock checking
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 The following macros are undefined for gcc and defined during a sparse
 run to use the "context" tracking feature of sparse, applied to
@@ -69,22 +78,22 @@ annotation is needed.  The tree annotations above are for cases where
 sparse would otherwise report a context imbalance.
 
 Getting sparse
-~~~~~~~~~~~~~~
+--------------
 
 You can get latest released versions from the Sparse homepage at
 https://sparse.wiki.kernel.org/index.php/Main_Page
 
 Alternatively, you can get snapshots of the latest development version
-of sparse using git to clone..
+of sparse using git to clone::
 
         git://git.kernel.org/pub/scm/devel/sparse/sparse.git
 
-DaveJ has hourly generated tarballs of the git tree available at..
+DaveJ has hourly generated tarballs of the git tree available at::
 
         http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
 
 
-Once you have it, just do
+Once you have it, just do::
 
         make
         make install
@@ -92,7 +101,7 @@ Once you have it, just do
 as a regular user, and it will install sparse in your ~/bin directory.
 
 Using sparse
-~~~~~~~~~~~~
+------------
 
 Do a kernel make with "make C=1" to run sparse on all the C files that get
 recompiled, or use "make C=2" to run sparse on the files whether they need to
@@ -101,7 +110,7 @@ have already built it.
 
 The optional make variable CF can be used to pass arguments to sparse.  The
 build system passes -Wbitwise to sparse automatically.  To perform endianness
-checks, you may define __CHECK_ENDIAN__:
+checks, you may define __CHECK_ENDIAN__::
 
         make C=2 CF="-D__CHECK_ENDIAN__"
 
diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst
index ae0c58c..d4bbda3 100644
--- a/Documentation/dev-tools/tools.rst
+++ b/Documentation/dev-tools/tools.rst
@@ -15,3 +15,4 @@ whole; patches welcome!
    :maxdepth: 2
 
    coccinelle
+   sparse
-- 
2.9.3

Powered by blists - more mailing lists