linux-kernel - Re: [PATCH] docs: rtla: replace dashes with spaces in titles

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

Date:   Wed, 2 Aug 2023 09:12:44 +0200
From:   Daniel Bristot de Oliveira <bristot@...nel.org>
To:     Costa Shulyupin <costa.shul@...hat.com>,
        Steven Rostedt <rostedt@...dmis.org>,
        Jonathan Corbet <corbet@....net>,
        linux-trace-kernel@...r.kernel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs: rtla: replace dashes with spaces in titles

On 8/2/23 05:50, Costa Shulyupin wrote:
> because
> - Titles containing spaces offer better readability compared
>   to those with dashes
> - Commands and their described subcommands are separated by spaces
> - Ensure that the titles are identical to the commands with subcommands

I added the - because that is how we call the man-pages:

man rtla-osnoise-top
--------------- %< ----------------------
RTLA-OSNOISE-TOP(1)                                                                                                                                                    RTLA-OSNOISE-TOP(1)

NAME
       rtla-osnoise-top - Display a summary of the operating system noise

SYNOPSIS
       rtla osnoise top [OPTIONS]
--------------- %< ----------------------


and it is also inline with other kernel tools, like perf:

man perf-record
--------------- %< ----------------------
PERF-RECORD(1)                                                                          perf Manual                                                                         PERF-RECORD(1)

NAME
       perf-record - Run a command and record its profile into perf.data

SYNOPSIS
       perf record [-e <EVENT> | --event=EVENT] [-a] <command>
       perf record [-e <EVENT> | --event=EVENT] [-a] -- <command> [<options>]
--------------- %< ----------------------

also...

[bristot@x1 rtla]$ make
rst2man --verbose rtla-hwnoise.rst > rtla-hwnoise.1
rst2man --verbose rtla-osnoise-hist.rst > rtla-osnoise-hist.1
rtla-osnoise-hist.rst:1: (ERROR/3) Invalid section title or transition marker.

===================
===================
rst2man --verbose rtla-osnoise.rst > rtla-osnoise.1
rtla-osnoise.rst:1: (ERROR/3) Invalid section title or transition marker.

===============
===============
rtla-osnoise.rst:3: (SEVERE/4) Missing matching underline for section title overline.

------------------------------------------------------------------
rtla osnoise
Measure the operating system noise
Exiting due to level-4 (SEVERE) system message.
make: *** [Makefile:36: rtla-osnoise.1] Error 1
[bristot@x1 rtla]$


> Signed-off-by: Costa Shulyupin <costa.shul@...hat.com>