Am 18.10.2016 um 18:05 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>: > Em Tue, 18 Oct 2016 16:27:54 +0100 > David Howells <dhowells@xxxxxxxxxx> escreveu: > >> Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> 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. The >> 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 > HTML. > > 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: > https://mchehab.fedorapeople.org/kernel_docs/admin-guide/module-signing.html > > If you're ok with that, I'll be folding the changes with the previous > patches. > > Regards, > Mauro > > > diff --git a/Documentation/admin-guide/index.rst b/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: > braille-console > parport > md > + module-signing > sysrq > unicode > vga-softcursor > diff --git a/Documentation/module-signing.txt b/Documentation/admin-guide/module-signing.rst > 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 .... .. 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. should be enough. --- Because the ".." seems unimpressive, some words about: reST syntax is very clear and simple, there are only * inline- and * block-markups. 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 [1]). Said this, in the above example, first ".." is the intro of a comment block. 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 [1]). 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 ;-) [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#whitespace I hope my short explanation helps to become more familiar with reST. -- Markus -- > ======== > Overview > ======== > > > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > 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 majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
