* [PATCH 4/5] winsup/doc: Use xidepend to generate the source list for FAQ targets as well
2015-06-22 14:40 [PATCH 0/5] More cygwin-doc stuff Jon TURNEY
@ 2015-06-22 14:40 ` Jon TURNEY
2015-06-22 15:16 ` Corinna Vinschen
2015-06-22 14:40 ` [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc Jon TURNEY
` (3 subsequent siblings)
4 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 14:40 UTC (permalink / raw)
To: cygwin-patches; +Cc: 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
^ permalink raw reply [flat|nested] 17+ messages in thread* [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc
2015-06-22 14:40 [PATCH 0/5] More cygwin-doc stuff Jon TURNEY
2015-06-22 14:40 ` [PATCH 4/5] winsup/doc: Use xidepend to generate the source list for FAQ targets as well Jon TURNEY
@ 2015-06-22 14:40 ` Jon TURNEY
2015-06-22 15:14 ` Corinna Vinschen
2015-06-22 14:40 ` [PATCH 5/5] winsup/doc: Update ancient README about building documentation Jon TURNEY
` (2 subsequent siblings)
4 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 14:40 UTC (permalink / raw)
To: cygwin-patches; +Cc: 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
^ permalink raw reply [flat|nested] 17+ messages in thread* Re: [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc
2015-06-22 14:40 ` [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc Jon TURNEY
@ 2015-06-22 15:14 ` Corinna Vinschen
2015-06-22 17:19 ` Jon TURNEY
0 siblings, 1 reply; 17+ messages in thread
From: Corinna Vinschen @ 2015-06-22 15:14 UTC (permalink / raw)
To: cygwin-patches
[-- 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 --]
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc
2015-06-22 15:14 ` Corinna Vinschen
@ 2015-06-22 17:19 ` Jon TURNEY
2015-06-22 17:47 ` Jon TURNEY
0 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 17:19 UTC (permalink / raw)
To: cygwin-patches
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
^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc
2015-06-22 17:19 ` Jon TURNEY
@ 2015-06-22 17:47 ` Jon TURNEY
2015-06-22 18:37 ` Corinna Vinschen
0 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 17:47 UTC (permalink / raw)
To: cygwin-patches; +Cc: 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
^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 5/5] winsup/doc: Update ancient README about building documentation
2015-06-22 14:40 [PATCH 0/5] More cygwin-doc stuff Jon TURNEY
2015-06-22 14:40 ` [PATCH 4/5] winsup/doc: Use xidepend to generate the source list for FAQ targets as well Jon TURNEY
2015-06-22 14:40 ` [PATCH 2/5] winsup/doc: Add intro man pages from cygwin-doc Jon TURNEY
@ 2015-06-22 14:40 ` Jon TURNEY
2015-06-22 15:17 ` Corinna Vinschen
2015-06-22 14:40 ` [PATCH 3/5] winsup/doc: Remove 'Usage' prefix from synopses Jon TURNEY
2015-06-22 14:40 ` [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation Jon TURNEY
4 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 14:40 UTC (permalink / raw)
To: cygwin-patches; +Cc: 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
^ permalink raw reply [flat|nested] 17+ messages in thread
* [PATCH 3/5] winsup/doc: Remove 'Usage' prefix from synopses
2015-06-22 14:40 [PATCH 0/5] More cygwin-doc stuff Jon TURNEY
` (2 preceding siblings ...)
2015-06-22 14:40 ` [PATCH 5/5] winsup/doc: Update ancient README about building documentation Jon TURNEY
@ 2015-06-22 14:40 ` Jon TURNEY
2015-06-22 15:15 ` Corinna Vinschen
2015-06-22 14:40 ` [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation Jon TURNEY
4 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 14:40 UTC (permalink / raw)
To: cygwin-patches; +Cc: 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] [<win32path> <posixpath>]
- mount -a
- mount <posixpath>
+mount [OPTION] [<win32path> <posixpath>]
+mount -a
+mount <posixpath>
</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] <command-line>
-Usage: strace [OPTIONS] -p <pid>
+strace [OPTIONS] <command-line>
+strace [OPTIONS] -p <pid>
</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] [<posixpath>]
+umount [OPTION] [<posixpath>]
</screen>
</refsynopsisdiv>
--
2.1.4
^ permalink raw reply [flat|nested] 17+ messages in thread* [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation
2015-06-22 14:40 [PATCH 0/5] More cygwin-doc stuff Jon TURNEY
` (3 preceding siblings ...)
2015-06-22 14:40 ` [PATCH 3/5] winsup/doc: Remove 'Usage' prefix from synopses Jon TURNEY
@ 2015-06-22 14:40 ` Jon TURNEY
2015-06-22 14:55 ` Corinna Vinschen
4 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 14:40 UTC (permalink / raw)
To: cygwin-patches; +Cc: 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 ®
+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
^ permalink raw reply [flat|nested] 17+ messages in thread* Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation
2015-06-22 14:40 ` [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation Jon TURNEY
@ 2015-06-22 14:55 ` Corinna Vinschen
2015-06-22 17:15 ` Jon TURNEY
0 siblings, 1 reply; 17+ messages in thread
From: Corinna Vinschen @ 2015-06-22 14:55 UTC (permalink / raw)
To: cygwin-patches
[-- 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 --]
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation
2015-06-22 14:55 ` Corinna Vinschen
@ 2015-06-22 17:15 ` Jon TURNEY
2015-06-22 18:40 ` Corinna Vinschen
0 siblings, 1 reply; 17+ messages in thread
From: Jon TURNEY @ 2015-06-22 17:15 UTC (permalink / raw)
To: cygwin-patches
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.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation
2015-06-22 17:15 ` Jon TURNEY
@ 2015-06-22 18:40 ` Corinna Vinschen
2015-06-23 11:27 ` Jon TURNEY
0 siblings, 1 reply; 17+ messages in thread
From: Corinna Vinschen @ 2015-06-22 18:40 UTC (permalink / raw)
To: cygwin-patches
[-- 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 --]
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation
2015-06-22 18:40 ` Corinna Vinschen
@ 2015-06-23 11:27 ` Jon TURNEY
0 siblings, 0 replies; 17+ messages in thread
From: Jon TURNEY @ 2015-06-23 11:27 UTC (permalink / raw)
To: cygwin-patches
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.
^ permalink raw reply [flat|nested] 17+ messages in thread