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

From
Daniel Bristot de Oliveira <bristot@kernel.org>
Date
2021-10-19 13:19:09
Also in
lkml
Reply to
Jonathan Corbet, 2021-10-18
On 10/18/21 19:43, Jonathan Corbet wrote:
Daniel Bristot de Oliveira [off-list ref] writes:
quoted
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 <redacted>
Cc: John Kacur <jkacur@redhat.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Thomas Gleixner <redacted>
Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Cc: Daniel Bristot de Oliveira <bristot@kernel.org>
Cc: <redacted>
Cc: <redacted>
Cc: <redacted>
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
  
Thread (34 messages) 34 messages, 4 authors, last reply 2021-10-19
Keyboard shortcuts
hback out one level
jnext message in thread / next series-diff position
kprevious message in thread / previous series-diff position
ldrill in
Escclose help / fold thread tree
?toggle this help