linux-kernel - Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

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: <CANiq72n3MQnjenbQGBUKD+SqNzdGUyJW9zjTOVY4+6cKBRc9ig@mail.gmail.com>
Date:   Fri, 10 Jun 2022 18:08:43 +0200
From:   Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To:     Jani Nikula <jani.nikula@...ux.intel.com>
Cc:     Akira Yokosawa <akiyks@...il.com>,
        Jonathan Corbet <corbet@....net>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        "Maciej W. Rozycki" <macro@...am.me.uk>,
        Miguel Ojeda <ojeda@...nel.org>,
        linux-kernel <linux-kernel@...r.kernel.org>
Subject: Re: [RFC PATCH 3/5] docs/doc-guide: Update guidelines for title adornments

On Fri, Jun 10, 2022 at 11:11 AM Jani Nikula
<jani.nikula@...ux.intel.com> wrote:
>
> When I wrote the original guidelines, it was my subjective decision to
> steer towards using the same title adornment styles and ordering across
> the kernel documentation. I intentionally left out all the
> reStructuredText details about this, because the definitive
> documentation is the reStructuredText documentation we can refer to.
>
> While the "Nth level title" is a more precise description, I'm not sure
> it's actually helpful without describing how these levels should map to
> kernel documentation structure. (Not saying the original did that
> either, but then there wasn't much structure to speak of.)

To give a bit of context: this patch followed from a question I asked
to Jonathan and Akira privately. Currently it is hard to tell the
"nesting level", and even worse, existing files are not consistent and
checking is not automated. Therefore, an easy way to handle this is to
request to follow the same pattern regardless of nesting across the
tree.

> Improving the documentation on documentation is great, but I think it's
> a bad sign when length of the notes and warnings on something far exceed
> the length of the thing being documented. The bulk of the text should be
> helpful enough for people to DTRT, while leaving out exhaustive
> descriptions of all the details that should just be references to
> reStructuredText documentation.

Perhaps we can move the rationale to the commit message, and keep only
the current rules in the document. What about something like:

"""
Please stick to this relative order of adornments within each file
(i.e. regardless of nesting level across the kernel tree):

    1. ``=`` with overline.
    2. ``=``.
    3. ``-``.
    4. ``~``.

For instance::

    =====
    First
    =====

    Second
    ======

    Third
    -----

    Fourth
    ~~~~~~
"""

Cheers,
Miguel