perf tools man pages on the web

perf tools man pages on the web

[Adrian Hunter]

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?

Regards
Adrian

Re: perf tools man pages on the web

[Ian Rogers]

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?

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,
Ian

> Regards
> Adrian

Re: perf tools man pages on the web

[Namhyung Kim]

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.  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

Re: perf tools man pages on the web

[Adrian Hunter]

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

>                        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

Re: perf tools man pages on the web

[Ian Rogers]

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?

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
>

Re: perf tools man pages on the web

[Adrian Hunter]

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.

+ 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
>>

Re: perf tools man pages on the web

[Ian Rogers]

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
> >>
>

Re: perf tools man pages on the web

[Adrian Hunter]

On 15/08/22 17:56, Ian Rogers 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?
> 
> 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.

Speaking of the wiki, anyone know how to change the
"Set $wgLogo to the URL path to your own logo image." image?

Re: perf tools man pages on the web

[Ian Rogers]

On Wed, Aug 17, 2022 at 1:55 AM Adrian Hunter <adrian.hunter@intel.com> wrote:
>
> On 15/08/22 17:56, Ian Rogers 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?
> >
> > 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.
>
> Speaking of the wiki, anyone know how to change the
> "Set $wgLogo to the URL path to your own logo image." image?

+1000

Someone at RedHat knows :-)

Ian

Re: perf tools man pages on the web

[Arnaldo Carvalho de Melo]

Em Wed, Aug 17, 2022 at 06:02:25AM -0700, Ian Rogers escreveu:
> On Wed, Aug 17, 2022 at 1:55 AM Adrian Hunter <adrian.hunter@intel.com> wrote:
> > Speaking of the wiki, anyone know how to change the
> > "Set $wgLogo to the URL path to your own logo image." image?
 
> +1000
 
> Someone at RedHat knows :-)

Documentation is at the Media Wiki site, admin up to a point was John Kacur,
John?

https://www.mediawiki.org/wiki/Manual:FAQ#Changing_the_interface>

--------------------- 8< ----------------------------------

How do I change the logo?

The logo that appears in the top left of each page is determined by the $wgLogo configuration line in the LocalSettings.php file.

There are two ways to change the logo:

    Upload a picture to your wiki using the normal file uploading interface. This allows the logo to be replaced easily, so you may want to protect the page if you use this method.

        Then add the $wgLogo line to LocalSettings.php, for example:

        $wgLogo = "{$wgUploadPath}/6/62/mylogo.png";

    Upload an image to your server by other means (such as FTP).

        Add the $wgLogo line to LocalSettings.php, for example:

        $wgLogo = "{$wgScriptPath}/mylogo.jpg";

        (In this example, the image is in the same folder as the LocalSettings.php file.)

If you want to change the logo in only specific pages, override #p-logo
css's background-image property or use third party extension like
Extension:LogoFunctions.  Caution! Caution: 	Do not simply overwrite
the default logo installed with MediaWiki (/resources/assets/wiki.png);
this file will be overwritten when you upgrade.  A good size for a
square logo is 135x135px or 150x150px, but the logo need not be square,
especially if it contains text below an image. The maximum logo size in
Vector is ~160x160px, while MonoBook's is ~155x155px. A logo that is too
large will be cut off.

--------------------- 8< ----------------------------------

- Arnaldo

Re: perf tools man pages on the web

[Ian Rogers]

On Thu, Aug 18, 2022 at 9:24 AM Arnaldo Carvalho de Melo
<arnaldo.melo@gmail.com> wrote:
>
>
>
> On Wed, Aug 17, 2022, 10:21 AM Arnaldo Carvalho de Melo <acme@kernel.org> wrote:
>>
>> Em Wed, Aug 17, 2022 at 06:02:25AM -0700, Ian Rogers escreveu:
>> > On Wed, Aug 17, 2022 at 1:55 AM Adrian Hunter <adrian.hunter@intel.com> wrote:
>> > > Speaking of the wiki, anyone know how to change the
>> > > "Set $wgLogo to the URL path to your own logo image." image?
>>
>> > +1000
>>
>> > Someone at RedHat knows :-)
>>
>> Documentation is at the Media Wiki site, admin up to a point was John Kacur,
>> John?
>>
>> https://www.mediawiki.org/wiki/Manual:FAQ#Changing_the_interface>
>>
>> --------------------- 8< ----------------------------------
>>
>> How do I change the logo?
>>
>> The logo that appears in the top left of each page is determined by the $wgLogo configuration line in the LocalSettings.php file.
>>
>> There are two ways to change the logo:
>>
>>     Upload a picture to your wiki using the normal file uploading interface. This allows the logo to be replaced easily, so you may want to protect the page if you use this method.
>>
>>         Then add the $wgLogo line to LocalSettings.php, for example:
>>
>>         $wgLogo = "{$wgUploadPath}/6/62/mylogo.png";
>>
>>     Upload an image to your server by other means (such as FTP).
>>
>>         Add the $wgLogo line to LocalSettings.php, for example:
>>
>>         $wgLogo = "{$wgScriptPath}/mylogo.jpg";
>>
>>         (In this example, the image is in the same folder as the LocalSettings.php file.)
>>
>> If you want to change the logo in only specific pages, override #p-logo
>> css's background-image property or use third party extension like
>> Extension:LogoFunctions.  Caution! Caution:     Do not simply overwrite
>> the default logo installed with MediaWiki (/resources/assets/wiki.png);
>> this file will be overwritten when you upgrade.  A good size for a
>> square logo is 135x135px or 150x150px, but the logo need not be square,
>> especially if it contains text below an image. The maximum logo size in
>> Vector is ~160x160px, while MonoBook's is ~155x155px. A logo that is too
>> large will be cut off.
>>
>> --------------------- 8< ----------------------------------
>
>
> I got it sorted out with the kernel.org admins.
>
> Please force reload.

You made my day!

Thanks,
Ian

> - Arnaldo

Re: perf tools man pages on the web

[Adrian Hunter]

On 18/08/22 19:24, Arnaldo Carvalho de Melo wrote:
> 
> 
> On Wed, Aug 17, 2022, 10:21 AM Arnaldo Carvalho de Melo <acme@kernel.org <mailto:acme@kernel.org>> wrote:
> 
>     Em Wed, Aug 17, 2022 at 06:02:25AM -0700, Ian Rogers escreveu:
>     > On Wed, Aug 17, 2022 at 1:55 AM Adrian Hunter <adrian.hunter@intel.com <mailto:adrian.hunter@intel.com>> wrote:
>     > > Speaking of the wiki, anyone know how to change the
>     > > "Set $wgLogo to the URL path to your own logo image." image?
> 
>     > +1000
> 
>     > Someone at RedHat knows :-)
> 
>     Documentation is at the Media Wiki site, admin up to a point was John Kacur,
>     John?
> 
>     https://www.mediawiki.org/wiki/Manual:FAQ#Changing_the_interface <https://www.mediawiki.org/wiki/Manual:FAQ#Changing_the_interface>>
> 
>     --------------------- 8< ----------------------------------
> 
>     How do I change the logo?
> 
>     The logo that appears in the top left of each page is determined by the $wgLogo configuration line in the LocalSettings.php file.
> 
>     There are two ways to change the logo:
> 
>         Upload a picture to your wiki using the normal file uploading interface. This allows the logo to be replaced easily, so you may want to protect the page if you use this method.
> 
>             Then add the $wgLogo line to LocalSettings.php, for example:
> 
>             $wgLogo = "{$wgUploadPath}/6/62/mylogo.png";
> 
>         Upload an image to your server by other means (such as FTP).
> 
>             Add the $wgLogo line to LocalSettings.php, for example:
> 
>             $wgLogo = "{$wgScriptPath}/mylogo.jpg";
> 
>             (In this example, the image is in the same folder as the LocalSettings.php file.)
> 
>     If you want to change the logo in only specific pages, override #p-logo
>     css's background-image property or use third party extension like
>     Extension:LogoFunctions.  Caution! Caution:     Do not simply overwrite
>     the default logo installed with MediaWiki (/resources/assets/wiki.png);
>     this file will be overwritten when you upgrade.  A good size for a
>     square logo is 135x135px or 150x150px, but the logo need not be square,
>     especially if it contains text below an image. The maximum logo size in
>     Vector is ~160x160px, while MonoBook's is ~155x155px. A logo that is too
>     large will be cut off.
> 
>     --------------------- 8< ----------------------------------
> 
> 
> I got it sorted out with the kernel.org <http://kernel.org> admins.
> 
> Please force reload.

Is it just me or has it disappeared again?