linux-kernel - Re: [PATCH 23/31] gcc-plugins.txt: standardize document format

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20170525051827.0ed2b88e@vela.lan>
Date:   Thu, 25 May 2017 05:18:27 +0900
From:   Mauro Carvalho Chehab <mchehab@...pensource.com>
To:     Kees Cook <keescook@...gle.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        LKML <linux-kernel@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>,
        David Woodhouse <dwmw2@...radead.org>,
        Brian Norris <computersforpeace@...il.com>,
        Boris Brezillon <boris.brezillon@...e-electrons.com>,
        Marek Vasut <marek.vasut@...il.com>,
        Richard Weinberger <richard@....at>,
        Cyrille Pitchen <cyrille.pitchen@...el.com>,
        Linux mtd <linux-mtd@...ts.infradead.org>,
        Emese Revfy <re.emese@...il.com>,
        "kernel-hardening@...ts.openwall.com" 
        <kernel-hardening@...ts.openwall.com>
Subject: Re: [PATCH 23/31] gcc-plugins.txt: standardize document format

Em Wed, 24 May 2017 10:35:42 -0700
Kees Cook <keescook@...gle.com> escreveu:

> On Thu, May 18, 2017 at 6:22 PM, Mauro Carvalho Chehab
> <mchehab@...pensource.com> wrote:
> > Each text file under Documentation follows a different
> > format. Some doesn't even have titles!
> >
> > Change its representation to follow the adopted standard,
> > using ReST markups for it to be parseable by Sphinx:
> >
> > - promote main title;
> > - use the right markup for footnotes;
> > - use bold markup for files name;
> > - identify literal blocks;
> > - add blank lines to avoid Sphinx to complain;
> > - remove numeration from titles.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@...pensource.com>  
> 
> Acked-by: Kees Cook <keescook@...omium.org>
> 
> This should probably get moved under "Kernel API documentation" but
> may need a new sub-category, maybe "instrumentation"? Things like
> KASan could be put under that too.

Yeah, I guess that most documents under Documentation/
will need to be renamed and placed into an existing or new book.

Kasan documentation is currently under dev-tools, with is, currently,
an unsorted book with:

   coccinelle
   sparse
   kcov
   gcov
   kasan
   ubsan
   kmemleak
   kmemcheck
   gdb-kernel-debugging
   kgdb

I agree with you: it probably makes sense to split external development
tools, like coccinelle/sparse from Kernel instrumentation, like kgdb,
kasan, gcc-plugins, etc.

So, perhaps we can change the content of Documentation/dev-tools/index.rst
to something like.


================================
Development tools for the kernel
================================

This document describe tools and instrumentation features of the Linux Kernel
used by developers to do quality assurance (QA).

This section describes Kernel internal features designed to provide mechanisms
for developers to test their code.

.. toctree::
   :maxdepth: 2

   (add here books like kasan, printk related docs, gcc-plugins, etc)

This section describes external tools used to ensure Kernel quality
assurance (QA).

.. toctree::
   :maxdepth: 2

   (add here books related external tools and robots, like coccinelle,
    sparse, kernel build robot, ktest, Coverity, etc)

.. only::  subproject and html

   Indices
   =======

   * :ref:`genindex`



Cheers,
Mauro