[PATCH 0/2] winsup/doc/: add proc(5) man page

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

[PATCH 0/2] winsup/doc/: add proc(5) man page

Brian Inglis
Hacked a Cygwin proc.5 man page, by combing through fhandler_proc...,
converted to proc-5.xml using doclifter, included after pathnames-proc
before pathnames-proc-registry sections in specialnames.xml, and
modified to match and create a refentry to generate proc(5) man page.

One of the issues with the xml input is that formatting wide screen
displays as if at .in 0 appears to be impossible, or at least not in
evidence in any of the other inputs or outputs, which don't include such
heavily indented lists of lists, and ending and restarting heavy
indenting context appears ugly.

Brian Inglis (2):
  specialnames.xml: add proc(5) Cygwin man page
  winsup/doc/Makefile.in: create man5 dir and install generated proc.5

 winsup/doc/Makefile.in      |    4 +
 winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
 2 files changed, 2104 insertions(+)

--
2.29.2

Reply | Threaded
Open this post in threaded view
|

[PATCH 1/2] specialnames.xml: add proc(5) Cygwin man page

Brian Inglis
---
 winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
 1 file changed, 2100 insertions(+)


0001-specialnames.xml-add-proc-5-Cygwin-man-page.patch (68K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

[PATCH 2/2] winsup/doc/Makefile.in: create man5 dir and install proc.5

Brian Inglis
In reply to this post by Brian Inglis
---
 winsup/doc/Makefile.in | 4 ++++
 1 file changed, 4 insertions(+)


0002-winsup-doc-Makefile.in-create-man5-dir-and-install-g.patch (893 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH 0/2] winsup/doc/: add proc(5) man page

Corinna Vinschen-2
In reply to this post by Brian Inglis
On Nov 23 15:10, Brian Inglis wrote:

> Hacked a Cygwin proc.5 man page, by combing through fhandler_proc...,
> converted to proc-5.xml using doclifter, included after pathnames-proc
> before pathnames-proc-registry sections in specialnames.xml, and
> modified to match and create a refentry to generate proc(5) man page.
>
> One of the issues with the xml input is that formatting wide screen
> displays as if at .in 0 appears to be impossible, or at least not in
> evidence in any of the other inputs or outputs, which don't include such
> heavily indented lists of lists, and ending and restarting heavy
> indenting context appears ugly.
>
> Brian Inglis (2):
>   specialnames.xml: add proc(5) Cygwin man page
>   winsup/doc/Makefile.in: create man5 dir and install generated proc.5
>
>  winsup/doc/Makefile.in      |    4 +
>  winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
>  2 files changed, 2104 insertions(+)
>
> --
> 2.29.2

LGTM.  Jon, can you take a look, too, please?


Thanks,
Corinna
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH 1/2] specialnames.xml: add proc(5) Cygwin man page

Jon TURNEY
In reply to this post by Brian Inglis
On 23/11/2020 22:11, Brian Inglis wrote:
> ---
>   winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
>   1 file changed, 2100 insertions(+)

I'm not sure how you generated this email.  But sending the patch inline
(using 'git-send-email'?), rather than as an attachment makes it a lot
easier to make review comments inline.

A few lines have trailing whitespace, which should be removed.

> diff --git a/winsup/doc/specialnames.xml b/winsup/doc/specialnames.xml
> index a1f7401e16b9..6b86187f39e9 100644
> --- a/winsup/doc/specialnames.xml
> +++ b/winsup/doc/specialnames.xml
> @@ -486,6 +486,2106 @@ one in Linux, but it provides significant capabilities. The
>  <systemitem>procps</systemitem> package contains several utilities
>  that use it.
>  </para>
> +  <refentry id="proc">
> +    <!-- from Linux manpages project proc(5)

Should this say 'based on', to make it clear this isn't a literal copy
of that?

> +
> +    <refentryinfo><date>2020-11-11</date></refentryinfo>
> +    <refmeta>
> +      <refentrytitle>proc</refentrytitle>
> +      <manvolnum>5</manvolnum>
> +      <refmiscinfo class='date'>2020-11-11</refmiscinfo>
> +      <refmiscinfo class='source'>Cygwin</refmiscinfo>
> +      <refmiscinfo class='manual'>Cygwin User's Manual</refmiscinfo>
> +    </refmeta>

I think the <date>s here should be omitted (rather than hoping someone
remembers to update them when the relevant content is updated), which
causes the build date to be used.

> +  <varlistentry>
> +    <term><filename>/proc/loadavg</filename></term>
> +    <listitem>
> +      <para>
> +        The first three fields in this file are load average figures
> +        giving the number of jobs in the run queue (state R) or waiting
> +        for disk I/O (state D) averaged over 1, 5, and 15 minutes.
> + They are the same as the load average numbers given by

As mentioned by Corinna previously, we don't know the 'D' state, so the
loadavg is just computed from the run queue length.

> +  <varlistentry>
> +    <term><filename>/proc/registry</filename></term>
> +    <listitem>
> +      <para>
> +        Under Windows, this directory contains subdirectories for
> +        registry paths, keys, and subkeys, and files named for registry
> +        values which contain registry data, for the current process.
> +      </para>
> +

'Under Windows' seems redundant :)

> +  <varlistentry>
> +    <term><filename>/proc/version</filename></term>
> +    <listitem>
> +      <para>
> +        This string identifies the kernel version that is currently

Kernel?

> + <para>
> +  Many files contain strings (e.g., the environment and command
> +  line) that are in the internal format, with subfields terminated
> +  by null bytes (&apos;&bsol;0&apos;).
> +  When inspecting such files, you may find that the results are
> +  more readable if you use a command of the following form to
> +  display them:
> +
> +  <screen>
> +    <prompt>$</prompt> <userinput>cat -A <emphasis remap='I'>file</emphasis></userinput>
> +  </screen>
> + </para>
> +
> + <para>
> +  This manual page is incomplete, possibly inaccurate, and is the kind
> +  of thing that needs to be updated very often.
> + </para>

The above should be in a section 'BUGS' ?

> +
> +    <refsect1 id='proc-colophon'><title>Colophon</title>
> +      <para>
> + This page is part of the <emphasis remap='I'>Cygwin</emphasis> project.

I'm guessing these 'remap' attributes are doclifter detritus and can be
discarded.

> + A description of the project, information about reporting bugs, and the
> + latest documentation, can be found on
> + <ulink
> + url="https://cygwin.com/docs.html">the Cygwin project web pages</ulink>.
> +      </para>
> +    </refsect1>

It would be nice to include this colophon on all our manpages, but that
probably requires more effort.

Nice work.

There also seem to be some docbook processing quirks which could bear
further investigation:

The copyright section from legal.xml doesn't seem to make it into the
proc.5 manpage, unlike all the others.

The proc.5 section appears as a manpage, and in the pdf output, but not
in the html output.
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH 1/2] specialnames.xml: add proc(5) Cygwin man page

Brian Inglis
On 2020-11-24 07:48, Jon Turney wrote:
> On 23/11/2020 22:11, Brian Inglis wrote:
>> ---
>>   winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
>>   1 file changed, 2100 insertions(+)
>
> I'm not sure how you generated this email.  But sending the patch inline (using
> 'git-send-email'?), rather than as an attachment makes it a lot easier to make
> review comments inline.

It's right from git send-email which creates the MIME sections in the patches:

"
...
  X-Mailer: git-send-email 2.29.2
...
  This is a multi-part message in MIME format.
  --------------2.29.2
  Content-Type: text/plain; charset=UTF-8; format=fixed
  Content-Transfer-Encoding: 8bit

  ---
  winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
  1 file changed, 2100 insertions(+)

  --------------2.29.2
  Content-Type: text/x-patch; name="0001-specialnames.xml-add-proc-5-Cygwin-man-
page.patch"
  Content-Transfer-Encoding: 8bit
  Content-Disposition: attachment;
filename="0001-specialnames.xml-add-proc-5-Cygwin-man-page.patch"
..."

so it may be down to how your MUA displays those, and we are running the same
release of TB, which on mine shows the patch "inline" after a filename separator
like any other text attachment.
Ctrl-U displays email source including headers; search for 'User-Agent:' or
'Mailer:' in headers.

> A few lines have trailing whitespace, which should be removed.

Not in the patched lines, which appear in *RED* in git diff, and I just
rechecked that they are in context lines, so I left them alone for separate
cleanup, as I have been chastised on previous occasions. ;^>

>> diff --git a/winsup/doc/specialnames.xml b/winsup/doc/specialnames.xml
>> index a1f7401e16b9..6b86187f39e9 100644
>> --- a/winsup/doc/specialnames.xml
>> +++ b/winsup/doc/specialnames.xml
>> @@ -486,6 +486,2106 @@ one in Linux, but it provides significant capabilities.
>> The
>>  <systemitem>procps</systemitem> package contains several utilities
>>  that use it.
>>  </para>
>> +  <refentry id="proc">
>> +    <!-- from Linux manpages project proc(5)
>
> Should this say 'based on', to make it clear this isn't a literal copy of that?

K

>> +
>> +    <refentryinfo><date>2020-11-11</date></refentryinfo>
>> +    <refmeta>
>> +      <refentrytitle>proc</refentrytitle>
>> +      <manvolnum>5</manvolnum>
>> +      <refmiscinfo class='date'>2020-11-11</refmiscinfo>
>> +      <refmiscinfo class='source'>Cygwin</refmiscinfo>
>> +      <refmiscinfo class='manual'>Cygwin User's Manual</refmiscinfo>
>> +    </refmeta>
>
> I think the <date>s here should be omitted (rather than hoping someone remembers
> to update them when the relevant content is updated), which causes the build
> date to be used.

That's the point - showing how current the information is, not when it was last
built.

>> +      <varlistentry>
>> +        <term><filename>/proc/loadavg</filename></term>
>> +        <listitem>
>> +          <para>
>> +            The first three fields in this file are load average figures
>> +            giving the number of jobs in the run queue (state R) or waiting
>> +            for disk I/O (state D) averaged over 1, 5, and 15 minutes.
>> +        They are the same as the load average numbers given by
>
> As mentioned by Corinna previously, we don't know the 'D' state, so the loadavg
> is just computed from the run queue length.

Code dispatches on 'D' state so I thought that statement was mistaken: will remove.

>> +      <varlistentry>
>> +        <term><filename>/proc/registry</filename></term>
>> +        <listitem>
>> +          <para>
>> +            Under Windows, this directory contains subdirectories for
>> +            registry paths, keys, and subkeys, and files named for registry
>> +            values which contain registry data, for the current process.
>> +          </para>
>> +
>
> 'Under Windows' seems redundant :)

Will change to 'Cygwin' as the intent is to clarify this is a custom variation,
not to be expected on Linux or Unix variations.

>> +      <varlistentry>
>> +        <term><filename>/proc/version</filename></term>
>> +        <listitem>
>> +          <para>
>> +            This string identifies the kernel version that is currently
>
> Kernel?

Missed another edit to 'Cygwin'.

>> +    <para>
>> +      Many files contain strings (e.g., the environment and command
>> +      line) that are in the internal format, with subfields terminated
>> +      by null bytes (&apos;&bsol;0&apos;).
>> +      When inspecting such files, you may find that the results are
>> +      more readable if you use a command of the following form to
>> +      display them:
>> +
>> +      <screen>
>> +        <prompt>$</prompt> <userinput>cat -A <emphasis
>> remap='I'>file</emphasis></userinput>
>> +      </screen>
>> +    </para>
>> +
>> +    <para>
>> +      This manual page is incomplete, possibly inaccurate, and is the kind
>> +      of thing that needs to be updated very often.
>> +    </para>
>
> The above should be in a section 'BUGS' ?

It looks like .SH Notes and Copyright have been docliftered, edited into, or
generated in the wrong place: I didn't notice that and will check the ins and outs.
In my proc.5 collection, these comments are mainly under .SH Notes except RH
uses Caveats, not really appropriate for free/libre/open systems, but Bugs might
be.

>> +
>> +    <refsect1 id='proc-colophon'><title>Colophon</title>
>> +      <para>
>> +    This page is part of the <emphasis remap='I'>Cygwin</emphasis> project.
>
> I'm guessing these 'remap' attributes are doclifter detritus and can be discarded.

I was hoping as they are in Docbook that they were rendering hints that would
maintain the original format. So can I safely eliminate them?

>> +    A description of the project, information about reporting bugs, and the
>> +    latest documentation, can be found on
>> +    <ulink
>> +    url="https://cygwin.com/docs.html">the Cygwin project web pages</ulink>.
>> +      </para>
>> +    </refsect1>
>
> It would be nice to include this colophon on all our manpages, but that probably
> requires more effort.

Perhaps in other patches including trailing space cleanups?

> Nice work.
>
> There also seem to be some docbook processing quirks which could bear further
> investigation:

A lot that seem to result from the purely declarative syntax of the tags, that
are not easy to ameliorate: I've dug, delved, tried and backed out changes and
extra .xsl rules for some renderings.

> The copyright section from legal.xml doesn't seem to make it into the proc.5
> manpage, unlike all the others.

I only checked specialnames not the utility manpages as the content is so
different, so I will check there to see how that works.

> The proc.5 section appears as a manpage, and in the pdf output, but not in the
> html output.

I'll see what differs between the HTML and PDF rendering, and the UG utility
HTML manpages, but suspect content and paper dependent LaTeX and/or TeX
intermediates for PDFs may be one difference.
[I prefer declarative epub xhtml+xml formats that are not pre-rendered onto
A4/Letter substrates and that obey my CSS preferences on each of my devices.]

--
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in binary units and prefixes, physical quantities in SI.]
Reply | Threaded
Open this post in threaded view
|

Re: proc(5) Cygwin man page

Brian Inglis
On 2020-11-24 14:03, Brian Inglis wrote:

> On 2020-11-24 07:48, Jon Turney wrote:
>> On 23/11/2020 22:11, Brian Inglis wrote:
>>> ---
>>>   winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
>>>   1 file changed, 2100 insertions(+)
>>
>> I'm not sure how you generated this email.  But sending the patch inline
>> (using 'git-send-email'?), rather than as an attachment makes it a lot easier
>> to make review comments inline.
>
> It's right from git send-email which creates the MIME sections in the patches:
>
> "
> ...
>   X-Mailer: git-send-email 2.29.2
> ...
>   This is a multi-part message in MIME format.
>   --------------2.29.2
>   Content-Type: text/plain; charset=UTF-8; format=fixed
>   Content-Transfer-Encoding: 8bit
>
>   ---
>   winsup/doc/specialnames.xml | 2100 +++++++++++++++++++++++++++++++++++
>   1 file changed, 2100 insertions(+)
>
>   --------------2.29.2
>   Content-Type: text/x-patch; name="0001-specialnames.xml-add-proc-5-Cygwin-man-
> page.patch"
>   Content-Transfer-Encoding: 8bit
>   Content-Disposition: attachment;
> filename="0001-specialnames.xml-add-proc-5-Cygwin-man-page.patch"
> ..."
>
> so it may be down to how your MUA displays those, and we are running the same
> release of TB, which on mine shows the patch "inline" after a filename separator
> like any other text attachment.
> Ctrl-U displays email source including headers; search for 'User-Agent:' or
> 'Mailer:' in headers.
>
>> A few lines have trailing whitespace, which should be removed.
>
> Not in the patched lines, which appear in *RED* in git diff, and I just
> rechecked that they are in context lines, so I left them alone for separate
> cleanup, as I have been chastised on previous occasions. ;^>
>
>>> diff --git a/winsup/doc/specialnames.xml b/winsup/doc/specialnames.xml
>>> index a1f7401e16b9..6b86187f39e9 100644
>>> --- a/winsup/doc/specialnames.xml
>>> +++ b/winsup/doc/specialnames.xml
>>> @@ -486,6 +486,2106 @@ one in Linux, but it provides significant
>>> capabilities. The
>>>  <systemitem>procps</systemitem> package contains several utilities
>>>  that use it.
>>>  </para>
>>> +  <refentry id="proc">
>>> +    <!-- from Linux manpages project proc(5)
>>
>> Should this say 'based on', to make it clear this isn't a literal copy of that?
>
> K
>
>>> +
>>> +    <refentryinfo><date>2020-11-11</date></refentryinfo>
>>> +    <refmeta>
>>> +      <refentrytitle>proc</refentrytitle>
>>> +      <manvolnum>5</manvolnum>
>>> +      <refmiscinfo class='date'>2020-11-11</refmiscinfo>
>>> +      <refmiscinfo class='source'>Cygwin</refmiscinfo>
>>> +      <refmiscinfo class='manual'>Cygwin User's Manual</refmiscinfo>
>>> +    </refmeta>
>>
>> I think the <date>s here should be omitted (rather than hoping someone
>> remembers to update them when the relevant content is updated), which causes
>> the build date to be used.
>
> That's the point - showing how current the information is, not when it was last
> built.
>
>>> +      <varlistentry>
>>> +        <term><filename>/proc/loadavg</filename></term>
>>> +        <listitem>
>>> +          <para>
>>> +            The first three fields in this file are load average figures
>>> +            giving the number of jobs in the run queue (state R) or waiting
>>> +            for disk I/O (state D) averaged over 1, 5, and 15 minutes.
>>> +        They are the same as the load average numbers given by
>>
>> As mentioned by Corinna previously, we don't know the 'D' state, so the
>> loadavg is just computed from the run queue length.
>
> Code dispatches on 'D' state so I thought that statement was mistaken: will remove.
>
>>> +      <varlistentry>
>>> +        <term><filename>/proc/registry</filename></term>
>>> +        <listitem>
>>> +          <para>
>>> +            Under Windows, this directory contains subdirectories for
>>> +            registry paths, keys, and subkeys, and files named for registry
>>> +            values which contain registry data, for the current process.
>>> +          </para>
>>> +
>>
>> 'Under Windows' seems redundant :)
>
> Will change to 'Cygwin' as the intent is to clarify this is a custom variation,
> not to be expected on Linux or Unix variations.
>
>>> +      <varlistentry>
>>> +        <term><filename>/proc/version</filename></term>
>>> +        <listitem>
>>> +          <para>
>>> +            This string identifies the kernel version that is currently
>>
>> Kernel?
>
> Missed another edit to 'Cygwin'.
>
>>> +    <para>
>>> +      Many files contain strings (e.g., the environment and command
>>> +      line) that are in the internal format, with subfields terminated
>>> +      by null bytes (&apos;&bsol;0&apos;).
>>> +      When inspecting such files, you may find that the results are
>>> +      more readable if you use a command of the following form to
>>> +      display them:
>>> +
>>> +      <screen>
>>> +        <prompt>$</prompt> <userinput>cat -A <emphasis
>>> remap='I'>file</emphasis></userinput>
>>> +      </screen>
>>> +    </para>
>>> +
>>> +    <para>
>>> +      This manual page is incomplete, possibly inaccurate, and is the kind
>>> +      of thing that needs to be updated very often.
>>> +    </para>
>>
>> The above should be in a section 'BUGS' ?
>
> It looks like .SH Notes and Copyright have been docliftered, edited into, or
> generated in the wrong place: I didn't notice that and will check the ins and outs.
> In my proc.5 collection, these comments are mainly under .SH Notes except RH
> uses Caveats, not really appropriate for free/libre/open systems, but Bugs might
> be.
>
>>> +
>>> +    <refsect1 id='proc-colophon'><title>Colophon</title>
>>> +      <para>
>>> +    This page is part of the <emphasis remap='I'>Cygwin</emphasis> project.
>>
>> I'm guessing these 'remap' attributes are doclifter detritus and can be
>> discarded.
>
> I was hoping as they are in Docbook that they were rendering hints that would
> maintain the original format. So can I safely eliminate them?
>
>>> +    A description of the project, information about reporting bugs, and the
>>> +    latest documentation, can be found on
>>> +    <ulink
>>> +    url="https://cygwin.com/docs.html">the Cygwin project web pages</ulink>.
>>> +      </para>
>>> +    </refsect1>
>>
>> It would be nice to include this colophon on all our manpages, but that
>> probably requires more effort.
>
> Perhaps in other patches including trailing space cleanups?
>
>> Nice work.
>>
>> There also seem to be some docbook processing quirks which could bear further
>> investigation:
>
> A lot that seem to result from the purely declarative syntax of the tags, that
> are not easy to ameliorate: I've dug, delved, tried and backed out changes and
> extra .xsl rules for some renderings.
>
>> The copyright section from legal.xml doesn't seem to make it into the proc.5
>> manpage, unlike all the others.
>
> I only checked specialnames not the utility manpages as the content is so
> different, so I will check there to see how that works.
>
>> The proc.5 section appears as a manpage, and in the pdf output, but not in the
>> html output.
>
> I'll see what differs between the HTML and PDF rendering, and the UG utility
> HTML manpages, but suspect content and paper dependent LaTeX and/or TeX
> intermediates for PDFs may be one difference.
> [I prefer declarative epub xhtml+xml formats that are not pre-rendered onto
> A4/Letter substrates and that obey my CSS preferences on each of my devices.]
Colophon with embedded <ulink... truncated Copyright section to only the
heading, and included link endnote appeared as final Notes section, so removed
Colophon section and Copyright section appears complete.

Have not yet removed remap hints as unsure if they are used or useful.

Attached rendered outputs FYI.

Will regenerate and email patches.

--
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in binary units and prefixes, physical quantities in SI.]


specialnames.tar.xz (2M) Download Attachment