[PATCH 5/5] winsup/doc: Update ancient README about building documentation

[PATCH 5/5] winsup/doc: Update ancient README about building documentation

[Jon TURNEY]

Update list of pre-requisites, everything else is obsolete.

Future work: Ensure that the list of pre-requisites in FAQ 6.21 "How do I build
Cygwin" remains synchronized with this list.

2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>

	* README: Update.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog |  4 ++++
 winsup/doc/README    | 23 ++---------------------
 2 files changed, 6 insertions(+), 21 deletions(-)

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 77985b8..841bbe2 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,5 +1,9 @@
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
 
+	* README: Update.
+
+2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
+
 	* Makefile.in (FAQ_SOURCES): Remove and generate with xidepend.
 
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
diff --git a/winsup/doc/README b/winsup/doc/README
index fe1adbd..24970f8 100644
--- a/winsup/doc/README
+++ b/winsup/doc/README
@@ -1,28 +1,9 @@
-The cygwin-doc source files are kept in CVS. Please see
-https://cygwin.com/cvs.html for more information.
+ADDITIONAL BUILD REQUIREMENTS FOR DOCUMENTATION
 
-BUILD REQUIREMENTS:
-
-bash
-bzip2
-coreutils
-cygwin
 dblatex
 docbook-xml45
 docbook-xsl
+docbook2x-texi
 gzip
-make
 texinfo
-perl
 xmlto
-
-OTHER NOTES:
-
-You may use docbook2X to convert the DocBook files into info pages.
-I have not been able to get a working docbook2X installation on Cygwin,
-so currently I convert the files on a machine running GNU/Linux.
-
-A few handmade files (cygwin.texi, intro.3, etc.) are found in the
-cygwin-doc-x.y-z-src.tar.bz2 package. It also contains the utilities for
-building the cygwin-doc-x.y-z "binary" package--simply run each step in
-the cygwin-doc-x.y-z.sh script.
-- 
2.1.4

[PATCH 1/5] winsup/doc: Create info pages from cygwin documentation

[Jon TURNEY]

v2:
Updated to use docbook2x-texi not docbook2texi, since source is now docbook XML.
Tweak DocBook XML so info directory entry has a description.

v3:
Use a custom charmap to handle ®

v4:
Proper build avoidance
texinfo node references may not contain ':', so provide alternate text for a few
xref targets

2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>

	* Makefile.in (install-info, cygwin-ug-net.info)
	(cygwin-api.info): Add.
	* cygwin-ug-net.xml: Add texinfo-node.
	* cygwin-api.xml: Ditto.
	* ntsec.xml (db_home): Add texinfo-node for titles containing a
	':' which are the targets of an xref.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog         |  9 +++++++++
 winsup/doc/Makefile.in       | 26 +++++++++++++++++++++++---
 winsup/doc/cygwin-api.xml    |  3 +++
 winsup/doc/cygwin-ug-net.xml |  3 +++
 winsup/doc/ntsec.xml         | 18 +++++++++++++++---
 5 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 23bd06c..0a23870 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,12 @@
+2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
+
+	* Makefile.in (install-info, cygwin-ug-net.info)
+	(cygwin-api.info): Add.
+	* cygwin-ug-net.xml: Add texinfo-node.
+	* cygwin-api.xml: Ditto.
+	* ntsec.xml (db_home): Add texinfo-node for titles containing a
+	':' which are the targets of an xref.
+
 2015-06-20  Corinna Vinschen  <corinna@vinschen.de>
 
 	* new-features.xml (ov-new2.1): Add alterante signal stack info.
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in
index 0205e67..9f6774b 100644
--- a/winsup/doc/Makefile.in
+++ b/winsup/doc/Makefile.in
@@ -19,6 +19,7 @@ htmldir = @htmldir@
 mandir = @mandir@
 man1dir = $(mandir)/man1
 man3dir = $(mandir)/man3
+infodir:=@infodir@
 
 override INSTALL:=@INSTALL@
 override INSTALL_DATA:=@INSTALL_DATA@
@@ -29,6 +30,7 @@ CC:=@CC@
 CC_FOR_TARGET:=@CC@
 
 XMLTO:=xmlto --skip-validation --with-dblatex
+DOCBOOK2XTEXI:=docbook2x-texi --xinclude --info --utf8trans-map=charmap
 
 include $(srcdir)/../Makefile.common
 -include Makefile.dep
@@ -40,7 +42,8 @@ FAQ_SOURCES:= $(wildcard $(srcdir)/faq*.xml)
 .html.body:
 	$(srcdir)/bodysnatcher.pl $<
 
-.PHONY: all clean install install-all install-pdf install-html install-man
+.PHONY: all clean install install-all install-pdf install-html install-man \
+	info install-info
 
 all: Makefile Makefile.dep \
 	cygwin-ug-net/cygwin-ug-net.html \
@@ -50,7 +53,8 @@ all: Makefile Makefile.dep \
 	cygwin-ug-net/cygwin-ug-net.pdf \
 	cygwin-api/cygwin-api.pdf \
 	utils2man.stamp \
-	api2man.stamp
+	api2man.stamp \
+	cygwin-ug-net.info cygwin-api.info
 
 Makefile: $(srcdir)/Makefile.in
 	/bin/sh ./config.status
@@ -61,10 +65,11 @@ clean:
 	rm -Rf cygwin-api cygwin-ug cygwin-ug-net faq
 	rm -f *.1 utils2man.stamp
 	rm -f *.3 api2man.stamp
+	rm -f *.info* charmap
 
 install: install-all
 
-install-all: install-pdf install-html install-man
+install-all: install-pdf install-html install-man install-info
 
 install-pdf: cygwin-ug-net/cygwin-ug-net.pdf cygwin-api/cygwin-api.pdf
 	@$(MKDIRP) $(DESTDIR)$(docdir)
@@ -84,6 +89,10 @@ install-man: utils2man.stamp api2man.stamp
 	@$(MKDIRP) $(DESTDIR)$(man3dir)
 	$(INSTALL_DATA) *.3 $(DESTDIR)$(man3dir)
 
+install-info: cygwin-ug-net.info cygwin-api.info
+	$(MKDIRP) $(DESTDIR)$(infodir)
+	$(INSTALL_DATA) *.info* $(DESTDIR)$(infodir)
+
 cygwin-ug-net/cygwin-ug-net-nochunks.html.gz : $(cygwin-ug-net_SOURCES) html.xsl
 	-$(XMLTO) html-nochunks -m $(srcdir)/html.xsl $<
 	-@$(MKDIRP) cygwin-ug-net
@@ -101,6 +110,9 @@ utils2man.stamp: $(cygwin-ug-net_SOURCES) man.xsl
 	$(XMLTO) man -m ${srcdir}/man.xsl $<
 	@touch $@
 
+cygwin-ug-net.info: $(cygwin-ug-net_SOURCES) charmap
+	-$(DOCBOOK2XTEXI) $(srcdir)/cygwin-ug-net.xml --string-param output-file=cygwin-ug-net
+
 cygwin-api/cygwin-api.html : $(cygwin-api_SOURCES) html.xsl
 	-$(XMLTO) html -o cygwin-api/ -m $(srcdir)/html.xsl $<
 
@@ -111,6 +123,14 @@ api2man.stamp: $(cygwin-api_SOURCES) man.xsl
 	$(XMLTO) man -m ${srcdir}/man.xsl $<
 	@touch $@
 
+cygwin-api.info: $(cygwin-api_SOURCES) charmap
+	-$(DOCBOOK2XTEXI) $(srcdir)/cygwin-api.xml --string-param output-file=cygwin-api
+
+# this generates a custom charmap for docbook2x-texi which has a mapping for &reg;
+charmap:
+	cp /usr/share/docbook2X/charmaps/texi.charmap charmap
+	echo "ae (R)" >>charmap
+
 faq/faq.html : $(FAQ_SOURCES)
 	-$(XMLTO) html -o faq -m $(srcdir)/html.xsl $(srcdir)/faq.xml
 	-sed -i 's;<a name="id[mp][0-9]*"></a>;;g' faq/faq.html
diff --git a/winsup/doc/cygwin-api.xml b/winsup/doc/cygwin-api.xml
index 7b831d9..267c2cb 100644
--- a/winsup/doc/cygwin-api.xml
+++ b/winsup/doc/cygwin-api.xml
@@ -6,6 +6,9 @@
 
   <bookinfo>
     <title>Cygwin API Reference</title>
+    <abstract role="texinfo-node">
+      <para>Cygwin API Reference</para>
+    </abstract>
       <xi:include href="legal.xml"/>
   </bookinfo>
 
diff --git a/winsup/doc/cygwin-ug-net.xml b/winsup/doc/cygwin-ug-net.xml
index f8b40e6..b6a9eef 100644
--- a/winsup/doc/cygwin-ug-net.xml
+++ b/winsup/doc/cygwin-ug-net.xml
@@ -5,6 +5,9 @@
 <book id="cygwin-ug-net" xmlns:xi="http://www.w3.org/2001/XInclude">
   <bookinfo>
     <title>Cygwin User's Guide</title>
+    <abstract role="texinfo-node">
+      <para>Cygwin User's Guide</para>
+    </abstract>
 		<xi:include href="legal.xml"/>
   </bookinfo>
 
diff --git a/winsup/doc/ntsec.xml b/winsup/doc/ntsec.xml
index d982867..ae0a119 100644
--- a/winsup/doc/ntsec.xml
+++ b/winsup/doc/ntsec.xml
@@ -1431,7 +1431,11 @@ following sections explain the settings in detail.
 
 </sect4>
 
-<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
+<sect4 id="ntsec-mapping-nsswitch-home">
+  <sectioninfo>
+    <title role="texinfo-node">The <literal>db_home</literal> setting</title>
+  </sectioninfo>
+    <title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
 
 <para>
 The <literal>db_home:</literal> setting defines how Cygwin fetches the user's
@@ -1518,7 +1522,11 @@ So by default, Cygwin just sets the home dir to
 
 </sect4>
 
-<sect4 id="ntsec-mapping-nsswitch-shell"><title id="ntsec-mapping-nsswitch-shell.title">The <literal>db_shell:</literal> setting</title>
+<sect4 id="ntsec-mapping-nsswitch-shell">
+  <sectioninfo>
+    <title role="texinfo-node">The <literal>db_shell</literal> setting</title>
+  </sectioninfo>
+  <title id="ntsec-mapping-nsswitch-shell.title">The <literal>db_shell:</literal> setting</title>
 
 <para>
 The <literal>db_shell:</literal> setting defines how Cygwin fetches the user's
@@ -1593,7 +1601,11 @@ As for <literal>db_home:</literal>, the default setting for
 
 </sect4>
 
-<sect4 id="ntsec-mapping-nsswitch-gecos"><title id="ntsec-mapping-nsswitch-gecos.title">The <literal>db_gecos:</literal> setting</title>
+<sect4 id="ntsec-mapping-nsswitch-gecos">
+  <sectioninfo>
+    <title role="texinfo-node">The <literal>db_gecos</literal> setting</title>
+  </sectioninfo>
+  <title id="ntsec-mapping-nsswitch-gecos.title">The <literal>db_gecos:</literal> setting</title>
 
 <para>
 The <literal>db_gecos:</literal> setting defines how to fetch additional
-- 
2.1.4

[PATCH 4/5] winsup/doc: Use xidepend to generate the source list for FAQ targets as well

[Jon TURNEY]

2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>

	* Makefile.in (FAQ_SOURCES): Remove and generate with xidepend.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog   | 4 ++++
 winsup/doc/Makefile.in | 6 ++----
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index ca3bac6..77985b8 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,5 +1,9 @@
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
 
+	* Makefile.in (FAQ_SOURCES): Remove and generate with xidepend.
+
+2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
+
 	* utils.xml: Remove 'Usage' prefix from synopses.
 
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in
index e215580..7cdc72c 100644
--- a/winsup/doc/Makefile.in
+++ b/winsup/doc/Makefile.in
@@ -35,8 +35,6 @@ DOCBOOK2XTEXI:=docbook2x-texi --xinclude --info --utf8trans-map=charmap
 include $(srcdir)/../Makefile.common
 -include Makefile.dep
 
-FAQ_SOURCES:= $(wildcard $(srcdir)/faq*.xml)
-
 .SUFFIXES: .html .body
 
 .html.body:
@@ -137,9 +135,9 @@ intro2man.stamp: intro.xml man.xsl
 	@echo ".so intro.1" >cygwin.1
 	@touch $@
 
-faq/faq.html : $(FAQ_SOURCES)
+faq/faq.html : $(faq_SOURCES)
 	-$(XMLTO) html -o faq -m $(srcdir)/html.xsl $(srcdir)/faq.xml
 	-sed -i 's;<a name="id[mp][0-9]*"></a>;;g' faq/faq.html
 
-Makefile.dep: cygwin-ug-net.xml cygwin-api.xml
+Makefile.dep: cygwin-ug-net.xml cygwin-api.xml faq.xml
 	cd $(srcdir) && ./xidepend $^ > "${CURDIR}/$@"
-- 
2.1.4

[PATCH 3/5] winsup/doc: Remove 'Usage' prefix from synopses

[Jon TURNEY]

Remove redundant 'Usage' prefix from synopses.

2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>

	* utils.xml: Remove 'Usage' prefix from synopses.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog |  4 +++
 winsup/doc/utils.xml | 88 ++++++++++++++++++++++++++--------------------------
 2 files changed, 48 insertions(+), 44 deletions(-)

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 1c944ad..ca3bac6 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,5 +1,9 @@
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
 
+	* utils.xml: Remove 'Usage' prefix from synopses.
+
+2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
+
 	* Makefile.in (intro2man.stamp): Add.
 	* intro.xml: New file.
 
diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml
index efadbba..5d3df69 100644
--- a/winsup/doc/utils.xml
+++ b/winsup/doc/utils.xml
@@ -27,18 +27,18 @@
 
       <refsynopsisdiv>
 	<screen>
-Usage: cygcheck [-v] [-h] PROGRAM
-       cygcheck -c [-d] [PACKAGE]
-       cygcheck -s [-r] [-v] [-h]
-       cygcheck -k
-       cygcheck -f FILE [FILE]...
-       cygcheck -l [PACKAGE]...
-       cygcheck -p REGEXP
-       cygcheck --delete-orphaned-installation-keys
-       cygcheck --enable-unique-object-names Cygwin-DLL
-       cygcheck --disable-unique-object-names Cygwin-DLL
-       cygcheck --show-unique-object-names Cygwin-DLL
-       cygcheck -h
+cygcheck [-v] [-h] PROGRAM
+cygcheck -c [-d] [PACKAGE]
+cygcheck -s [-r] [-v] [-h]
+cygcheck -k
+cygcheck -f FILE [FILE]...
+cygcheck -l [PACKAGE]...
+cygcheck -p REGEXP
+cygcheck --delete-orphaned-installation-keys
+cygcheck --enable-unique-object-names Cygwin-DLL
+cygcheck --disable-unique-object-names Cygwin-DLL
+cygcheck --show-unique-object-names Cygwin-DLL
+cygcheck -h
 	</screen>
       </refsynopsisdiv>
 
@@ -291,10 +291,10 @@ are unable to find another Cygwin DLL.
 
     <refsynopsisdiv>
     <screen>
-Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME...
-       cygpath [-c HANDLE]
-       cygpath [-ADHOPSW]
-       cygpath [-F ID]
+cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME...
+cygpath [-c HANDLE]
+cygpath [-ADHOPSW]
+cygpath [-F ID]
     </screen>
     </refsynopsisdiv>
 
@@ -466,7 +466,7 @@ explorer $XPATH &
 
     <refsynopsisdiv>
       <screen>
-Usage: dumper [OPTION] FILENAME WIN32PID
+dumper [OPTION] FILENAME WIN32PID
       </screen>
     </refsynopsisdiv>
 
@@ -526,8 +526,8 @@ error_start=x:\path\to\dumper.exe
 
     <refsynopsisdiv>
       <screen>
-Usage: getconf [-v specification] variable_name [pathname]
-       getconf -a [pathname]
+getconf [-v specification] variable_name [pathname]
+getconf -a [pathname]
       </screen>
     </refsynopsisdiv>
 
@@ -590,7 +590,7 @@ Other options:
 
     <refsynopsisdiv>
       <screen>
-Usage: getfacl [-adn] FILE [FILE2...]
+getfacl [-adn] FILE [FILE2...]
       </screen>
     </refsynopsisdiv>
 
@@ -655,8 +655,8 @@ line separates the ACLs for each file.
 
     <refsynopsisdiv>
       <screen>
-Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
-       kill -l [signal]
+kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
+kill -l [signal]
       </screen>
     </refsynopsisdiv>
 
@@ -772,7 +772,7 @@ SIGUSR2     31    user defined signal 2
 
     <refsynopsisdiv>
       <screen>
-Usage: ldd [OPTION]... FILE...
+ldd [OPTION]... FILE...
       </screen>
     </refsynopsisdiv>
 
@@ -812,9 +812,9 @@ Usage: ldd [OPTION]... FILE...
 
     <refsynopsisdiv>
       <screen>
-Usage: locale [-amvhV]
-   or: locale [-ck] NAME
-   or: locale [-usfnU]
+locale [-amvhV]
+locale [-ck] NAME
+locale [-usfnU]
       </screen>
     </refsynopsisdiv>
 
@@ -977,7 +977,7 @@ bash$ locale noexpr
 
     <refsynopsisdiv>
       <screen>
-Usage: minidumper [OPTION] FILENAME WIN32PID
+minidumper [OPTION] FILENAME WIN32PID
       </screen>
     </refsynopsisdiv>
 
@@ -1030,7 +1030,7 @@ Usage: minidumper [OPTION] FILENAME WIN32PID
 
     <refsynopsisdiv>
       <screen>
-Usage: mkgroup [OPTION]...
+mkgroup [OPTION]...
       </screen>
     </refsynopsisdiv>
 
@@ -1134,7 +1134,7 @@ groups on domain controllers and domain member machines.
 
     <refsynopsisdiv>
       <screen>
-Usage: mkpasswd [OPTIONS]...
+mkpasswd [OPTIONS]...
       </screen>
     </refsynopsisdiv>
 
@@ -1240,9 +1240,9 @@ on domain controllers and domain member machines.
 
     <refsynopsisdiv>
       <screen>
-Usage: mount [OPTION] [&lt;win32path&gt; &lt;posixpath&gt;]
-       mount -a
-       mount &lt;posixpath&gt;
+mount [OPTION] [&lt;win32path&gt; &lt;posixpath&gt;]
+mount -a
+mount &lt;posixpath&gt;
       </screen>
      </refsynopsisdiv>
 
@@ -1507,7 +1507,7 @@ D: on /d type fat (binary,user,noumount)
 
     <refsynopsisdiv>
       <screen>
-Usage: passwd [OPTION] [USER]
+passwd [OPTION] [USER]
       </screen>
     </refsynopsisdiv>
 
@@ -1668,7 +1668,7 @@ specifying an empty password.
 
     <refsynopsisdiv>
       <screen>
-Usage: pldd [OPTION...] PID
+pldd [OPTION...] PID
       </screen>
     </refsynopsisdiv>
 
@@ -1702,7 +1702,7 @@ Usage: pldd [OPTION...] PID
 
     <refsynopsisdiv>
       <screen>
-Usage: ps [-aefls] [-u UID]
+ps [-aefls] [-u UID]
       </screen>
     </refsynopsisdiv>
 
@@ -1775,7 +1775,7 @@ With no options, ps outputs the long format by default
 
     <refsynopsisdiv>
       <screen>
-Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY
+regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY
       </screen>
     </refsynopsisdiv>
 
@@ -1965,8 +1965,8 @@ Example: regtool get '\user\software\Microsoft\Clock\iFormat'
 
     <refsynopsisdiv>
       <screen>
-Usage: setfacl [-r] {-f ACL_FILE | -s acl_entries} FILE...
-       setfacl [-r] {-b|[-d acl_entries] [-m acl_entries]} FILE...
+setfacl [-r] {-f ACL_FILE | -s acl_entries} FILE...
+setfacl [-r] {-b|[-d acl_entries] [-m acl_entries]} FILE...
       </screen>
      </refsynopsisdiv>
 
@@ -2101,7 +2101,7 @@ $ getfacl source_file | setfacl -f - target_file
 
     <refsynopsisdiv>
       <screen>
-Usage: setmetamode [metabit|escprefix]
+setmetamode [metabit|escprefix]
       </screen>
     </refsynopsisdiv>
 
@@ -2141,7 +2141,7 @@ Other options:
 
     <refsynopsisdiv>
       <screen>
-Usage: ssp [options] low_pc high_pc command...
+ssp [options] low_pc high_pc command...
       </screen>
     </refsynopsisdiv>
 
@@ -2315,8 +2315,8 @@ $ ssp <literal>-v</literal> <literal>-s</literal> <literal>-l</literal> <literal
 
     <refsynopsisdiv>
       <screen>
-Usage: strace [OPTIONS] &lt;command-line&gt;
-Usage: strace [OPTIONS] -p &lt;pid&gt;
+strace [OPTIONS] &lt;command-line&gt;
+strace [OPTIONS] -p &lt;pid&gt;
       </screen>
     </refsynopsisdiv>
 
@@ -2410,7 +2410,7 @@ $ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' &am
 
     <refsynopsisdiv>
       <screen>
-Usage: tzset [OPTION]
+tzset [OPTION]
       </screen>
     </refsynopsisdiv>
 
@@ -2456,7 +2456,7 @@ setenv TZ `tzset`
 
     <refsynopsisdiv>
       <screen>
-Usage: umount [OPTION] [&lt;posixpath&gt;]
+umount [OPTION] [&lt;posixpath&gt;]
       </screen>
     </refsynopsisdiv>
 
-- 
2.1.4

[PATCH 0/5] More cygwin-doc stuff

[Jon TURNEY]

intro.1 and intro.3 man pages for Cygwin
Cygwin User's Guide and Cygwin API reference .info
A few documentation related cleanups.

Jon TURNEY (5):
  winsup/doc: Create info pages from cygwin documentation
  winsup/doc: Add intro man pages from cygwin-doc
  winsup/doc: Remove 'Usage' prefix from synopses
  winsup/doc: Use xidepend to generate the source list for FAQ targets
    as well
  winsup/doc: Update ancient README about building documentation

 winsup/doc/ChangeLog         |  26 ++++++
 winsup/doc/Makefile.in       |  40 +++++++--
 winsup/doc/README            |  23 +----
 winsup/doc/cygwin-api.xml    |   3 +
 winsup/doc/cygwin-ug-net.xml |   3 +
 winsup/doc/intro.xml         | 196 +++++++++++++++++++++++++++++++++++++++++++
 winsup/doc/ntsec.xml         |  18 +++-
 winsup/doc/utils.xml         |  88 +++++++++----------
 8 files changed, 321 insertions(+), 76 deletions(-)
 create mode 100644 winsup/doc/intro.xml

-- 
2.1.4

[PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc

[Jon TURNEY]

v2:
intro.1 and cygwin.1 are identical. Make cygwin.1 a link to intro.1
Update dates in static man pages

v3:
Use doclifter to convert intro.[13] to DocBook XML
Clean up markup and fix a couple of spelling mistakes.
Build and install manpages from XML

2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>

	* Makefile.in (intro2man.stamp): Add.
	* intro.xml: New file.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog   |   5 ++
 winsup/doc/Makefile.in |   8 +-
 winsup/doc/intro.xml   | 196 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 208 insertions(+), 1 deletion(-)
 create mode 100644 winsup/doc/intro.xml

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 0a23870..1c944ad 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,5 +1,10 @@
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
 
+	* Makefile.in (intro2man.stamp): Add.
+	* intro.xml: New file.
+
+2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
+
 	* Makefile.in (install-info, cygwin-ug-net.info)
 	(cygwin-api.info): Add.
 	* cygwin-ug-net.xml: Add texinfo-node.
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in
index 9f6774b..e215580 100644
--- a/winsup/doc/Makefile.in
+++ b/winsup/doc/Makefile.in
@@ -54,6 +54,7 @@ all: Makefile Makefile.dep \
 	cygwin-api/cygwin-api.pdf \
 	utils2man.stamp \
 	api2man.stamp \
+	intro2man.stamp \
 	cygwin-ug-net.info cygwin-api.info
 
 Makefile: $(srcdir)/Makefile.in
@@ -83,7 +84,7 @@ install-html: cygwin-ug-net/cygwin-ug-net.html cygwin-api/cygwin-api.html
 	$(INSTALL_DATA) cygwin-api/*.html $(DESTDIR)$(htmldir)/cygwin-api
 	$(INSTALL_DATA) cygwin-api/cygwin-api.html $(DESTDIR)$(htmldir)/cygwin-api/index.html
 
-install-man: utils2man.stamp api2man.stamp
+install-man: utils2man.stamp api2man.stamp intro2man.stamp
 	@$(MKDIRP) $(DESTDIR)$(man1dir)
 	$(INSTALL_DATA) *.1 $(DESTDIR)$(man1dir)
 	@$(MKDIRP) $(DESTDIR)$(man3dir)
@@ -131,6 +132,11 @@ charmap:
 	cp /usr/share/docbook2X/charmaps/texi.charmap charmap
 	echo "ae (R)" >>charmap
 
+intro2man.stamp: intro.xml man.xsl
+	-$(XMLTO) man -m ${srcdir}/man.xsl $<
+	@echo ".so intro.1" >cygwin.1
+	@touch $@
+
 faq/faq.html : $(FAQ_SOURCES)
 	-$(XMLTO) html -o faq -m $(srcdir)/html.xsl $(srcdir)/faq.xml
 	-sed -i 's;<a name="id[mp][0-9]*"></a>;;g' faq/faq.html
diff --git a/winsup/doc/intro.xml b/winsup/doc/intro.xml
new file mode 100644
index 0000000..427e1eb
--- /dev/null
+++ b/winsup/doc/intro.xml
@@ -0,0 +1,196 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<reference id="intro" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <referenceinfo>
+    <xi:include href="legal.xml"/>
+  </referenceinfo>
+  <title>Cygwin</title>
+  <refentry id="intro1">
+    <refmeta>
+      <refentrytitle>intro</refentrytitle>
+      <manvolnum>1</manvolnum>
+      <refmiscinfo class="manual">Cygwin</refmiscinfo>
+    </refmeta>
+    <refnamediv>
+      <refname>intro</refname>
+      <refpurpose>Introduction to the Cygwin Environment</refpurpose>
+    </refnamediv>
+    <refsect1>
+      <title>DESCRIPTION</title>
+      <para><emphasis>Cygwin</emphasis> is a Linux-like environment for
+      Windows. It consists of two parts:</para>
+      <para>A DLL (<filename>cygwin1.dll</filename>) which acts as a Linux API
+      emulation layer providing substantial Linux API functionality. The
+      <citerefentry><refentrytitle>intro</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      man page gives an introduction to this API.</para>
+      <para>A collection of tools which provide Linux look and feel.  This man
+      page describes the user environment.</para>
+    </refsect1>
+    <refsect1>
+      <title>AVAILABILITY</title>
+      <para><emphasis>Cygwin</emphasis> is developed by volunteers collaborating
+      over the Internet. It is distributed through the website <ulink
+      url="http://cygwin.com">http://cygwin.com</ulink>, where you can find
+      extensive documentation, including FAQ, User's Guide, and API
+      Reference. The <emphasis>Cygwin</emphasis> website should be considered
+      the authoritative source of information. The source code, released under
+      the <emphasis>GNU General Public License, Version 2</emphasis>, is also
+      available from the website or one of the mirrors.</para>
+    </refsect1>
+    <refsect1>
+      <title>COMPATIBILITY</title>
+      <para><emphasis>Cygwin</emphasis> uses the GNU versions of many of the
+      standard UNIX command-line utilities (<command>sed</command>,
+      <command>awk</command>, etc.), so the user environment is more similar to
+      a Linux system than, for example, Sun Solaris.</para>
+      <para>The default login shell and <command>/bin/sh</command> for
+      <emphasis>Cygwin</emphasis> is <command>bash</command>, the GNU
+      "Bourne-Again Shell", but other shells such as <command>tcsh</command>
+      (an improved <command>csh</command>) are also available and can be
+      installed using <emphasis>Cygwin</emphasis>'s setup.</para>
+    </refsect1>
+    <refsect1>
+      <title>NOTES</title>
+      <para>To port applications you will need to install the development tools,
+      which you can do by selecting <package>gcc</package> in
+      <emphasis>setup.exe</emphasis> (dependencies are automatically handled).
+      If you need a specific program or library, you can search for a
+      <emphasis>Cygwin</emphasis> package containing it at:</para>
+      <para>
+	<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>
+      </para>
+      <para>If you are a UNIX veteran who plans to use
+      <emphasis>Cygwin</emphasis> extensively, you will probably find it worth
+      your while to learn to use <emphasis>Cygwin</emphasis>-specific tools that
+      provide a UNIX-like interface to common operations. For example,
+      <command>cygpath</command> converts between UNIX and Win32-style
+      pathnames. The full documentation for these utilities is at:</para>
+      <para>
+	<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html">http://cygwin.com/cygwin-ug-net/using-utils.html</ulink>
+      </para>
+      <para>The optional <package>cygutils</package> package also contains
+      utilities that help with common problems, such as
+      <command>dos2unix</command> and <command>unix2dos</command> for the
+      CRLF issue.</para>
+    </refsect1>
+    <refsect1>
+      <title>DOCUMENTATION</title>
+      <para>In addition to man pages and texinfo documentation, many
+      <emphasis>Cygwin</emphasis> packages provide system-independent
+      documentation in the <filename>/usr/share/doc/</filename> directory and
+      <emphasis>Cygwin</emphasis>-specific documentation in
+      <filename>/usr/share/doc/Cygwin/</filename></para>
+      <para>For example, if you have both <command>less</command> and
+      <command>cron</command> installed, the command <command>less
+      /usr/share/doc/Cygwin/cron.README</command> would display the instructions
+      to set up <command>cron</command> on your system.</para>
+    </refsect1>
+    <refsect1>
+      <title>REPORTING BUGS</title>
+      <para>If you find a bug in <emphasis>Cygwin</emphasis>, please read</para>
+      <para>
+	<ulink url="http://cygwin.com/bugs.html">http://cygwin.com/bugs.html</ulink>
+      </para>
+      <para>and follow the instructions for reporting found there.  If you are
+      able to track down the source of the bug and can provide a fix, there are
+      instructions for contributing patches at:</para>
+      <para>
+	<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>SEE ALSO</title>
+      <para>
+	<citerefentry>
+	  <refentrytitle>intro</refentrytitle>
+	  <manvolnum>3</manvolnum>
+	</citerefentry>
+      </para>
+    </refsect1>
+  </refentry>
+
+  <refentry id="intro3">
+    <refmeta>
+      <refentrytitle>intro</refentrytitle>
+      <manvolnum>3</manvolnum>
+      <refmiscinfo class="manual">Cygwin</refmiscinfo>
+    </refmeta>
+    <refnamediv>
+      <refname>intro</refname>
+      <refpurpose>Introduction to the Cygwin API</refpurpose>
+    </refnamediv>
+    <refsect1>
+      <title>DESCRIPTION</title>
+      <para><emphasis>Cygwin</emphasis> is a Linux-like environment for
+      Windows. It consists of two parts:</para>
+      <para>A DLL (<filename>cygwin1.dll</filename>) which acts as a Linux API
+      emulation layer providing substantial Linux API functionality.  This page
+      describes the API provided by the DLL.
+      </para>
+      <para>A collection of tools which provide Linux look and feel.  This
+      environment is described in the
+      <citerefentry><refentrytitle>intro</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      man page.</para>
+    </refsect1>
+    <refsect1>
+      <title>AVAILABILITY</title>
+      <para><emphasis>Cygwin</emphasis> is developed by volunteers collaborating
+      over the Internet. It is distributed through the website <ulink
+      url="http://cygwin.com">http://cygwin.com</ulink>. The website has
+      extensive documentation, including FAQ, User's Guide, and API
+      Reference. It should be considered the authoritative source of
+      information. The source code, released under the <emphasis>GNU General
+      Public License, Version 2</emphasis>, is also available from the website
+      or one of the mirrors.</para>
+    </refsect1>
+    <refsect1>
+      <title>COMPATIBILITY</title>
+      <para><emphasis>Cygwin</emphasis> policy is to attempt to adhere to
+      <emphasis>POSIX/SUSv2</emphasis> (Portable Operating System Interface for
+      UNIX / The Single UNIX Specification, Version 2) where possible.</para>
+      <para><emphasis>SUSv2</emphasis> is available online at:</para>
+      <para>
+	<ulink url="http://www.opengroup.org/onlinepubs/007908799/">http://www.opengroup.org/onlinepubs/007908799/</ulink>
+      </para>
+      <para>For compatibility information about specific functions, see the API
+      Reference at:</para>
+      <para>
+	<ulink url="http://cygwin.com/cygwin-api/cygwin-api.html">http://cygwin.com/cygwin-api/cygwin-api.html</ulink>
+      </para>
+      <para>Where these standards are ambiguous, Cygwin tries to mimic
+      <emphasis>Linux</emphasis>.  However, <emphasis>Cygwin</emphasis> uses
+      <emphasis>newlib</emphasis> instead of <emphasis>glibc</emphasis> as its C
+      Library, available at:</para>
+      <para>
+	<ulink url="http://sources.redhat.com/newlib/">http://sources.redhat.com/newlib/</ulink>
+      </para>
+      <para>Keep in mind that there are many underlying differences between UNIX
+      and Win32 (for example, a case-insensitive file system), making complete
+      compatibility an ongoing challenge.</para>
+    </refsect1>
+    <refsect1>
+      <title>REPORTING BUGS</title>
+      <para>If you find a bug in <emphasis>Cygwin</emphasis>, please read</para>
+      <para>
+	<ulink url="http://cygwin.com/bugs.html">http://cygwin.com/bugs.html</ulink>
+      </para>
+      <para>and follow the instructions for reporting found there.  If you are
+      able to track down the source of the bug and can provide a fix, there are
+      instructions for contributing patches at:</para>
+      <para>
+	<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>SEE ALSO</title>
+      <para>
+	<citerefentry>
+	  <refentrytitle>intro</refentrytitle>
+	  <manvolnum>1</manvolnum>
+	</citerefentry>
+      </para>
+    </refsect1>
+  </refentry>
+
+</reference>
-- 
2.1.4

Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation

[Corinna Vinschen]

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

On Jun 22 15:39, Jon TURNEY wrote:
> v2:
> Updated to use docbook2x-texi not docbook2texi, since source is now docbook XML.
> Tweak DocBook XML so info directory entry has a description.
> 
> v3:
> Use a custom charmap to handle ®
> 
> v4:
> Proper build avoidance
> texinfo node references may not contain ':', so provide alternate text for a few
> xref targets
> 
> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
> 
> 	* Makefile.in (install-info, cygwin-ug-net.info)
> 	(cygwin-api.info): Add.
> 	* cygwin-ug-net.xml: Add texinfo-node.
> 	* cygwin-api.xml: Ditto.

This is fine.

> 	* ntsec.xml (db_home): Add texinfo-node for titles containing a
> 	':' which are the targets of an xref.

This... not so much.  Let's simply remove the colons instead:

-<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
+<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home</literal> setting</title>
[...]


Thanks,
Corinna

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

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

Re: [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc

[Corinna Vinschen]

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

A few nits:

[intro.1]
> +      <para><emphasis>Cygwin</emphasis> is a Linux-like environment for
> +      Windows. It consists of two parts:</para>
> +      <para>A DLL (<filename>cygwin1.dll</filename>) which acts as a Linux API

s#Linux#POSIX#

> +      emulation layer providing substantial Linux API functionality. The

s#Linux API functionality#POSIX API functionality modeled after the GNU/Linux operating system#

> +      <citerefentry><refentrytitle>intro</refentrytitle><manvolnum>3</manvolnum></citerefentry>
> +      man page gives an introduction to this API.</para>
> +      <para>A collection of tools which provide Linux look and feel.  This man
> +      page describes the user environment.</para>
> +    </refsect1>
> +    <refsect1>
> +      <title>AVAILABILITY</title>
> +      <para><emphasis>Cygwin</emphasis> is developed by volunteers collaborating
> +      over the Internet. It is distributed through the website <ulink
> +      url="http://cygwin.com">http://cygwin.com</ulink>, where you can find
> +      extensive documentation, including FAQ, User's Guide, and API
> +      Reference. The <emphasis>Cygwin</emphasis> website should be considered
> +      the authoritative source of information. The source code, released under
> +      the <emphasis>GNU General Public License, Version 2</emphasis>, is also

s#Version 2#Version 3 (GPLv3+)#

[intro.3]
> +      <para><emphasis>Cygwin</emphasis> is a Linux-like environment for
> +      Windows. It consists of two parts:</para>
> +      <para>A DLL (<filename>cygwin1.dll</filename>) which acts as a Linux API

s#Linux#POSIX#

> +      emulation layer providing substantial Linux API functionality.  This page

s#Linux API functionality#POSIX API functionality modeled after the
GNU/Linux operating system#

> +      describes the API provided by the DLL.
> +      </para>
> +      <para>A collection of tools which provide Linux look and feel.  This
> +      environment is described in the
> +      <citerefentry><refentrytitle>intro</refentrytitle><manvolnum>1</manvolnum></citerefentry>
> +      man page.</para>
> +    </refsect1>
> +    <refsect1>
> +      <title>AVAILABILITY</title>
> +      <para><emphasis>Cygwin</emphasis> is developed by volunteers collaborating
> +      over the Internet. It is distributed through the website <ulink
> +      url="http://cygwin.com">http://cygwin.com</ulink>. The website has
> +      extensive documentation, including FAQ, User's Guide, and API
> +      Reference. It should be considered the authoritative source of
> +      information. The source code, released under the <emphasis>GNU General
> +      Public License, Version 2</emphasis>, is also available from the website

s#Version 2#Version 3 (GPLv3+)#

> +      or one of the mirrors.</para>
> +    </refsect1>
> +    <refsect1>
> +      <title>COMPATIBILITY</title>
> +      <para><emphasis>Cygwin</emphasis> policy is to attempt to adhere to
> +      <emphasis>POSIX/SUSv2</emphasis> (Portable Operating System Interface for

s#POSIX/SUSv2#POSIX.1-2008/SUSv4#

> +      UNIX / The Single UNIX Specification, Version 2) where possible.</para>

s#Version 2#Version 4#

> +      <para><emphasis>SUSv2</emphasis> is available online at:</para>

s#SUSv2#POSIX.1-2008/SUSv4#

> +      <para>
> +	<ulink url="http://www.opengroup.org/onlinepubs/007908799/">http://www.opengroup.org/onlinepubs/007908799/</ulink>

http://pubs.opengroup.org/onlinepubs/9699919799/

> +      <para>Keep in mind that there are many underlying differences between UNIX
> +      and Win32 (for example, a case-insensitive file system), making complete
> +      compatibility an ongoing challenge.</para>

Is "case-insensitive file system" a good example?  For one thing, NTFS
is a case-sensitive filesystem, and only the Win32 API and the default
NT kernel setting in the registry enforces case-insensitivity.  See
https://cygwin.com/cygwin-ug-net/using-specialnames.html#pathnames-casesensitive

What about the OS consequently using UTF-16 as an example?

> +    </refsect1>
> +    <refsect1>
> +      <title>REPORTING BUGS</title>
> +      <para>If you find a bug in <emphasis>Cygwin</emphasis>, please read</para>
> +      <para>
> +	<ulink url="http://cygwin.com/bugs.html">http://cygwin.com/bugs.html</ulink>
> +      </para>
> +      <para>and follow the instructions for reporting found there.  If you are
> +      able to track down the source of the bug and can provide a fix, there are
> +      instructions for contributing patches at:</para>
> +      <para>
> +	<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>
> +      </para>
> +    </refsect1>
> +    <refsect1>
> +      <title>SEE ALSO</title>
> +      <para>
> +	<citerefentry>
> +	  <refentrytitle>intro</refentrytitle>
> +	  <manvolnum>1</manvolnum>

Shouldn't that be a 3 here?


Thanks,
Corinna

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

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

Re: [PATCH 3/5] winsup/doc: Remove 'Usage' prefix from synopses

[Corinna Vinschen]

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

On Jun 22 15:39, Jon TURNEY wrote:
> Remove redundant 'Usage' prefix from synopses.
> 
> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
> 
> 	* utils.xml: Remove 'Usage' prefix from synopses.

Ok.


Thanks,
Corinna

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

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

Re: [PATCH 4/5] winsup/doc: Use xidepend to generate the source list for FAQ targets as well

[Corinna Vinschen]

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

On Jun 22 15:39, Jon TURNEY wrote:
> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
> 
> 	* Makefile.in (FAQ_SOURCES): Remove and generate with xidepend.

Ok.


Thanks,
Corinna

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

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

Re: [PATCH 5/5] winsup/doc: Update ancient README about building documentation

[Corinna Vinschen]

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

On Jun 22 15:39, Jon TURNEY wrote:
> Update list of pre-requisites, everything else is obsolete.
> 
> Future work: Ensure that the list of pre-requisites in FAQ 6.21 "How do I build
> Cygwin" remains synchronized with this list.
> 
> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
> 
> 	* README: Update.

Ok.

Thanks,
Corinna

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

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

Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation

[Jon TURNEY]

On 22/06/2015 15:55, Corinna Vinschen wrote:
> On Jun 22 15:39, Jon TURNEY wrote:
>> v2:
>> Updated to use docbook2x-texi not docbook2texi, since source is now docbook XML.
>> Tweak DocBook XML so info directory entry has a description.
>>
>> v3:
>> Use a custom charmap to handle ®
>>
>> v4:
>> Proper build avoidance
>> texinfo node references may not contain ':', so provide alternate text for a few
>> xref targets
>>
>> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
>>
>> 	* Makefile.in (install-info, cygwin-ug-net.info)
>> 	(cygwin-api.info): Add.
>> 	* cygwin-ug-net.xml: Add texinfo-node.
>> 	* cygwin-api.xml: Ditto.
>
> This is fine.
>
>> 	* ntsec.xml (db_home): Add texinfo-node for titles containing a
>> 	':' which are the targets of an xref.
>
> This... not so much.  Let's simply remove the colons instead:
>
> -<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
> +<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home</literal> setting</title>
> [...]

I did consider this, but to be consistent it would needs to be removed 
from all section titles:

> <sect4 id="ntsec-mapping-nsswitch-pwdgrp"><title id="ntsec-mapping-nsswitch-pwdgrp.title">The <literal>passwd:</literal> and <literal>group:</literal> settings</title>
> <sect4 id="ntsec-mapping-nsswitch-enum"><title id="ntsec-mapping-nsswitch-enum.title">The <literal>db_enum:</literal> setting</title>
> <sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
> <sect4 id="ntsec-mapping-nsswitch-shell"><title id="ntsec-mapping-nsswitch-shell.title">The <literal>db_shell:</literal> setting</title>
> <sect4 id="ntsec-mapping-nsswitch-gecos"><title id="ntsec-mapping-nsswitch-gecos.title">The <literal>db_gecos:</literal> setting</title>

Even then, it's not consistent with the text, which always treats : as 
part of the keyword.

Re: [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc

[Jon TURNEY]

On 22/06/2015 16:14, Corinna Vinschen wrote:
> A few nits:

Thanks for the detailed review.

>> +      <para>Keep in mind that there are many underlying differences between UNIX
>> +      and Win32 (for example, a case-insensitive file system), making complete
>> +      compatibility an ongoing challenge.</para>
>
> Is "case-insensitive file system" a good example?  For one thing, NTFS
> is a case-sensitive filesystem, and only the Win32 API and the default
> NT kernel setting in the registry enforces case-insensitivity.  See
> https://cygwin.com/cygwin-ug-net/using-specialnames.html#pathnames-casesensitive
>
> What about the OS consequently using UTF-16 as an example?

I don't know if it actually helps to give a specific example here. The 
meaning is plain enough without one.

>> +    <refsect1>
>> +      <title>SEE ALSO</title>
>> +      <para>
>> +	<citerefentry>
>> +	  <refentrytitle>intro</refentrytitle>
>> +	  <manvolnum>1</manvolnum>
>
> Shouldn't that be a 3 here?

I don't think so.  This is a cross-reference to intro.1 in the SEE ALSO 
section of intro.3

[PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc

[Jon TURNEY]

v2:
intro.1 and cygwin.1 are identical. Make cygwin.1 a link to intro.1
Update dates in static man pages

v3:
Use doclifter to convert intro.[13] to DocBook XML
Clean up markup and fix a couple of spelling mistakes.
Build and install manpages from XML

v4:
Update to refer to GPLv3+, SUSv4

2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>

	* Makefile.in (intro2man.stamp): Add.
	* intro.xml: New file.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog   |   5 ++
 winsup/doc/Makefile.in |   8 +-
 winsup/doc/intro.xml   | 198 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 210 insertions(+), 1 deletion(-)
 create mode 100644 winsup/doc/intro.xml

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 0a23870..1c944ad 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,5 +1,10 @@
 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
 
+	* Makefile.in (intro2man.stamp): Add.
+	* intro.xml: New file.
+
+2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
+
 	* Makefile.in (install-info, cygwin-ug-net.info)
 	(cygwin-api.info): Add.
 	* cygwin-ug-net.xml: Add texinfo-node.
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in
index 9f6774b..e215580 100644
--- a/winsup/doc/Makefile.in
+++ b/winsup/doc/Makefile.in
@@ -54,6 +54,7 @@ all: Makefile Makefile.dep \
 	cygwin-api/cygwin-api.pdf \
 	utils2man.stamp \
 	api2man.stamp \
+	intro2man.stamp \
 	cygwin-ug-net.info cygwin-api.info
 
 Makefile: $(srcdir)/Makefile.in
@@ -83,7 +84,7 @@ install-html: cygwin-ug-net/cygwin-ug-net.html cygwin-api/cygwin-api.html
 	$(INSTALL_DATA) cygwin-api/*.html $(DESTDIR)$(htmldir)/cygwin-api
 	$(INSTALL_DATA) cygwin-api/cygwin-api.html $(DESTDIR)$(htmldir)/cygwin-api/index.html
 
-install-man: utils2man.stamp api2man.stamp
+install-man: utils2man.stamp api2man.stamp intro2man.stamp
 	@$(MKDIRP) $(DESTDIR)$(man1dir)
 	$(INSTALL_DATA) *.1 $(DESTDIR)$(man1dir)
 	@$(MKDIRP) $(DESTDIR)$(man3dir)
@@ -131,6 +132,11 @@ charmap:
 	cp /usr/share/docbook2X/charmaps/texi.charmap charmap
 	echo "ae (R)" >>charmap
 
+intro2man.stamp: intro.xml man.xsl
+	-$(XMLTO) man -m ${srcdir}/man.xsl $<
+	@echo ".so intro.1" >cygwin.1
+	@touch $@
+
 faq/faq.html : $(FAQ_SOURCES)
 	-$(XMLTO) html -o faq -m $(srcdir)/html.xsl $(srcdir)/faq.xml
 	-sed -i 's;<a name="id[mp][0-9]*"></a>;;g' faq/faq.html
diff --git a/winsup/doc/intro.xml b/winsup/doc/intro.xml
new file mode 100644
index 0000000..e76d9de
--- /dev/null
+++ b/winsup/doc/intro.xml
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<reference id="intro" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <referenceinfo>
+    <xi:include href="legal.xml"/>
+  </referenceinfo>
+  <title>Cygwin</title>
+  <refentry id="intro1">
+    <refmeta>
+      <refentrytitle>intro</refentrytitle>
+      <manvolnum>1</manvolnum>
+      <refmiscinfo class="manual">Cygwin</refmiscinfo>
+    </refmeta>
+    <refnamediv>
+      <refname>intro</refname>
+      <refpurpose>Introduction to the Cygwin Environment</refpurpose>
+    </refnamediv>
+    <refsect1>
+      <title>DESCRIPTION</title>
+      <para><emphasis>Cygwin</emphasis> is a Linux-like environment for
+      Windows. It consists of two parts:</para>
+      <para>A DLL (<filename>cygwin1.dll</filename>) which acts as a POSIX API
+      emulation layer providing substantial POSIX API functionality, modelled
+      after the GNU/Linux operating system. The
+      <citerefentry><refentrytitle>intro</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      man page gives an introduction to this API.</para>
+      <para>A collection of tools which provide Linux look and feel.  This man
+      page describes the user environment.</para>
+    </refsect1>
+    <refsect1>
+      <title>AVAILABILITY</title>
+      <para><emphasis>Cygwin</emphasis> is developed by volunteers collaborating
+      over the Internet. It is distributed through the website <ulink
+      url="http://cygwin.com">http://cygwin.com</ulink>, where you can find
+      extensive documentation, including FAQ, User's Guide, and API
+      Reference. The <emphasis>Cygwin</emphasis> website should be considered
+      the authoritative source of information. The source code, released under
+      the <emphasis>GNU General Public License, Version 3 (GPLv3+)</emphasis>,
+      is also available from the website or one of the mirrors.</para>
+    </refsect1>
+    <refsect1>
+      <title>COMPATIBILITY</title>
+      <para><emphasis>Cygwin</emphasis> uses the GNU versions of many of the
+      standard UNIX command-line utilities (<command>sed</command>,
+      <command>awk</command>, etc.), so the user environment is more similar to
+      a Linux system than, for example, Sun Solaris.</para>
+      <para>The default login shell and <command>/bin/sh</command> for
+      <emphasis>Cygwin</emphasis> is <command>bash</command>, the GNU
+      "Bourne-Again Shell", but other shells such as <command>tcsh</command>
+      (an improved <command>csh</command>) are also available and can be
+      installed using <emphasis>Cygwin</emphasis>'s setup.</para>
+    </refsect1>
+    <refsect1>
+      <title>NOTES</title>
+      <para>To port applications you will need to install the development tools,
+      which you can do by selecting <package>gcc</package> in
+      <emphasis>setup.exe</emphasis> (dependencies are automatically handled).
+      If you need a specific program or library, you can search for a
+      <emphasis>Cygwin</emphasis> package containing it at:</para>
+      <para>
+	<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>
+      </para>
+      <para>If you are a UNIX veteran who plans to use
+      <emphasis>Cygwin</emphasis> extensively, you will probably find it worth
+      your while to learn to use <emphasis>Cygwin</emphasis>-specific tools that
+      provide a UNIX-like interface to common operations. For example,
+      <command>cygpath</command> converts between UNIX and Win32-style
+      pathnames. The full documentation for these utilities is at:</para>
+      <para>
+	<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html">http://cygwin.com/cygwin-ug-net/using-utils.html</ulink>
+      </para>
+      <para>The optional <package>cygutils</package> package also contains
+      utilities that help with common problems, such as
+      <command>dos2unix</command> and <command>unix2dos</command> for the
+      CRLF issue.</para>
+    </refsect1>
+    <refsect1>
+      <title>DOCUMENTATION</title>
+      <para>In addition to man pages and texinfo documentation, many
+      <emphasis>Cygwin</emphasis> packages provide system-independent
+      documentation in the <filename>/usr/share/doc/</filename> directory and
+      <emphasis>Cygwin</emphasis>-specific documentation in
+      <filename>/usr/share/doc/Cygwin/</filename></para>
+      <para>For example, if you have both <command>less</command> and
+      <command>cron</command> installed, the command <command>less
+      /usr/share/doc/Cygwin/cron.README</command> would display the instructions
+      to set up <command>cron</command> on your system.</para>
+    </refsect1>
+    <refsect1>
+      <title>REPORTING BUGS</title>
+      <para>If you find a bug in <emphasis>Cygwin</emphasis>, please read</para>
+      <para>
+	<ulink url="http://cygwin.com/bugs.html">http://cygwin.com/bugs.html</ulink>
+      </para>
+      <para>and follow the instructions for reporting found there.  If you are
+      able to track down the source of the bug and can provide a fix, there are
+      instructions for contributing patches at:</para>
+      <para>
+	<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>SEE ALSO</title>
+      <para>
+	<citerefentry>
+	  <refentrytitle>intro</refentrytitle>
+	  <manvolnum>3</manvolnum>
+	</citerefentry>
+      </para>
+    </refsect1>
+  </refentry>
+
+  <refentry id="intro3">
+    <refmeta>
+      <refentrytitle>intro</refentrytitle>
+      <manvolnum>3</manvolnum>
+      <refmiscinfo class="manual">Cygwin</refmiscinfo>
+    </refmeta>
+    <refnamediv>
+      <refname>intro</refname>
+      <refpurpose>Introduction to the Cygwin API</refpurpose>
+    </refnamediv>
+    <refsect1>
+      <title>DESCRIPTION</title>
+      <para><emphasis>Cygwin</emphasis> is a Linux-like environment for
+      Windows. It consists of two parts:</para>
+      <para>A DLL (<filename>cygwin1.dll</filename>) which acts as a POSIX API
+      emulation layer providing substantial POSIX API functionality, modelled
+      after the GNU/Linux operating system. This page describes the API provided
+      by the DLL.
+      </para>
+      <para>A collection of tools which provide Linux look and feel.  This
+      environment is described in the
+      <citerefentry><refentrytitle>intro</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      man page.</para>
+    </refsect1>
+    <refsect1>
+      <title>AVAILABILITY</title>
+      <para><emphasis>Cygwin</emphasis> is developed by volunteers collaborating
+      over the Internet. It is distributed through the website <ulink
+      url="http://cygwin.com">http://cygwin.com</ulink>. The website has
+      extensive documentation, including FAQ, User's Guide, and API
+      Reference. It should be considered the authoritative source of
+      information. The source code, released under the <emphasis>GNU General
+      Public License, Version 3 (GPLv3+)</emphasis>, is also available from the
+      website or one of the mirrors.</para>
+    </refsect1>
+    <refsect1>
+      <title>COMPATIBILITY</title>
+      <para><emphasis>Cygwin</emphasis> policy is to attempt to adhere to
+      <emphasis>POSIX.1-2008/SUSv4</emphasis> (Portable Operating System
+      Interface for UNIX / The Single UNIX Specification, Version 4) where
+      possible.</para>
+      <para><emphasis>SUSv4</emphasis> is available online at:</para>
+      <para>
+	<ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/">http://pubs.opengroup.org/onlinepubs/9699919799/</ulink>
+      </para>
+      <para>For compatibility information about specific functions, see the API
+      Reference at:</para>
+      <para>
+	<ulink url="http://cygwin.com/cygwin-api/cygwin-api.html">http://cygwin.com/cygwin-api/cygwin-api.html</ulink>
+      </para>
+      <para>Where these standards are ambiguous, Cygwin tries to mimic
+      <emphasis>Linux</emphasis>.  However, <emphasis>Cygwin</emphasis> uses
+      <emphasis>newlib</emphasis> instead of <emphasis>glibc</emphasis> as its C
+      Library, available at:</para>
+      <para>
+	<ulink url="http://sources.redhat.com/newlib/">http://sources.redhat.com/newlib/</ulink>
+      </para>
+      <para>Keep in mind that there are many underlying differences between UNIX
+      and Win32 making complete compatibility an ongoing challenge.</para>
+    </refsect1>
+    <refsect1>
+      <title>REPORTING BUGS</title>
+      <para>If you find a bug in <emphasis>Cygwin</emphasis>, please read</para>
+      <para>
+	<ulink url="http://cygwin.com/bugs.html">http://cygwin.com/bugs.html</ulink>
+      </para>
+      <para>and follow the instructions for reporting found there.  If you are
+      able to track down the source of the bug and can provide a fix, there are
+      instructions for contributing patches at:</para>
+      <para>
+	<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>
+      </para>
+    </refsect1>
+    <refsect1>
+      <title>SEE ALSO</title>
+      <para>
+	<citerefentry>
+	  <refentrytitle>intro</refentrytitle>
+	  <manvolnum>1</manvolnum>
+	</citerefentry>
+      </para>
+    </refsect1>
+  </refentry>
+
+</reference>
-- 
2.1.4

Re: [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc

[Corinna Vinschen]

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

On Jun 22 18:47, Jon TURNEY wrote:
> v2:
> intro.1 and cygwin.1 are identical. Make cygwin.1 a link to intro.1
> Update dates in static man pages
> 
> v3:
> Use doclifter to convert intro.[13] to DocBook XML
> Clean up markup and fix a couple of spelling mistakes.
> Build and install manpages from XML
> 
> v4:
> Update to refer to GPLv3+, SUSv4
> 
> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
> 
> 	* Makefile.in (intro2man.stamp): Add.
> 	* intro.xml: New file.

GTG :)


Thanks,
Corinna

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

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

Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation

[Corinna Vinschen]

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

On Jun 22 18:15, Jon TURNEY wrote:
> On 22/06/2015 15:55, Corinna Vinschen wrote:
> >On Jun 22 15:39, Jon TURNEY wrote:
> >>v2:
> >>Updated to use docbook2x-texi not docbook2texi, since source is now docbook XML.
> >>Tweak DocBook XML so info directory entry has a description.
> >>
> >>v3:
> >>Use a custom charmap to handle ®
> >>
> >>v4:
> >>Proper build avoidance
> >>texinfo node references may not contain ':', so provide alternate text for a few
> >>xref targets
> >>
> >>2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
> >>
> >>	* Makefile.in (install-info, cygwin-ug-net.info)
> >>	(cygwin-api.info): Add.
> >>	* cygwin-ug-net.xml: Add texinfo-node.
> >>	* cygwin-api.xml: Ditto.
> >
> >This is fine.
> >
> >>	* ntsec.xml (db_home): Add texinfo-node for titles containing a
> >>	':' which are the targets of an xref.
> >
> >This... not so much.  Let's simply remove the colons instead:
> >
> >-<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
> >+<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home</literal> setting</title>
> >[...]
> 
> I did consider this, but to be consistent it would needs to be removed from
> all section titles:
> 
> ><sect4 id="ntsec-mapping-nsswitch-pwdgrp"><title id="ntsec-mapping-nsswitch-pwdgrp.title">The <literal>passwd:</literal> and <literal>group:</literal> settings</title>
> ><sect4 id="ntsec-mapping-nsswitch-enum"><title id="ntsec-mapping-nsswitch-enum.title">The <literal>db_enum:</literal> setting</title>
> ><sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
> ><sect4 id="ntsec-mapping-nsswitch-shell"><title id="ntsec-mapping-nsswitch-shell.title">The <literal>db_shell:</literal> setting</title>
> ><sect4 id="ntsec-mapping-nsswitch-gecos"><title id="ntsec-mapping-nsswitch-gecos.title">The <literal>db_gecos:</literal> setting</title>

I missed something, apparently.  From where are these three referenced,
but not the others?

> Even then, it's not consistent with the text, which always treats : as part
> of the keyword.

Yeah.  I'm not overly happy with this myself.  I didn't know how better
I could make clear that the colon is part of the keyword.

So, ok.  Please apply.  Maybe it makes sense to add texinfo-nodes for
the others in the list above as well?  Just in case?


Corinna

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

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

Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation

[Jon TURNEY]

On 22/06/2015 19:40, Corinna Vinschen wrote:
> On Jun 22 18:15, Jon TURNEY wrote:
>> On 22/06/2015 15:55, Corinna Vinschen wrote:
>>> On Jun 22 15:39, Jon TURNEY wrote:
>>>> v2:
>>>> Updated to use docbook2x-texi not docbook2texi, since source is now docbook XML.
>>>> Tweak DocBook XML so info directory entry has a description.
>>>>
>>>> v3:
>>>> Use a custom charmap to handle ®
>>>>
>>>> v4:
>>>> Proper build avoidance
>>>> texinfo node references may not contain ':', so provide alternate text for a few
>>>> xref targets
>>>>
>>>> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
>>>>
>>>> 	* Makefile.in (install-info, cygwin-ug-net.info)
>>>> 	(cygwin-api.info): Add.
>>>> 	* cygwin-ug-net.xml: Add texinfo-node.
>>>> 	* cygwin-api.xml: Ditto.
>>>
>>> This is fine.
>>>
>>>> 	* ntsec.xml (db_home): Add texinfo-node for titles containing a
>>>> 	':' which are the targets of an xref.
>>>
>>> This... not so much.  Let's simply remove the colons instead:
>>>
>>> -<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
>>> +<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home</literal> setting</title>
>>> [...]
>>
>> I did consider this, but to be consistent it would needs to be removed from
>> all section titles:
>>
>>> <sect4 id="ntsec-mapping-nsswitch-pwdgrp"><title id="ntsec-mapping-nsswitch-pwdgrp.title">The <literal>passwd:</literal> and <literal>group:</literal> settings</title>
>>> <sect4 id="ntsec-mapping-nsswitch-enum"><title id="ntsec-mapping-nsswitch-enum.title">The <literal>db_enum:</literal> setting</title>
>>> <sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
>>> <sect4 id="ntsec-mapping-nsswitch-shell"><title id="ntsec-mapping-nsswitch-shell.title">The <literal>db_shell:</literal> setting</title>
>>> <sect4 id="ntsec-mapping-nsswitch-gecos"><title id="ntsec-mapping-nsswitch-gecos.title">The <literal>db_gecos:</literal> setting</title>
>
> I missed something, apparently.  From where are these three referenced,
> but not the others?

> $ egrep -H 'xref linkend="ntsec-mapping-nsswitch-(home|shell|gecos|enum|pwdgrp)' ntsec.xml
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-home"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-shell"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-gecos"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-home"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-shell"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-gecos"></xref>.</seg>

It's seems to be a peculiarity of the .info format that a title with a 
':' in it is fine, but you can't make an xref to it without providing an 
alternate link text, as ':' terminates the link text

>> Even then, it's not consistent with the text, which always treats : as part
>> of the keyword.
>
> Yeah.  I'm not overly happy with this myself.  I didn't know how better
> I could make clear that the colon is part of the keyword.
>
> So, ok.  Please apply.  Maybe it makes sense to add texinfo-nodes for
> the others in the list above as well?  Just in case?

I think there are other titles elsewhere, which are also not the target 
of a xref.

A "warning: @ref cross-reference name should not contain `:'" is emitted 
where this problem exists.