* Re: [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst
2017-08-19 15:21 [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst Josh Holland
@ 2017-08-21 9:15 ` Jani Nikula
2017-08-21 12:58 ` Jonathan Corbet
2017-08-23 20:34 ` Josh Holland
2 siblings, 0 replies; 4+ messages in thread
From: Jani Nikula @ 2017-08-21 9:15 UTC (permalink / raw)
To: keyrings
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst
2017-08-19 15:21 [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst Josh Holland
2017-08-21 9:15 ` Jani Nikula
@ 2017-08-21 12:58 ` Jonathan Corbet
2017-08-23 20:34 ` Josh Holland
2 siblings, 0 replies; 4+ messages in thread
From: Jonathan Corbet @ 2017-08-21 12:58 UTC (permalink / raw)
To: keyrings
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst
2017-08-19 15:21 [PATCH 1/2] docs: Standardise capitalisation of section headers in core.rst Josh Holland
2017-08-21 9:15 ` Jani Nikula
2017-08-21 12:58 ` Jonathan Corbet
@ 2017-08-23 20:34 ` Josh Holland
2 siblings, 0 replies; 4+ messages in thread
From: Josh Holland @ 2017-08-23 20:34 UTC (permalink / raw)
To: keyrings
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
^ permalink raw reply [flat|nested] 4+ messages in thread