[PATCH v2 0/2] proc(5) man page

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

[PATCH v2 0/2] proc(5) man page

Brian Inglis
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 | 2094 +++++++++++++++++++++++++++++++++++
 2 files changed, 2098 insertions(+)

--
2.29.2

Reply | Threaded
Open this post in threaded view
|

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

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


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

[PATCH v2 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 v2 0/2] proc(5) man page

Corinna Vinschen-2
In reply to this post by Brian Inglis
Hi Brian,

On Nov 24 23:49, Brian Inglis wrote:

> 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 | 2094 +++++++++++++++++++++++++++++++++++
>  2 files changed, 2098 insertions(+)
>
> --
> 2.29.2

It would be helpful if you could outline the changes from v1.


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

Re: [PATCH v2 0/2] proc(5) man page

Brian Inglis
On 2020-11-30 03:47, Corinna Vinschen wrote:
> On Nov 24 23:49, Brian Inglis wrote:
>> 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 | 2094 +++++++++++++++++++++++++++++++++++
>>   2 files changed, 2098 insertions(+)

> It would be helpful if you could outline the changes from v1.

Those were fairly minor fixes to content and some processing outlined in the
(lengthy) responses to Jon's (lengthy) comments under:
https://sourceware.org/pipermail/cygwin-patches/2020q4/010829.html

and I have copied them below, so please clarify if the below is not what you want?

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

 >> 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.]
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH v2 0/2] proc(5) man page

Corinna Vinschen-2
On Nov 30 17:57, Brian Inglis wrote:

> On 2020-11-30 03:47, Corinna Vinschen wrote:
> > On Nov 24 23:49, Brian Inglis wrote:
> > > 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 | 2094 +++++++++++++++++++++++++++++++++++
> > >   2 files changed, 2098 insertions(+)
>
> > It would be helpful if you could outline the changes from v1.
>
> Those were fairly minor fixes to content and some processing outlined in the
> (lengthy) responses to Jon's (lengthy) comments under:
> https://sourceware.org/pipermail/cygwin-patches/2020q4/010829.html
>
> and I have copied them below, so please clarify if the below is not what you want?

I was after a short list with bullet points, ratehr than copying
an email I have in my inbox anyway :}

Jon, can you please take another look, too?


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

Re: [PATCH v2 0/2] proc(5) man page

Brian Inglis
On 2020-12-01 02:55, Corinna Vinschen wrote:

> On Nov 30 17:57, Brian Inglis wrote:
>> On 2020-11-30 03:47, Corinna Vinschen wrote:
>>> On Nov 24 23:49, Brian Inglis wrote:
>>>> 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 | 2094 +++++++++++++++++++++++++++++++++++
>>>>    2 files changed, 2098 insertions(+)
>>
>>> It would be helpful if you could outline the changes from v1.
>>
>> Those were fairly minor fixes to content and some processing outlined in the
>> (lengthy) responses to Jon's (lengthy) comments under:
>> https://sourceware.org/pipermail/cygwin-patches/2020q4/010829.html
>>
>> and I have copied them below, so please clarify if the below is not what you want?
>
> I was after a short list with bullet points, ratehr than copying
> an email I have in my inbox anyway :}
>
> Jon, can you please take another look, too?

* patches are sent directly from git send-email
* trailing whitespace only in Makefile.in context lines so left as is
* comment changed to "based on" Linux manpages project proc(5)
* dates retained to show how current content is, rather than when last built
* /proc/loadavg 'D' state mention removed
* /proc/registry Windows changed to Cygwin to clarify this variation
* /proc/version kernel changed to Cygwin
* Notes subsection missing title and Copyright subsection not included in
standalone man page due to Colophon subsection messing up man rendering
* removed Colophon subsection and Notes reappears properly and Copyright is
included; other system show these under Notes except RH uses Caveats
* retain remap attributes as Docbook rendering hints

--
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: [PATCH v2 0/2] proc(5) man page

cygwin-patches mailing list
On Dec  1 09:49, Brian Inglis wrote:

> On 2020-12-01 02:55, Corinna Vinschen wrote:
> > On Nov 30 17:57, Brian Inglis wrote:
> > > On 2020-11-30 03:47, Corinna Vinschen wrote:
> > > > On Nov 24 23:49, Brian Inglis wrote:
> > > > > 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 | 2094 +++++++++++++++++++++++++++++++++++
> > > > >    2 files changed, 2098 insertions(+)
> > >
> > > > It would be helpful if you could outline the changes from v1.
> > >
> > > Those were fairly minor fixes to content and some processing outlined in the
> > > (lengthy) responses to Jon's (lengthy) comments under:
> > > https://sourceware.org/pipermail/cygwin-patches/2020q4/010829.html
> > >
> > > and I have copied them below, so please clarify if the below is not what you want?
> >
> > I was after a short list with bullet points, ratehr than copying
> > an email I have in my inbox anyway :}
> >
> > Jon, can you please take another look, too?
>
> * patches are sent directly from git send-email
> * trailing whitespace only in Makefile.in context lines so left as is
> * comment changed to "based on" Linux manpages project proc(5)
> * dates retained to show how current content is, rather than when last built
> * /proc/loadavg 'D' state mention removed
> * /proc/registry Windows changed to Cygwin to clarify this variation
> * /proc/version kernel changed to Cygwin
> * Notes subsection missing title and Copyright subsection not included in
> standalone man page due to Colophon subsection messing up man rendering
> * removed Colophon subsection and Notes reappears properly and Copyright is
> included; other system show these under Notes except RH uses Caveats
> * retain remap attributes as Docbook rendering hints
>
> --
> 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.]

Thanks, pushed.


Corinna