Converting manpages from asciidoc to rst2man ?

Converting manpages from asciidoc to rst2man ?

[Dimitri John Ledkov]

Hi all,

I was going through build-depends on linux kernel in Ubuntu and I
noticed that whilst most documentation and man-pages are written in
Rst format, there are a few that require asciidoc.

$ git grep -l asciidoc -- '*Makefile*'
tools/kvm/kvm_stat/Makefile
tools/lib/perf/Documentation/Makefile
tools/perf/Documentation/Makefile
tools/perf/Makefile.perf

$ git grep -l rst2man -- '*Makefile*'
Documentation/tools/rtla/Makefile
Documentation/tools/rv/Makefile
tools/bpf/bpftool/Documentation/Makefile
tools/testing/selftests/bpf/Makefile.docs

Are both Rst and asciidoc preferred in the kernel Documentation? Or
should we upgrade kvm_stat & perf manpages from asciidoc to rst2man?

-- 
Dimitri

Re: Converting manpages from asciidoc to rst2man ?

[Jonathan Corbet]

Dimitri John Ledkov <dimitri.ledkov@canonical.com> writes:

> Hi all,
>
> I was going through build-depends on linux kernel in Ubuntu and I
> noticed that whilst most documentation and man-pages are written in
> Rst format, there are a few that require asciidoc.
>
> $ git grep -l asciidoc -- '*Makefile*'
> tools/kvm/kvm_stat/Makefile
> tools/lib/perf/Documentation/Makefile
> tools/perf/Documentation/Makefile
> tools/perf/Makefile.perf

Interesting...I was unaware of those...

> Are both Rst and asciidoc preferred in the kernel Documentation? Or
> should we upgrade kvm_stat & perf manpages from asciidoc to rst2man?

In general we don't have a lot of man pages in the kernel, so it's not
something we've put a lot of thought into.  Ideally, I suppose, it would
be nice to get all of those man pages integrated into the RST docs
build, but it's not something that is likely to inspire any great sense
of urgency.

Thanks,

jon

Re: Converting manpages from asciidoc to rst2man ?

[Ian Rogers]

On Mon, Dec 4, 2023 at 6:36 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> Dimitri John Ledkov <dimitri.ledkov@canonical.com> writes:
>
> > Hi all,
> >
> > I was going through build-depends on linux kernel in Ubuntu and I
> > noticed that whilst most documentation and man-pages are written in
> > Rst format, there are a few that require asciidoc.
> >
> > $ git grep -l asciidoc -- '*Makefile*'
> > tools/kvm/kvm_stat/Makefile
> > tools/lib/perf/Documentation/Makefile
> > tools/perf/Documentation/Makefile
> > tools/perf/Makefile.perf

Fwiw, I'd be in favor of perf not using asciidoc and would be happy to
review patches making the change to rst. Ultimately merging wouldn't
be my decision though :-)

Thanks,
Ian


> Interesting...I was unaware of those...
>
> > Are both Rst and asciidoc preferred in the kernel Documentation? Or
> > should we upgrade kvm_stat & perf manpages from asciidoc to rst2man?
>
> In general we don't have a lot of man pages in the kernel, so it's not
> something we've put a lot of thought into.  Ideally, I suppose, it would
> be nice to get all of those man pages integrated into the RST docs
> build, but it's not something that is likely to inspire any great sense
> of urgency.
>
> Thanks,
>
> jon
>

Re: Converting manpages from asciidoc to rst2man ?

[Theodore Ts'o]

On Mon, Dec 04, 2023 at 07:36:04AM -0700, Jonathan Corbet wrote:
> 
> In general we don't have a lot of man pages in the kernel, so it's not
> something we've put a lot of thought into.  Ideally, I suppose, it would
> be nice to get all of those man pages integrated into the RST docs
> build, but it's not something that is likely to inspire any great sense
> of urgency.

These manpages (at least the perf ones) are actually translated into
nroff/troff's -man macro format using asciidoctor so that things like
"man perf": For example, from Debian testing's "linux-perf" package:

% gunzip < /usr/share/man/man1/perf.1.gz | head
'\" t
.\"     Title: perf
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2023-11-03
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF" "1" "2023-11-03" "perf" "perf Manual"

% dpkg -S /usr/share/man/man1/perf.1.gz
diversion by linux-perf from: /usr/share/man/man1/perf.1.gz
diversion by linux-perf to: /usr/share/man/man1/perf.wrapper.1.gz
linux-perf: /usr/share/man/man1/perf.1.gz

I guess we could try to use rst2man to do the same thing, but it's a
lot more than just "make it look nice" when rendered into HTML and pdf
when processfing the .rst file.  We need to make sure that after the
rst file is turned into a -man text file, that it looks good when
postsprocess via "groff -man -T utf8" *and* "groff -man -T pdf".

It would also mean that python3-docutils would have to be installed
when building kernel docs (to provide the rst2man command), but then
again, it would remove the need to have asciidoctor installed....

Cheers,

					- Ted