* effectively.sgml: New file, "Using Cygwin Effectively with Windows".

4 files changed, 216 insertions, 1 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 99b465c80..755a6f12c 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,9 @@
+2003-07-31  Joshua Daniel Franklin <joshuadfranklin@yahoo.com
+
+	* effectively.sgml: New file, "Using Cygwin Effectively with Windows".
+	* legal.sgml: Update year in copyright notice.
+	* using.sgml: Include "Using Cygwin Effectively with Windows" section.
+
 2003-07-15  Christopher Faylor  <cgf@redhat.com>
 
 	* pathnames.sgml: Use correct registry key.  Clarify '@' operation.
diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml
new file mode 100644
index 000000000..d6c2d9ad9
--- /dev/null
+++ b/winsup/doc/effectively.sgml
@@ -0,0 +1,207 @@
+<sect1 id="using-effectively">
+<title>Using Cygwin effectively with Windows</title>
+
+<para>
+Cygwin is not a full operating system, and so must rely on Windows for
+accomplishing some tasks. For example, Cygwin provides a POSIX view
+of the Windows filesystem, but does not provide filesystem drivers of 
+its own. Therefore part of using Cygwin effectively is learning to use
+Windows effectively. 
+Many Windows utilities provide a good way to interact with Cygwin's 
+predominately command-line environment. For example, 
+<command>ipconfig.exe</command> provides information about network 
+configuration, and <command>net.exe</command> views and configures
+network file and printer resources.  Most of these tools
+support the <literal>/?</literal> switch to display usage information. 
+</para>
+
+<para>
+Unfortunately, no standard set of tools included with all versions of 
+Windows exists.  If you are unfamiliar with the tools available 
+on your system, here is a general guide.  Windows 95, 98, and ME have 
+very limited command-line configuration tools.  Windows NT 4.0 has much 
+better coverage, which Windows 2000 and XP expanded. 
+Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit 
+Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the 
+Windows Support Tools). Additionally, many independent sites such as 
+<ulink URL="http://download.com.com">download.com</ulink>, 
+<ulink URL="http://simtel.net">simtel.net</ulink>, 
+and <ulink URL="http://sysinternals.com">sysinternals.com</ulink>
+provide command-line utilities.  A few Windows tools, such as 
+<command>find.exe</command> and <command>sort.exe</command>,
+may conflict with the Cygwin versions; make sure that you use the full 
+path (<command>/usr/bin/find</command>) or that your Cygwin 
+<literal>bin</literal> directory comes first in your <EnVar>PATH</EnVar>.
+</para>
+
+<sect2> <title>Pathnames</title>
+
+<para>
+Windows programs do not understand POSIX pathnames, so any arguments 
+that reference the filesystem must be in Windows (or DOS) format or 
+translated.  Cygwin provides the <command>cygpath</command> utility for 
+converting between Windows and POSIX paths. A complete description of its 
+options and examples of its usage are in <Xref Linkend="cygpath">, 
+including a shell script for starting Windows Explorer in any directory. 
+The same format works for most Windows programs, for example 
+<screen>
+<literal>notepad.exe "$(cygpath -aw "Desktop/Phone Numbers.txt")"</literal>
+</screen>
+A few programs require a Windows-style, semicolon-delimited path list, 
+which <command>cygpath</command> can translate from a POSIX path with the
+<literal>-p</literal> option. For example, a Java compilation from 
+<command>bash</command> might look like this: 
+<screen>
+<literal>javac -cp "$(cygpath -pw "$CLASSPATH")" hello.java</literal>
+</screen>
+Since using quoting and subshells is somewhat awkward, it is often 
+preferable to use <command>cygpath</command> in shell scripts.
+</para>
+
+</sect2>
+
+<sect2> <title>Console Programs</title>
+<para>
+Another issue is receiving output from or giving input to the console-based 
+Windows programs.  Unfortunately, interacting with Windows console 
+applications is not a simple matter of using a translation utility. Windows 
+console applications and designed to run under <command>command.com</command> 
+or <command>cmd.exe</command>, and some do not deal gracefully with other
+situations.  Cygwin can receive console input only if it
+is also running in a console (DOS box) since Windows does not provide
+any way to attach to the backend of the console device. Another
+traditional Unix input/output method, ptys (pseudo-terminals), are 
+supported by Cygwin but not entirely by Windows.  The basic problem is 
+that a Cygwin pty is a pipe and some Windows applications do not like 
+having their input or output redirected to pipes.  
+</para>
+
+<para>
+To help deal with these issues, Cygwin supports customizable levels of 
+Windows verses Unix compatibility behavior.  To be most compatible with 
+Windows programs, use a DOS prompt, running only the occasional Cygwin 
+command or script. Next would be to run <command>bash</command> with 
+the default DOS box. To make Cygwin more Unix compatible in this case, 
+set <EnVar>CYGWIN=tty</EnVar> (see <Xref Linkend="using-cygwinenv">).
+Alternatively, the optional <command>rxvt</command> package provides 
+a native-Windows version of the popular X11 terminal emulator (it is not 
+necessary to set <EnVar>CYGWIN=tty</EnVar> with <command>rxvt</command>). 
+Using <command>rxvt.exe</command> provides the most Unix-like environment, 
+but expect some compatibility problems with Windows programs.
+</para>
+
+</sect2>
+
+<sect2> <title>Cygwin and Windows Networking</title>
+<para>
+Many popular Cygwin packages, such as <command>ncftp</command>, 
+<command>lynx</command>, and <command>wget</command>, require a 
+network connection.  Since Cygwin relies on Windows for connectivity, 
+if one of these tools is not working as expected you may need to 
+troubleshoot using Windows tools. The first test is to see if you
+can reach the URL's host with <command>ping.exe</command>, one of the 
+few utilities included with every Windows version since Windows 95.
+If you chose to install the inetutils package, you may have both
+Windows and Cygwin versions of utilities such as <command>ftp</command>
+and <command>telnet</command>. If you are having problems using one
+of these programs, see if the alternate one works as expected. 
+</para>
+
+<para>
+There are a variety of other programs available for specific situations.
+If your system does not have an always-on network connection, you 
+may be interested in <command>rasdial.exe</command> (or alternatives for
+Windows 95, 98, and ME) for automating dialup connections.  
+Users who frequently change their network 
+configuration can script these changes with <command>netsh.exe</command> 
+(Windows 2000 and XP). For proxy users, the open source 
+<ulink URL="http://apserver.sourceforge.net">
+NTLM Authorization Proxy Server</ulink> or the no-charge
+<ulink URL="http://www.hummingbird.com/products/nc/socks/index.html">
+Hummingbird SOCKS Proxy</ulink> may allow you to use Cygwin network
+programs in your environment.
+</para>
+
+</sect2>
+
+<sect2><title>The cygutils package</title>
+
+<para>
+The optional cygutils package contains miscellaneous tools that are
+small enough to not require their own package. It is not included in a
+default Cygwin install; select it from the Utils category in 
+<command>setup.exe</command>. Several of the cygutils tools are useful
+for interacting with Windows. 
+</para>
+
+<para>
+One of the hassles of Unix-Windows interoperability is the different line 
+endings on text files.  As mentioned in <Xref Linkend="using-textbinary">, 
+Unix tools such as <command>tr</command> can convert between CRLF and LF 
+endings, but cygutils provides several dedicated programs: 
+<command>conv</command>, <command>d2u</command>, <command>dos2unix</command>, 
+<command>u2d</command>, and <command>unix2dos</command>. Use the
+<literal>--help</literal> switch for usage information. 
+</para>
+
+<sect2><title>Creating shortcuts with cygutils</title>
+<para>
+Another problem area is between Unix-style links, which link one file
+to another, and Microsoft .lnk files, which provide a shortcut to a
+file.  They seem similar at first glance but, in reality, are fairly 
+different.  By default, Cygwin uses a mechanism that creates symbolic
+links that are compatible with standard Microsoft .lnk files. However,
+they do not include much of the information that is available in a 
+standard Microsoft shortcut, such as the working directory, an icon, 
+etc.  The cygutils package includes a <command>mkshortcut</command> 
+utility for creating standard Microsoft .lnk files.
+</para>
+
+<para>
+If Cygwin handled these native shortcuts like any other symlink, 
+you could not archive Microsoft .lnk files into <command>tar</command>
+archives and keep all the information in them.  After unpacking, 
+these shortcuts would have lost all the extra information and would
+be no different than standard Cygwin symlinks. Therefore these two types 
+of links are treated differently.  Unfortunately, this means that the 
+usual Unix way of creating and using symlinks does not work with 
+Windows shortcuts. 
+</para>
+</sect2>
+  
+<sect2><title>Printing with cygutils</title>
+<para>
+There are several options for printing from Cygwin, including the 
+<command>lpr</command> found in cygutils (not to be confused with the 
+native Windows <command>lpr.exe</command>). The easiest way to use cygutils' 
+<command>lpr</command> is to specify a default device name in the 
+<EnVar>PRINTER</EnVar> environment variable.  You may also specify a device 
+on the command line with the <literal>-d</literal> or <literal>-P</literal> 
+options, which will override the environment variable setting. 
+</para>
+
+<para>
+A device name 
+may be a UNC path (<literal>\\server_name\printer_name</literal>), a reserved 
+DOS device name (<literal>prn</literal>, <literal>lpt1</literal>), or a 
+local port name that is mapped to a printer share. Note that forward slashes 
+may be used in a UNC path (<literal>//server_name/printer_name</literal>),
+which is helpful when using <command>lpr</command> from a shell that uses
+the backslash as an escape character. 
+</para>
+
+<para>
+<command>lpr</command> sends raw data to the printer; no formatting is done.
+Many, but not all, printers accept plain text as input. If your printer 
+supports PostScript, packages such as 
+<command>a2ps</command> and <command>enscript</command> can prepare text
+files for printing. The ghostscript package also provides some translation
+from PostScript to various native printer languages. Additionally, a native 
+Windows application for printing PostScript, <command>gsprint</command>, is 
+available from the <ulink URL="http://www.cs.wisc.edu/~ghost/">Ghostscript
+website</ulink>.
+</para>
+
+</sect2>
+
+</sect1>
diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.sgml
index 1190ecce1..531128e33 100644
--- a/winsup/doc/legal.sgml
+++ b/winsup/doc/legal.sgml
@@ -1,6 +1,6 @@
 <LegalNotice id="legal">
 
-<Para>Copyright &copy; 1998,1999,2000,2001 Red Hat, Inc.</Para>
+<para>Copyright &copy; 1998, 1999, 2000, 2001, 2002, 2003 Red Hat, Inc.</para>
 
 <!--
 
diff --git a/winsup/doc/using.sgml b/winsup/doc/using.sgml
index 9d60e77bf..13a353c52 100644
--- a/winsup/doc/using.sgml
+++ b/winsup/doc/using.sgml
@@ -16,4 +16,6 @@ DOCTOOL-INSERT-using-cygwinenv
 
 DOCTOOL-INSERT-using-utils
 
+DOCTOOL-INSERT-using-effectively
+
 </chapter>