This is the mail archive of the cygwin-patches mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]