Re: perf tools man pages on the web

[Ian Rogers <irogers@google.com>]

On Tue, Aug 16, 2022 at 10:24 PM Adrian Hunter <adrian.hunter@intel.com> wrote:
>
> On 16/08/22 16:25, Ian Rogers wrote:
> > On Mon, Aug 15, 2022 at 11:05 PM Adrian Hunter <adrian.hunter@intel.com> wrote:
> >>
> >> On 16/08/22 08:07, Namhyung Kim wrote:
> >>> Hi Ian and Adrian,
> >>>
> >>> On Mon, Aug 15, 2022 at 7:56 AM Ian Rogers <irogers@google.com> wrote:
> >>>>
> >>>> On Mon, Aug 15, 2022 at 5:05 AM Adrian Hunter <adrian.hunter@intel.com> wrote:
> >>>>>
> >>>>> Hi
> >>>>>
> >>>>> I notice man pages on man7.org e.g.
> >>>>>
> >>>>>         https://www.man7.org/linux/man-pages/man1/perf.1.html
> >>>>>
> >>>>> do not get updated every release, and I wondered if the perf tools
> >>>>> man pages should also be under:
> >>>>>
> >>>>>         https://docs.kernel.org/tools/index.html
> >>>>>
> >>>>> Thoughts?
> >>>>
> >>>> Sounds good to me. I'm assuming it would be some kind of build step
> >>>> that would take the man pages and add them to what linux-doc needs?
> >>>
> >>> I guess it's the RST format.  I'm not sure if there's a converter
> >>> from asciidoc to RST.
> >>
> >> Could use the html files that are already generated by:
> >>
> >>         make -C perf/tools html
> >
> > A lot of the man page makefile code comes from git and wasn't in great
> > shape the last I looked [1]. I believe that would be true for the HTML
> > output. As there are existing dependencies on rst2man for BPF [2], I
> > think it'd be cleaner to migrate all the man pages to rst format with
> > new man page build rules using rst2man. Wdyt?
>
> That seems like a larger job.  For now, I am just suggesting copying the
> html files onto kernel.org.

So I'm not sure the HTML is in any kind of shape. The build rules and
configuration files are remnants of what git had many many years ago.
I did a quick experiment going via docbook (which we do currently in
the man page generation) and using pandoc to write out rst:

$ cd tools/perf/Documentation
$ asciidoc -o - -b docbook -d manpage -f asciidoc.conf perf.txt|pandoc
-f docbook -t rst > perf.rst
$ man2rst perf.rst perf.man
$ man ./perf.man

and got something functional but with these warnings:

perf.rst:7: (ERROR/3) Unexpected indentation.
perf.rst:11: (WARNING/2) malformed hyperlink target.
perf.rst:66: (WARNING/2) malformed hyperlink target.
perf.rst:76: (WARNING/2) malformed hyperlink target.

So we might be able to convert somewhat automatically but have to fix
up hyperlinks.

Thanks,
Ian

> + Mauro
>
> Mauro, do you know if that is feasible?
>
> >
> > Thanks,
> > Ian
> >
> > [1] https://lore.kernel.org/all/20210715013343.2286699-1-irogers@google.com/
> > [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/include/uapi/linux/bpf.h#n1538
> >
> >>>                        Anyway having the perf man pages in the
> >>> tools section looks good.
> >>>
> >>>>
> >>>> Fwiw, there has been some effort to try to improve the wiki:
> >>>> https://perf.wiki.kernel.org/index.php/Main_Page
> >>>> For example, the useful links are now broken apart and have more
> >>>> links, there is a work-in-progress glossary. Perhaps there can be some
> >>>> guidance on what to capture and where.
> >>>
> >>> Thanks for working on this.  I really need to take a look...
> >>>
> >>> Thanks,
> >>> Namhyung
> >>
>