[PATCH 0/3] Small documentation fixes

[PATCH 0/3] Small documentation fixes

[Jon Turney]

Jon Turney (3):
  Use <example> tag at same level as <para>, not inside it
  Use <filename> tag, not <pathname> tag
  Improve description of Cygwin ldd utility

 winsup/doc/utils.xml | 43 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 32 insertions(+), 11 deletions(-)

-- 
2.8.3

[PATCH 2/3] Use <filename> tag, not <pathname> tag

[Jon Turney]

Fix an instance of the invalid <pathname> tag in Cygwin utils documentation,
by using the valid <filename> tag instead.

Signed-off-by: Jon Turney <jon.turney@dronecode.org.uk>
---
 winsup/doc/utils.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml
index 4853d92..12949c5 100644
--- a/winsup/doc/utils.xml
+++ b/winsup/doc/utils.xml
@@ -335,7 +335,7 @@ Other options:
     However, the cygdrive prefix can be changed by the user, so symbolic links
     created using the cygdrive prefix are not foolproof.  With
     <literal>-U</literal> cygpath will generate such paths prepended by the
-    virtual <pathname>/proc/cygdrive</pathname> symbolic link, which will
+    virtual <filename>/proc/cygdrive</filename> symbolic link, which will
     never change, so the created path is safe against changing the cygdrive
     prefix.</para>
 
-- 
2.8.3

[PATCH 3/3] Improve description of Cygwin ldd utility

[Jon Turney]

Improve the description of Cygwin ldd utility to give a bit more detail
about how it does what it does

Also add a security warning (modelled after the one in the Linux manpage)
that it may end up executing the file it is applied to.

Signed-off-by: Jon Turney <jon.turney@dronecode.org.uk>
---
 winsup/doc/utils.xml | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml
index 12949c5..906c377 100644
--- a/winsup/doc/utils.xml
+++ b/winsup/doc/utils.xml
@@ -755,10 +755,20 @@ ldd [OPTION]... FILE...
 
     <refsect1>
       <title>Description</title>
-    <para><command>ldd</command> prints the shared libraries (DLLs) an
-      executable or DLL is linked against. No modifying option is implemented
-      yet.</para>
+      <para><command>ldd</command> prints the shared libraries (DLLs) loaded
+      when running an executable or DLL.</para>
+
+    <refsect2>
+      <title>Security</title>
+      <para>
+	<command>ldd</command> invokes the Windows loader on the file specified,
+	then uses the Windows debugging interface to report DLLs loaded, and
+	(for executables) to attempt to stop execution before the entrypoint.
+	Thus, you should never use ldd on an untrusted file.
+      </para>
+    </refsect2>
     </refsect1>
+
   </refentry>
 
   <refentry id="locale">
-- 
2.8.3

[PATCH 1/3] Use <example> tag at same level as <para>, not inside it

[Jon Turney]

In Cygwin utils documentation, use the <example> tag at same level as
<para>, not inside it.

This improves the generated manpages.

Signed-off-by: Jon Turney <jon.turney@dronecode.org.uk>
---
 winsup/doc/utils.xml | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml
index 08a24f7..4853d92 100644
--- a/winsup/doc/utils.xml
+++ b/winsup/doc/utils.xml
@@ -102,7 +102,10 @@ Note: -c, -f, and -l only report on packages that are currently installed. To
     <para> The <literal>-f</literal> option helps you to track down which
       package a file came from, and <literal>-l</literal> lists all files in a
       package. For example, to find out about
-      <filename>/usr/bin/less</filename> and its package: <example
+      <filename>/usr/bin/less</filename> and its package:
+    </para>
+
+    <example
       id="utils-cygcheck-ex"><title>Example <command>cygcheck</command>
       usage</title>
       <screen>
@@ -116,7 +119,7 @@ $ cygcheck -l less
 /usr/man/man1/less.1
 /usr/man/man1/lesskey.1
 </screen>
-      </example> </para>
+      </example>
 
     <para>The <literal>-h</literal> option prints additional helpful messages
       in the report, at the beginning of each section. It also adds table
@@ -150,7 +153,9 @@ $ cygcheck -l less
 
     <para>For example, perhaps you are getting an error because you are missing
       a certain DLL and you want to know which package includes that file:
-      <example id="utils-search-ex"><title>Searching all packages for a
+    </para>
+
+    <example id="utils-search-ex"><title>Searching all packages for a
       file</title>
       <screen>
 $ cygcheck -p 'cygintl-2\.dll'
@@ -170,7 +175,7 @@ Found 2 matches for '/ls\.exe'.
 coreutils-5.2.1-5         GNU core utilities (includes fileutils, sh-utils and textutils)
 coreutils-5.3.0-6         GNU core utilities (includes fileutils, sh-utils and textutils)
 </screen>
-      </example> </para>
+      </example>
 
     <para>Note that this option takes a regular expression, not a glob or
       wildcard. This means that you need to use <literal>.*</literal> if you
@@ -1168,19 +1173,25 @@ on domain controllers and domain member machines.
       multiple domains) where the UIDs might match otherwise. The
       <literal>-p</literal> option causes <command>mkpasswd</command> to use
       the specified prefix instead of the account home dir or <literal>/home/
-      </literal>. For example, this command: <example id="utils-althome-ex"
+      </literal>. For example, this command:
+    </para>
+
+    <example id="utils-althome-ex"
       ><title>Using an alternate home root</title>
       <screen>
 <prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" &gt; /etc/passwd</userinput>
 </screen>
-      </example> would put local users' home directories in the Windows
+    </example>
+
+    <para>
+      would put local users' home directories in the Windows
       'Profiles' directory. The <literal>-u</literal> option creates just an
       entry for the specified user. The <literal>-U</literal> option allows you
       to enumerate the standard UNIX users on a Samba machine. It's used
       together with <literal>-l samba-server</literal> or <literal>-L
       samba-server</literal>. The normal UNIX users are usually not enumerated,
       but they can show up as file owners in <command>ls -l</command> output.
-      </para>
+    </para>
     </refsect1>
   </refentry>
 
-- 
2.8.3

Re: [PATCH 0/3] Small documentation fixes

[Corinna Vinschen]

[-- Attachment #1: Type: text/plain, Size: 541 bytes --]

On Jul  5 11:07, Jon Turney wrote:
> Jon Turney (3):
>   Use <example> tag at same level as <para>, not inside it
>   Use <filename> tag, not <pathname> tag
>   Improve description of Cygwin ldd utility
> 
>  winsup/doc/utils.xml | 43 ++++++++++++++++++++++++++++++++-----------
>  1 file changed, 32 insertions(+), 11 deletions(-)

Looks good, please apply.


Thanks,
Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]