[PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst

[PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst

[Josh Holland]

The table of contents in security/keys/core.rst had different
capitalisation to the section headers, which broke case-sensitive
search.

Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
---
 Documentation/security/keys/core.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
index 1648fa80b..7c39c595c 100644
--- a/Documentation/security/keys/core.rst
+++ b/Documentation/security/keys/core.rst
@@ -16,17 +16,17 @@ The key service can be configured on by enabling:
 
 This document has the following sections:
 
-	- Key overview
-	- Key service overview
-	- Key access permissions
-	- SELinux support
-	- New procfs files
-	- Userspace system call interface
-	- Kernel services
-	- Notes on accessing payload contents
-	- Defining a key type
-	- Request-key callback service
-	- Garbage collection
+	- Key Overview
+	- Key Service Overview
+	- Key Access Permissions
+	- SELinux Support
+	- New ProcFS Files
+	- Userspace System Call Interface
+	- Kernel Services
+	- Notes On Accessing Payload Contents
+	- Defining a Key Type
+	- Request-Key Callback Service
+	- Garbage Collection
 
 
 Key Overview
-- 
2.14.1

Re: [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst

[Jani Nikula]

On Sat, 19 Aug 2017, Josh Holland <anowlcalledjosh@gmail.com> wrote:
> The table of contents in security/keys/core.rst had different
> capitalisation to the section headers, which broke case-sensitive
> search.
>
> Signed-off-by: Josh Holland <anowlcalledjosh@gmail.com>
> ---
>  Documentation/security/keys/core.rst | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst
> index 1648fa80b..7c39c595c 100644
> --- a/Documentation/security/keys/core.rst
> +++ b/Documentation/security/keys/core.rst
> @@ -16,17 +16,17 @@ The key service can be configured on by enabling:
>  
>  This document has the following sections:
>  
> -	- Key overview
> -	- Key service overview
> -	- Key access permissions
> -	- SELinux support
> -	- New procfs files
> -	- Userspace system call interface
> -	- Kernel services
> -	- Notes on accessing payload contents
> -	- Defining a key type
> -	- Request-key callback service
> -	- Garbage collection
> +	- Key Overview
> +	- Key Service Overview
> +	- Key Access Permissions
> +	- SELinux Support
> +	- New ProcFS Files
> +	- Userspace System Call Interface
> +	- Kernel Services
> +	- Notes On Accessing Payload Contents
> +	- Defining a Key Type
> +	- Request-Key Callback Service
> +	- Garbage Collection

If you want to retain the contents in .rst for the benefit of reading
this as plain text, this is fine.

However, if you want to sphinxify things a little, you could make the
resulting html a little bit nicer with automatic links, and document
maintenance a little bit easier, by replacing the hand written contents
with:

.. contents::
   :local:

The maintainer's call, obviously.


BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst

[Jonathan Corbet]

On Mon, 21 Aug 2017 12:15:26 +0300
Jani Nikula <jani.nikula@linux.intel.com> wrote:

> However, if you want to sphinxify things a little, you could make the
> resulting html a little bit nicer with automatic links, and document
> maintenance a little bit easier, by replacing the hand written contents
> with:
> 
> .. contents::
>    :local:

I think this is what we should do.  I don't think that manually listing
the section heads buys a whole lot for readers of the docs, and
experience says they won't be kept in sync with the rest of the
document.  I'd much rather see a patch taking them out and letting Sphinx
do the work.

Part 2 looks fine, though, I'll apply that shortly.

Thanks,

jon

Re: [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst

[Josh Holland]

On 2017-08-21, Jonathan Corbet wrote:
> On Mon, 21 Aug 2017 12:15:26 +0300
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
> > However, if you want to sphinxify things a little, you could make the
> > resulting html a little bit nicer with automatic links, and document
> > maintenance a little bit easier, by replacing the hand written contents
> > with:
> > 
> > .. contents::
> >    :local:
> 
> I think this is what we should do.  I don't think that manually listing
> the section heads buys a whole lot for readers of the docs, and
> experience says they won't be kept in sync with the rest of the
> document.  I'd much rather see a patch taking them out and letting Sphinx
> do the work.

Ok, I'll send a patch in.

> Part 2 looks fine, though, I'll apply that shortly.

Great!

Thanks,

Josh