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

Jon Turney jon.turney@dronecode.org.uk
Tue Nov 24 14:48:43 GMT 2020


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 ('\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' ?

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


More information about the Cygwin-patches mailing list