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 ('\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
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.]
