From ac51da48181e56cb45ddd609b50a3549287bdc27 Mon Sep 17 00:00:00 2001 From: Joshua Daniel Franklin Date: Sun, 11 Jan 2004 08:32:09 +0000 Subject: 2004-01-11 Joshua Daniel Franklin * Makefile.in: Add new target for single-file User's Guide, use new cygwin.dsl for output. * cygwin.dsl: New file, DSSSL stylesheet for custom Cygwin output. * cygwin-api.in.sgml: Update to DocBook SGML 4.2 DTD. * cygwin-ug-net.in.sgml: Update to DocBook SGML 4.2 DTD. * cygwin-ug.in.sgml: Update to DocBook SGML 4.2 DTD. * cygwinenv.sgml: Correct some tags. Add description of default values to ntsec, export, and error_start items. * dll.sgml: Add explanation of cyg prefix for DLLs. * effectively.sgml: Use systemitem tag for names of Cygwin packages. * how-programming.texinfo: Add example to FAQ entry. * pathnames.sgml: Add discussion of /proc filesystem. * setup-net.sgml: Correct some typos and grammar. --- winsup/doc/ChangeLog | 16 ++++ winsup/doc/Makefile.in | 22 ++++-- winsup/doc/cygwin-api.in.sgml | 2 +- winsup/doc/cygwin-ug-net.in.sgml | 2 +- winsup/doc/cygwin-ug.in.sgml | 2 +- winsup/doc/cygwin.dsl | 149 +++++++++++++++++++++++++++++++++++++ winsup/doc/cygwinenv.sgml | 72 ++++++++++-------- winsup/doc/dll.sgml | 16 +++- winsup/doc/effectively.sgml | 27 ++++--- winsup/doc/how-programming.texinfo | 12 +++ winsup/doc/pathnames.sgml | 24 ++++++ winsup/doc/setup-net.sgml | 16 ++-- 12 files changed, 297 insertions(+), 63 deletions(-) create mode 100644 winsup/doc/cygwin.dsl diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 96e19d9a9..ed67974ef 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,19 @@ +2004-01-11 Joshua Daniel Franklin + + * Makefile.in: Add new target for single-file User's Guide, use new + cygwin.dsl for output. + * cygwin.dsl: New file, DSSSL stylesheet for custom Cygwin output. + * cygwin-api.in.sgml: Update to DocBook SGML 4.2 DTD. + * cygwin-ug-net.in.sgml: Update to DocBook SGML 4.2 DTD. + * cygwin-ug.in.sgml: Update to DocBook SGML 4.2 DTD. + * cygwinenv.sgml: Correct some tags. Add description of default values + to ntsec, export, and error_start items. + * dll.sgml: Add explanation of cyg prefix for DLLs. + * effectively.sgml: Use systemitem tag for names of Cygwin packages. + * how-programming.texinfo: Add example to FAQ entry. + * pathnames.sgml: Add discussion of /proc filesystem. + * setup-net.sgml: Correct some typos and grammar. + 2003-09-01 Corinna Vinschen * pathnames.sgml: Remove description how to mount raw devices and diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in index 4be5f06e5..d3e7772e2 100644 --- a/winsup/doc/Makefile.in +++ b/winsup/doc/Makefile.in @@ -29,45 +29,51 @@ TEXI2HTML:=texi2html include $(srcdir)/../Makefile.common -TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool \ - cygwin-ug.sgml cygwin-ug-net.sgml +TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool.exe *.junk \ + cygwin-ug.sgml cygwin-ug \ + cygwin-ug-net.sgml cygwin-ug-net cygwin-ug-net.html \ + cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int .SUFFIXES: -# You can add cygwin-api/cygwin-api.html if you want to. all : \ cygwin-ug/cygwin-ug.html \ cygwin-ug-net/cygwin-ug-net.html \ + cygwin-ug-net.html \ cygwin-api-int/cygwin-api-int.html \ cygwin-api/cygwin-api.html \ $(DOC) \ $(HTMLDOC) clean: - rm -f $(TOCLEAN) + rm -Rf $(TOCLEAN) install: all +# jw -d $(srcdir)/cygwin.dsl#html cygwin-ug-net.sgml cygwin-ug/cygwin-ug.html : cygwin-ug.sgml doctool - -db2html $< + -db2html -d $(srcdir)/cygwin.dsl#html $< cygwin-ug.sgml : cygwin-ug.in.sgml ./doctool Makefile -./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $< +cygwin-ug-net.html : cygwin-ug-net.sgml doctool + -jw -d $(srcdir)/cygwin.dsl#html -u $< + cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.sgml doctool - -db2html $< + -db2html -d $(srcdir)/cygwin.dsl#html $< cygwin-ug-net.sgml : cygwin-ug-net.in.sgml ./doctool Makefile -./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $< cygwin-api/cygwin-api.html : cygwin-api.sgml - -db2html $< + -db2html -d $(srcdir)/cygwin.dsl#html $< cygwin-api.sgml : cygwin-api.in.sgml ./doctool Makefile -./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $< cygwin-api-int/cygwin-api-int.html : cygwin-api-int.sgml - -db2html $< + -db2html -d $(srcdir)/cygwin.dsl#html $< cygwin-api-int.sgml : cygwin-api.in.sgml ./doctool Makefile -./doctool -i -m $(SGMLDIRS) -s $(srcdir) -b cygwin-api-int -o $@ $< diff --git a/winsup/doc/cygwin-api.in.sgml b/winsup/doc/cygwin-api.in.sgml index 06baf5247..d141935f6 100644 --- a/winsup/doc/cygwin-api.in.sgml +++ b/winsup/doc/cygwin-api.in.sgml @@ -1,4 +1,4 @@ -1998Red Hat, Inc."> 1999,2000,2001 Red Hat, Inc."> diff --git a/winsup/doc/cygwin-ug.in.sgml b/winsup/doc/cygwin-ug.in.sgml index 91054f324..7727b1767 100644 --- a/winsup/doc/cygwin-ug.in.sgml +++ b/winsup/doc/cygwin-ug.in.sgml @@ -1,4 +1,4 @@ -1999,2000,2001 Red Hat, Inc."> + + +]]> + + +]]> +]> + + + + + + + +;; The following are +;; +;; ==================== +;; customize the print stylesheet +;; ==================== + +;; make funcsynopsis look pretty +(define %funcsynopsis-decoration% + ;; Decorate elements of a FuncSynopsis? + #t) + +;; use graphics in admonitions, and have their path be "." +;; NO: we are not yet ready to use gifs in TeX and so forth +(define %admon-graphics-path% + "./") +(define %admon-graphics% + #f) + +;; this is necessary because right now jadetex does not understand +;; symbolic entities, whereas things work well with numeric entities. +(declare-characteristic preserve-sdata? + "UNREGISTERED::James Clark//Characteristic::preserve-sdata?" + #f) +(define %two-side% #t) + +(define %section-autolabel% + ;; Are sections enumerated? + #t) +;; (define %title-font-family% +;; ;; The font family used in titles +;; "Ariel") +(define %visual-acuity% + ;; General measure of document text size + ;; "presbyopic" + ;; "large-type" + "presbyopic") + +(define %generate-part-toc% #t) + + +;;; The following customizations are from Tim Waugh's selfdocbook +;;; http://cyberelk.net/tim/docbook/ +;;; +;;; TeX backend can go to PS (where EPS is needed) +;;; or to PDF (where PNG is needed). So, just +;;; omit the file extension altogether and let +;;; tex/pdfjadetex sort it out on its own. +(define (graphic-file filename) + (let ((ext (file-extension filename))) + (if (or (equal? 'backend 'tex) ;; Leave off the extension for TeX + (not filename) + (not %graphic-default-extension%) + (member ext %graphic-extensions%)) + filename + (string-append filename "." %graphic-default-extension%)))) + +;;; Full justification. +(define %default-quadding% + 'justify) + +;;; To make URLs line wrap we use the TeX 'url' package. +;;; See also: jadetex.cfg +;; First we need to declare the 'formatting-instruction' flow class. +(declare-flow-object-class formatting-instruction +"UNREGISTERED::James Clark//Flow Object Class::formatting-instruction") +;; Then redefine ulink to use it. +(element ulink + (make sequence + (if (node-list-empty? (children (current-node))) + ; ulink url="...", /ulink + (make formatting-instruction + data: (string-append "\\url{" + (attribute-string (normalize "url")) + "}")) + (if (equal? (attribute-string (normalize "url")) + (data-of (current-node))) + ; ulink url="http://...", http://..., /ulink + (make formatting-instruction data: + (string-append "\\url{" + (attribute-string (normalize "url")) + "}")) + ; ulink url="http://...", some text, /ulink + (make sequence + ($charseq$) + (literal " (") + (make formatting-instruction data: + (string-append "\\url{" + (attribute-string (normalize "url")) + "}")) + (literal ")")))))) +;;; And redefine filename to use it too. +(element filename + (make formatting-instruction + data: (string-append "\\path{" (data-of (current-node)) "}"))) + + + + + + + + +;; If true (non-zero), elements of the FuncSynopsis will be decorated +;; (e.g. bold or italic). +(define %funcsynopsis-decoration% #t) + +;; If true, a Table of Contents will be generated for each 'Article'. +(define %generate-article-toc% #t) + +;; If true, a Table of Contents will be generated for each Part. +(define %generate-part-toc% #t) + +;; The name of the stylesheet to place in the HTML LINK TAG, +;; or #f to suppress the stylesheet LINK. +(define %stylesheet% "docbook.css") + +(define %use-id-as-filename% #t) + +(define %html-ext% ".html") + + + + + + + diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml index c78299e5e..439a22169 100644 --- a/winsup/doc/cygwinenv.sgml +++ b/winsup/doc/cygwinenv.sgml @@ -8,7 +8,7 @@ by prefixing with no . -(no)binmode - if set, non-disk +(no)binmode - if set, non-disk (e.g. pipe and COM ports) file opens default to binary mode (no CRLF translation) instead of text mode. Defaults to set (binary mode). By default, devices are opened in binary mode, so this option @@ -24,24 +24,24 @@ pipe to binary by default. always open in binary mode. -check_case:level - Controls the behaviour of +check_case:level - Controls the behaviour of Cygwin when a user tries to open or create a file using a case different from the case of the path as asved on the disk. level is one of relaxed, adjust and strict. -relaxed which is the default behaviour simply +relaxed which is the default behaviour simply ignores case. That's the default for native Windows applications as well. -adjust behaves mostly invisible. The POSIX input +adjust behaves mostly invisible. The POSIX input path is internally adjusted in case, so that the resulting DOS path uses the correct case throughout. You can see the result when changing the directory using a wrong case and calling /bin/pwd afterwards. -strict results in a error message if the case +strict results in a error message if the case isn't correct. Trying to open a file Foo while a file fOo exists results in a "no such file or directory" error. Trying to create a file BAR while a file @@ -52,7 +52,7 @@ case" error. -codepage:[ansi|oem] - Windows console +codepage:[ansi|oem] - Windows console applications can use different character sets (codepages) for drawing characters. The first setting, called "ansi", is the default. This character set contains various forms of latin characters used @@ -68,22 +68,33 @@ Cygwin, you can use this option to select an appropriate codepage. -(no)envcache - If set, environment variable +(no)envcache - If set, environment variable conversions (between Win32 and POSIX) are cached. Note that this is may cause problems if the mount table changes, as the cache is not invalidated and may contain values that depend on the previous mount table contents. Defaults to set. -(no)export - if set, the final values of these -settings are re-exported to the environment as $CYGWIN again. +(no)export - if set, the final values of these +settings are re-exported to the environment as CYGWIN again. +Defaults to off. -error_start:filepath - if set, runs filepath -when cygwin encounters a fatal error. This is useful for debugging. -filepath is usually set to the path to the gdb -program. -(no)glob[:ignorecase] - if set, command line arguments +error_start:filepath - if set, runs +filepath when cygwin encounters a fatal error. This is +useful for debugging. filepath is usually set to the path +to the gdb or dumper program. +There is no default set. + + +forkchunk:32768 - causes fork() +to copy memory some number of bytes at a time, in the above example +32768 bytes (32Kb) at a time. The default is to copy as many bytes as +possible, which is preferable in most cases but may slow some older systems +down. + + +(no)glob[:ignorecase] - if set, command line arguments containing UNIX-style file wildcard characters (brackets, question mark, asterisk, escaped with \) are expanded into lists of files that match those wildcards. @@ -93,40 +104,41 @@ Default is set. If supplied, wildcard matching is case insensitive. The default is noignorecase -(no)ntea - if set, use the full NT Extended +(no)ntea - if set, use the full NT Extended Attributes to store UNIX-like inode information. This option only operates under Windows NT. Defaults to not set. Warning! This may create additional large files on non-NTFS partitions. -(no)ntsec - if set, use the NT security +(no)ntsec - if set, use the NT security model to set UNIX-like permissions on files and processes. The file permissions can only be set on NTFS partitions. FAT doesn't -support the NT file security. For more information, read the documentation -in ntsec.sgml. +support the NT file security. Defaults to set. For more information, read +the documentation in . -(no)smbntsec - if set, use `ntsec' on remote +(no)smbntsec - if set, use ntsec on remote drives as well (this is the default). If you encounter problems with NT shares -or Samba drives, setting this to `nosmbntsec' could help. In that case the -permission and owner/group information is faked as on FAT partitions. -A reason for a non working ntsec on remote drives could be insufficient -permissions of the users. Since the needed user rights are somewhat dangerous -(SeRestorePrivilege) it's not always an option to grant that rights to users. -However, this shouldn't be a problem in NT domain environments. +or Samba drives, setting this to nosmbntsec could help. In that +case the permission and owner/group information is faked as on FAT partitions. +A reason for a non working ntsec on remote drives could be +insufficient permissions of the users. Since the needed user rights are +somewhat dangerous (SeRestorePrivilege) it's not always an option to grant that +rights to users. However, this shouldn't be a problem in NT domain +environments. -(no)reset_com - if set, serial ports are reset +(no)reset_com - if set, serial ports are reset to 9600-8-N-1 with no flow control when used. This is done at open time and when handles are inherited. Defaults to set. -(no)strip_title - if set, strips the directory +(no)strip_title - if set, strips the directory part off the window title, if any. Default is not set. -(no)title - if set, the title bar +(no)title - if set, the title bar reflects the name of the program currently running. Default is not set. Note that under Win9x the title bar is always enabled and it is stripped by default, but this is because of the way Win9x works. In @@ -134,7 +146,7 @@ order not to strip, specify title or title nostrip_title. -(no)tty - if set, Cygwin enables extra support +(no)tty - if set, Cygwin enables extra support (i.e., termios) for UNIX-like ttys. It is not compatible with some Windows programs. Defaults to not set, in which case the tty is opened in text mode @@ -144,7 +156,7 @@ This option must be specified before starting a Cygwin shell and it cannot be changed in the shell. -(no)winsymlinks - if set, Cygwin creates +(no)winsymlinks - if set, Cygwin creates symlinks as Windows shortcuts with a special header and the R/O attribute set. If not set, Cygwin creates symlinks as plain files with a magic number, a path and the system attribute set. Defaults to set. diff --git a/winsup/doc/dll.sgml b/winsup/doc/dll.sgml index 7bb10829c..a44129b3c 100644 --- a/winsup/doc/dll.sgml +++ b/winsup/doc/dll.sgml @@ -91,13 +91,21 @@ you will probably want to use the complete syntax: -Wl,--out-implib=lib${module}.dll.a \ -Wl,--export-all-symbols \ -Wl,--enable-auto-import \ - -Wl,--whole-archive ${old_lib} \ + -Wl,--whole-archive ${old_libs} \ -Wl,--no-whole-archive ${dependency_libs} -Where ${module} is the name of your DLL, ${old_lib} are all + +The name of your library is ${module}, prefixed with +cyg for the DLL and lib for the +import library. Cygwin DLLs use the cyg prefix to +differentiate them from native-Windows MinGW DLLs, see +the MinGW website for more details. +${old_libs} are all your object files, bundled together in static libs or single object -files and the ${dependency_libs} are import libs you need to -link against, e.g '-lpng -lz -L/usr/local/special -lmyspeciallib'. +files and the ${dependency_libs} are import libs you +need to link against, e.g +'-lpng -lz -L/usr/local/special -lmyspeciallib'. + Linking Against DLLs diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml index d6c2d9ad9..59ab01ffb 100644 --- a/winsup/doc/effectively.sgml +++ b/winsup/doc/effectively.sgml @@ -83,7 +83,7 @@ Windows programs, use a DOS prompt, running only the occasional Cygwin command or script. Next would be to run bash with the default DOS box. To make Cygwin more Unix compatible in this case, set CYGWIN=tty (see ). -Alternatively, the optional rxvt package provides +Alternatively, the optional rxvt package provides a native-Windows version of the popular X11 terminal emulator (it is not necessary to set CYGWIN=tty with rxvt). Using rxvt.exe provides the most Unix-like environment, @@ -94,14 +94,15 @@ but expect some compatibility problems with Windows programs. Cygwin and Windows Networking -Many popular Cygwin packages, such as ncftp, -lynx, and wget, require a +Many popular Cygwin packages, such as ncftp, +lynx, and wget, 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 ping.exe, 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 +If you chose to install the inetutils package, +you may have both Windows and Cygwin versions of utilities such as ftp and telnet. If you are having problems using one of these programs, see if the alternate one works as expected. @@ -127,10 +128,10 @@ programs in your environment. The cygutils package -The optional cygutils package contains miscellaneous tools that are +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 -setup.exe. Several of the cygutils tools are useful +setup.exe. Several of the cygutils tools are useful for interacting with Windows. @@ -138,7 +139,7 @@ for interacting with Windows. One of the hassles of Unix-Windows interoperability is the different line endings on text files. As mentioned in , Unix tools such as tr can convert between CRLF and LF -endings, but cygutils provides several dedicated programs: +endings, but cygutils provides several dedicated programs: conv, d2u, dos2unix, u2d, and unix2dos. Use the --help switch for usage information. @@ -153,7 +154,8 @@ 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 mkshortcut +etc. The cygutils package includes a +mkshortcut utility for creating standard Microsoft .lnk files. @@ -172,8 +174,8 @@ Windows shortcuts. Printing with cygutils There are several options for printing from Cygwin, including the -lpr found in cygutils (not to be confused with the -native Windows lpr.exe). The easiest way to use cygutils' +lpr found in cygutils (not to be confused with the +native Windows lpr.exe). The easiest way to use cygutils' lpr is to specify a default device name in the PRINTER environment variable. You may also specify a device on the command line with the -d or -P @@ -194,8 +196,9 @@ the backslash as an escape character. lpr 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 -a2ps and enscript can prepare text -files for printing. The ghostscript package also provides some translation +a2ps and enscript 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, gsprint, is available from the Ghostscript diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo index d54ec3d4e..3ec161e75 100644 --- a/winsup/doc/how-programming.texinfo +++ b/winsup/doc/how-programming.texinfo @@ -576,6 +576,18 @@ Unix emulation environment and defining _WIN32 confuses some programs which think that they have to make special concessions for a Windows environment which Cygwin handles automatically. +Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to +tell which compiler (or settings) you're running. +Check this out in detail by running, for example + +@example + $ gcc -dM -E -xc /dev/null >gcc.txt + $ gcc -mno-cygwin -dM -E -xc /dev/null >gcc-mno-cygwin.txt + $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt +@end example +Then use the diff and grep utilities to check +what the difference is. + @subsection How should I port my Unix GUI to Windows? There are two basic strategies for porting Unix GUIs to Windows. diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml index 13441e995..56a5f7d69 100644 --- a/winsup/doc/pathnames.sgml +++ b/winsup/doc/pathnames.sgml @@ -292,6 +292,30 @@ when needed. +The /proc filesystem + +Cygwin, like Linux and other similar operating systems, supports the +/proc virtual filesystem. The files in this +directory are representations of various aspects of your system, +for example the command cat /proc/cpuinfo +displays information such as what model and speed processor you have. + + +One unique aspect of the Cygwin /proc filesystem +is /proc/registry, which displays the Windows +registry with each KEY as a directory and each +VALUE as a file. As anytime you deal with the +Windows registry, use caution since changes may result in an unstable +or broken system. + + +The Cygwin /proc is not as complete as the +one in Linux, but it provides significant capabilities. The +procps package contains several utilities +that use it. + + + The @pathnames To circumvent the limitations on shell line length in the native Windows command shells, Cygwin programs expand their arguments diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml index c9b692712..a01472898 100644 --- a/winsup/doc/setup-net.sgml +++ b/winsup/doc/setup-net.sgml @@ -3,7 +3,7 @@ Internet Setup To install the Cygwin net release, go to http://cygwin.com/ and click on "Install Cygwin Now!". This will +URL="http://cygwin.com/setup.exe">"Install Cygwin Now!". This will download a GUI installer called setup.exe which can be run to download a complete cygwin installation via the internet. Follow the instructions on each screen to install Cygwin. @@ -141,9 +141,9 @@ For each selected mirror site, setup.exe downloads a small text file called setup.bz2 that contains a list of packages available from that site along with some basic information about each package which setup.exe parses and uses to create the -chooser window. For details about the format of this file, see - -http://sources.redhat.com/cygwin-apps/setup.html. +chooser window. For details about the format of this file, see +the +setup.exe homepage. The chooser is the most complex part of setup.exe. @@ -155,7 +155,10 @@ will install only the packages in the Base category and their dependencies, resulting in a minimal Cygwin installation. However, this will not include many commonly used tools such as gcc (which you will find in the Devel -category). +category). Since setup.exe automatically selects +dependencies, be careful not to unselect any required packages. In +particular, everything in the Base category is +required. You can change setup.exe's view style, which is helpful @@ -191,7 +194,8 @@ though mirrors have at least one previous version and occasionally there is a testing or beta version of a package available. To see these package, click on the Prev or Exp radio button. Be warned, however, that the next time you run setup.exe -it will try to replace old or experimental versions with the latest. +it will try to replace old or experimental versions with the current +stable version. -- cgit v1.2.3