Am 18.10.2016 um 18:05 schrieb Mauro Carvalho Chehab <mche...@s-opensource.com>:
> Em Tue, 18 Oct 2016 16:27:54 +0100
> David Howells <dhowe...@redhat.com> escreveu:
>> Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:
>>> - Fix identatio for the document title;
>>> - remove its index;
>>> - create a table for hash algorithm to be used;
>>> - use quote blocks where needed;
>>> - use monotonic fonts for parameters;
>>> - adjust whitespaces and blank lines;
>>> - Fix case on section titles;
>>> - add it to the user's book.
>> Hmmm... I'm not entirely convinced that these changes are an improvement.
>> main usage of this file is as a text file, but the index has been removed and
>> it's now got weird markups in it that reduce the readability.
>> Can you please at least return the index? If these files are no longer meant
>> to be read as text files, why don't we just bite the bullet and convert the
>> whole lot to latex, docbook or texinfo?
> See the enclosed patch. I'm putting a ".." before each line in the index,
> so that those lines won't be processed by Sphinx when generating PDF or
> Btw, on the last rebase, I forgot to add it to the admin-guide book.
> So, the diff also does what's needed to put it there.
> With such changes, it will now be seen in HTML as:
> If you're ok with that, I'll be folding the changes with the previous
> diff --git a/Documentation/admin-guide/index.rst
> index 4d87487ba40c..4e5abbb4bbd5 100644
> --- a/Documentation/admin-guide/index.rst
> +++ b/Documentation/admin-guide/index.rst
> @@ -21,6 +21,7 @@ Contents:
> + module-signing
> diff --git a/Documentation/module-signing.txt
> similarity index 97%
> rename from Documentation/module-signing.txt
> rename to Documentation/admin-guide/module-signing.rst
> index 81e76d8c7b00..27e59498b487 100644
> --- a/Documentation/module-signing.txt
> +++ b/Documentation/admin-guide/module-signing.rst
> @@ -1,6 +1,19 @@
> Kernel module signing facility
> +.. CONTENTS
> +.. - Overview.
> +.. - Configuring module signing.
> +.. - Generating signing keys.
> +.. - Public keys in the kernel.
> +.. - Manually signing modules.
> +.. - Signed modules and stripping.
> +.. - Loading signed modules.
> +.. - Non-valid signatures and unsigned modules.
> +.. - Administering/protecting the private key.
just a small suggestion of mine ....
- Configuring module signing.
- Generating signing keys.
- Public keys in the kernel.
- Manually signing modules.
- Signed modules and stripping.
- Loading signed modules.
- Non-valid signatures and unsigned modules.
- Administering/protecting the private key.
should be enough.
Because the ".." seems unimpressive, some words about:
reST syntax is very clear and simple, there are only
* inline- and
E.g. ``foo()`` is a inline-markup and the block-markup is simply
done by indentation.
Everything what is indented at the same level, is a part of the
same block (and also a block in it self). Another available
construct is a *sub-block*, this is done by indenting one level
more then the surrounding block (see "Indentation" in ).
Said this, in the above example, first ".." is the intro of a
We already know/use blocks when we (e.g.) use a ".. code-block"
directive ... yes, all directives with a body are also blocks.
Directives are the way to *extend* the reST syntax, e.g. with the
*kernel-doc* directive, we extended the syntax to our needs.
Every block has to end with a blank line. E.g. take the
paragraphs in this mail. Except one, they are all at the same
level and separated by a blank line (see "Blank Lines" in ).
By this, we see that reST tries to build up a syntax which is
intuitive, so often we do not realize that the whitespace we are
using in ASCII files are a major part of the reST syntax ;-)
I hope my short explanation helps to become
more familiar with reST.
-- Markus --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html