Re: [PATCH V3 13/19] rtla: Add Documentation

From: Daniel Bristot de Oliveira <bristot@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Ingo Molnar <mingo@redhat.com>, Tom Zanussi <zanussi@kernel.org>,
	Masami Hiramatsu <mhiramat@kernel.org>,
	Juri Lelli <juri.lelli@redhat.com>,
	Clark Williams <williams@redhat.com>,
	John Kacur <jkacur@redhat.com>,
	Peter Zijlstra <peterz@infradead.org>,
	Thomas Gleixner <tglx@linutronix.de>,
	Sebastian Andrzej Siewior <bigeasy@linutronix.de>,
	linux-rt-users@vger.kernel.org,
	linux-trace-devel@vger.kernel.org, linux-kernel@vger.kernel.org,
	Steven Rostedt <rostedt@goodmis.org>
Subject: Re: [PATCH V3 13/19] rtla: Add Documentation
Date: Tue, 19 Oct 2021 14:56:15 +0200	[thread overview]
Message-ID: <f0c50222-a9a8-d0e5-d705-d9d670467142@kernel.org> (raw)
In-Reply-To: <877deaut3b.fsf@meer.lwn.net>

On 10/18/21 19:43, Jonathan Corbet wrote:
> Daniel Bristot de Oliveira <bristot@kernel.org> writes:
> 
>> Adds the basis for rtla documentation. It is based on libtracefs
>> Documentation as suggested by Steven Rostedt. This patch also
>> includes the rtla(1) man page.
>>
>> Cc: Steven Rostedt <rostedt@goodmis.org>
>> Cc: Ingo Molnar <mingo@redhat.com>
>> Cc: Tom Zanussi <zanussi@kernel.org>
>> Cc: Masami Hiramatsu <mhiramat@kernel.org>
>> Cc: Juri Lelli <juri.lelli@redhat.com>
>> Cc: Clark Williams <williams@redhat.com>
>> Cc: John Kacur <jkacur@redhat.com>
>> Cc: Peter Zijlstra <peterz@infradead.org>
>> Cc: Thomas Gleixner <tglx@linutronix.de>
>> Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
>> Cc: Daniel Bristot de Oliveira <bristot@kernel.org>
>> Cc: linux-rt-users@vger.kernel.org
>> Cc: linux-trace-devel@vger.kernel.org
>> Cc: linux-kernel@vger.kernel.org
>> Suggested-by: Steven Rostedt <rostedt@goodmis.org>
>> Signed-off-by: Daniel Bristot de Oliveira <bristot@kernel.org>
>> ---
>>  tools/tracing/rtla/Documentation/Makefile     | 223 ++++++++++++++++++
>>  .../tracing/rtla/Documentation/asciidoc.conf  | 118 +++++++++
>>  .../rtla/Documentation/manpage-base.xsl       |  35 +++
>>  .../rtla/Documentation/manpage-normal.xsl     |  13 +
>>  tools/tracing/rtla/Documentation/rtla.txt     |  56 +++++
>>  tools/tracing/rtla/Documentation/utils.mk     | 144 +++++++++++
>>  tools/tracing/rtla/Makefile                   |  20 +-
>>  7 files changed, 604 insertions(+), 5 deletions(-)
>>  create mode 100644 tools/tracing/rtla/Documentation/Makefile
>>  create mode 100644 tools/tracing/rtla/Documentation/asciidoc.conf
>>  create mode 100644 tools/tracing/rtla/Documentation/manpage-base.xsl
>>  create mode 100644 tools/tracing/rtla/Documentation/manpage-normal.xsl
>>  create mode 100644 tools/tracing/rtla/Documentation/rtla.txt
>>  create mode 100644 tools/tracing/rtla/Documentation/utils.mk
> 
> So please forgive me for being obnoxious but I have to ask...do we
> *really* need to add yet another markup language and docs build
> infrastructure to the kernel?  I'm glad to see documentation, of course,
> but I would be gladder if it weren't a silo completely separate from the
> rest of the kernel docs.  Is there a reason why this couldn't have been
> done with Sphinx?

I am not a document format specialist, neither have a strong opinion on this, so
suggestions are welcome. I used this format as a suggestion from steven, it is
also similar to what we have on perf...

The idea here is to create a set of man pages. I saw that it is possible to
create man pages using Sphinx, but there are so many options that it is hard to
get started...

I also noticed that bpftools uses .rst files, but uses rst2man to convert the files.

Converting the current files to .rst is easy.

So, could give me some directions on what you think would be the best way to
create this set of man pages?

A link to a project that creates a set of man pages using Sphinx using a
Makefile would be a plus :-).

-- Daniel

> 
> Thanks,
> 
> jon
> 