Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <845391b2-12f6-86b6-9ce6-19e16edbfce1@kernel.org>
Date:   Wed, 2 Aug 2023 09:12:44 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.12.0
Subject: Re: [PATCH] docs: rtla: replace dashes with spaces in titles
To:     Costa Shulyupin <costa.shul@redhat.com>,
        Steven Rostedt <rostedt@goodmis.org>,
        Jonathan Corbet <corbet@lwn.net>,
        linux-trace-kernel@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
References: <20230802035037.404230-1-costa.shul@redhat.com>
Content-Language: en-US, pt-BR, it-IT
From:   Daniel Bristot de Oliveira <bristot@kernel.org>
In-Reply-To: <20230802035037.404230-1-costa.shul@redhat.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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@redhat.com>