linux-kernel - [PATCH 0/9] docs: Fix various build warnings/errors

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-next>] [day] [month] [year] [list]

Message-Id: <20190307211153.28400-1-tobin@kernel.org>
Date:   Fri,  8 Mar 2019 08:11:44 +1100
From:   "Tobin C. Harding" <tobin@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     "Tobin C. Harding" <tobin@...nel.org>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [PATCH 0/9] docs: Fix various build warnings/errors

Hi,

I had a few hours to spare so I thought I'd clear some Sphinx build
warnings/errors.  There isn't anything too controversial here.  The only
interesting thing I hit was in patch 7 (docs: Remove unknown 'hint'
directive), I couldn't work out if this was a serious directive, a joke,
or a typo.  Please review that patch more carefully than the others.

Patch 4 adds :ref: and raises an issue I've come across a few times now,
could I have your opinion on it please (if you have the time/inclination
to share it)

:ref:`/Documentation/path/to/file.rst <label>`

vs

:ref:`label`

Undeniably the second is better in HTML.  The first is, on one hand,
arguable better to parse when reading the textual file (since you can
see which file it refers to) but on the other hand kinda looks ugly
since it often line wraps poorly and is a bit cluttered if all you want to
see is the path.  Having only the label doesn't _really_ make it worse
in text because often you already know (or don't care) what the path is
(e.g. when there are multiple refs to the same label) and if you do care
you can just grep the docs for the label.

Do you have an opinion on this?

Oh also, do you have a script by any chance that does a clean build of
the docs, saves stderr output, applies a patch, cleanly re-builds the
docs and then diffs the two outputs?  Then rinse-and-repeat for a whole
patch series. Thought I'd ask before I write one.

thanks,
Tobin.

Tobin C. Harding (9):
  docs: Fix spelling mistake
  docs: Add colon clearing sphinx warning
  docs: Remove unnecessary reference link title
  docs: Use reference to link to rst file
  docs: Replace backtick with apostrophe.
  docs: Use correct list markup character
  docs: Remove unknown 'hint' directive
  docs: Fix Title underline too short warning
  docs: Add blank line after SPDX licence identifier

 .../admin-guide/mm/numa_memory_policy.rst     |  9 ++-
 .../driver-api/dmaengine/dmatest.rst          |  4 +-
 Documentation/driver-api/gpio/board.rst       |  5 +-
 Documentation/filesystems/path-lookup.rst     | 24 ++++----
 Documentation/laptops/lg-laptop.rst           | 13 +++--
 Documentation/misc-devices/ibmvmc.rst         |  1 +
 Documentation/networking/snmp_counter.rst     | 58 +++++++++----------
 Documentation/process/howto.rst               |  2 +-
 Documentation/vm/numa.rst                     |  4 +-
 Documentation/vm/slub.rst                     |  2 +-
 include/linux/kernel.h                        |  2 +-
 include/linux/wait.h                          |  2 +-
 12 files changed, 64 insertions(+), 62 deletions(-)

-- 
2.21.0