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

Brian Inglis Brian.Inglis@SystematicSw.ab.ca
Tue Nov 24 21:03:41 GMT 2020

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.
  Content-Type: text/plain; charset=UTF-8; format=fixed
  Content-Transfer-Encoding: 8bit

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

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

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?


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

>> +      <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 ('\0').
>> +      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 

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

More information about the Cygwin-patches mailing list