From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 115298 invoked by alias); 15 Jun 2015 12:37:36 -0000 Mailing-List: contact cygwin-patches-help@cygwin.com; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Post: List-Archive: List-Help: , Sender: cygwin-patches-owner@cygwin.com Mail-Followup-To: cygwin-patches@cygwin.com Received: (qmail 115285 invoked by uid 89); 15 Jun 2015 12:37:35 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=0.4 required=5.0 tests=AWL,BAYES_50,KAM_LAZY_DOMAIN_SECURITY,RCVD_IN_DNSWL_NONE autolearn=no version=3.3.2 X-HELO: rgout06.bt.lon5.cpcloud.co.uk Received: from rgout06.bt.lon5.cpcloud.co.uk (HELO rgout06.bt.lon5.cpcloud.co.uk) (65.20.0.183) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 15 Jun 2015 12:37:10 +0000 X-OWM-Source-IP: 86.141.128.210(GB) X-OWM-Env-Sender: jonturney@btinternet.com X-CTCH-RefID: str=0001.0A090201.557EC6F3.0084,ss=1,re=0.000,recu=0.000,reip=0.000,cl=1,cld=1,fgs=0 X-Junkmail-Premium-Raw: score=27/50,refid=2.7.2:2015.6.15.101816:17:27.888,ip=86.141.128.210,rules=__HAS_FROM, __TO_MALFORMED_2, __TO_NO_NAME, __SUBJ_ALPHA_END, __HAS_MSGID, __SANE_MSGID, __HAS_X_MAILER, __IN_REP_TO, __REFERENCES, __ANY_URI, __URI_NO_WWW, __URI_NO_PATH, __FRAUD_CONTACT_NAME, __SUBJ_ALPHA_NEGATE, BODY_SIZE_10000_PLUS, __MIME_TEXT_ONLY, RDNS_GENERIC_POOLED, __URI_NS, SXL_IP_DYNAMIC[210.128.141.86.fur], HTML_00_01, HTML_00_10, RDNS_SUSP_GENERIC, RDNS_SUSP, REFERENCES X-CTCH-Spam: Unknown Received: from localhost.localdomain (86.141.128.210) by rgout06.bt.lon5.cpcloud.co.uk (8.6.122.06) (authenticated as jonturney@btinternet.com) id 557EACF60005043F; Mon, 15 Jun 2015 13:37:07 +0100 From: Jon TURNEY To: cygwin-patches@cygwin.com Cc: Jon TURNEY Subject: [PATCH 5/8] winsup/doc: Convert utils.xml to using refentry Date: Mon, 15 Jun 2015 12:37:00 -0000 Message-Id: <1434371793-3980-6-git-send-email-jon.turney@dronecode.org.uk> In-Reply-To: <1434371793-3980-1-git-send-email-jon.turney@dronecode.org.uk> References: <1434371793-3980-1-git-send-email-jon.turney@dronecode.org.uk> X-SW-Source: 2015-q2/txt/msg00061.txt.bz2 Convert utils.xml from using a sect2 to using a refentry for each utility program. Unfortunately, using refentry seems to tickle a bug in dblatex when generating pdf, which appears to not escape \ properly in the latex for refentry, so use fop instead. Note that the chunked html now generates a page for each utility, rather than one containing all utilities. A small customization to TOC generation for HTML and PDF is needed to ensure that it appears as before, containing an entry for each utility command. Future work: synopsis and options sections could use more detailed markup than just wrapping the whole thing in 2015-06-12 Jon Turney * Makefile.in (XMLTO): Switch from dblatex to fop. * utils.xml : Convert from using a sect2 to using a refentry for each utility program. * cygwin.xsl: Customize autotoc to include refentries. * fo.xsl: Ditto. Signed-off-by: Jon TURNEY --- winsup/doc/ChangeLog | 8 + winsup/doc/Makefile.in | 2 +- winsup/doc/cygwin.xsl | 13 + winsup/doc/fo.xsl | 36 +++ winsup/doc/utils.xml | 778 ++++++++++++++++++++++++++++++++++++------------- 5 files changed, 627 insertions(+), 210 deletions(-) diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index a73326a..7b15a5d 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,5 +1,13 @@ 2015-06-12 Jon Turney + * Makefile.in (XMLTO): Switch from dblatex to fop. + * utils.xml : Convert from using a sect2 to using a refentry for + each utility program. + * cygwin.xsl: Customize autotoc to include refentries. + * fo.xsl: Ditto. + +2015-06-12 Jon Turney + * Makefile.in (cygwin-ug-net/cygwin-ug-net.pdf) (cygwin-api/cygwin-api.pdf): Use fo.xsl to customized DocBook XML->PDF conversion. diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in index 2d71728..bcc32e4 100644 --- a/winsup/doc/Makefile.in +++ b/winsup/doc/Makefile.in @@ -25,7 +25,7 @@ MKDIRP:=$(INSTALL) -m 755 -d CC:=@CC@ CC_FOR_TARGET:=@CC@ -XMLTO:=xmlto --skip-validation --with-dblatex +XMLTO:=xmlto --skip-validation --with-fop include $(srcdir)/../Makefile.common diff --git a/winsup/doc/cygwin.xsl b/winsup/doc/cygwin.xsl index 99ec5d0..df12555 100644 --- a/winsup/doc/cygwin.xsl +++ b/winsup/doc/cygwin.xsl @@ -10,4 +10,17 @@ + + + + + + + + + + + + diff --git a/winsup/doc/fo.xsl b/winsup/doc/fo.xsl index 4bc255c..ba8e191 100644 --- a/winsup/doc/fo.xsl +++ b/winsup/doc/fo.xsl @@ -29,4 +29,40 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml index fcecd11..a3d7da8 100644 --- a/winsup/doc/utils.xml +++ b/winsup/doc/utils.xml @@ -13,10 +13,20 @@ identically. All of the Cygwin command-line utilities support the --help and --version options. - - cygcheck - - + + + cygcheck + 1 + Cygwin Utilities + + + + cygcheck + List system information, check installed packages, or query package database + + + + Usage: cygcheck [-v] [-h] PROGRAM cygcheck -c [-d] [PACKAGE] cygcheck -s [-r] [-v] [-h] @@ -29,9 +39,12 @@ Usage: cygcheck [-v] [-h] PROGRAM cygcheck --disable-unique-object-names Cygwin-DLL cygcheck --show-unique-object-names Cygwin-DLL cygcheck -h + + -List system information, check installed packages, or query package database. - + + Options + At least one command option or a PROGRAM is required, as shown above. PROGRAM list library (DLL) dependencies of PROGRAM @@ -68,7 +81,10 @@ Note: -c, -f, and -l only report on packages that are currently installed. To search all official Cygwin packages use -p instead. The -p REGEXP matches package names, descriptions, and names of files/paths within all packages. + + + Description The cygcheck program is a diagnostic utility for dealing with Cygwin programs. If you are familiar with dpkg or rpm, @@ -257,20 +273,34 @@ are unable to find another Cygwin DLL. and --enable-... options, the --show-unique-object-names option also works for Cygwin DLLs which are currently in use. + - + - - cygpath + + + cygpath + 1 + Cygwin Utilities + + + cygpath + Convert Unix and Windows format paths, or output system path information + + + Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME... cygpath [-c HANDLE] cygpath [-ADHOPSW] cygpath [-F ID] + + -Convert Unix and Windows format paths, or output system path information - + + Options + Output type options: -d, --dos print DOS (short) form of NAMEs (C:\PROGRA~1\) @@ -312,7 +342,10 @@ Other options: -h, --help output usage information and exit -V, --version output version information and exit + + + Description The cygpath program is a utility that converts Windows native filenames to Cygwin POSIX-style pathnames and vice versa. It can be used when a Cygwin program needs to pass a file name to a @@ -417,23 +450,39 @@ explorer $XPATH & (CDBurn area). By default the output is in UNIX (POSIX) format; use the -w or -d options to get other formats. - - - - - dumper - - + + + + + + dumper + 1 + Cygwin Utilities + + + + dumper + Dump core from WIN32PID to FILENAME.core + + + + Usage: dumper [OPTION] FILENAME WIN32PID + + -Dump core from WIN32PID to FILENAME.core - + + Options + -d, --verbose be verbose while dumping -h, --help output help information and exit -q, --quiet be quiet while dumping (default) -V, --version output version information and exit + + + Description The dumper utility can be used to create a core dump of running Windows process. This core dump can be later loaded to gdb and analyzed. One common way to use @@ -461,18 +510,31 @@ error_start=x:\path\to\dumper.exe dump on one machine and try to debug it on another, you'll need to place identical copies of the executable and dlls in the same directories as on the machine where the core dump was created. - - - - - getconf - - + + + + + + getconf + 1 + Cygwin Utilities + + + + getconf + Get configuration values + + + + Usage: getconf [-v specification] variable_name [pathname] getconf -a [pathname] + + -Get configuration values - + + Options + -v specification Indicate specific version for which configuration values shall be fetched. -a, --all Print all known configuration values @@ -482,7 +544,10 @@ Other options: -h, --help This text -V, --version Print program version and exit + + + Description The getconf utility prints the value of the configuration variable specified by variable_name. If no pathname is given, getconf @@ -509,17 +574,30 @@ Other options: Use the -a option to print a list of all available configuration variables for the system, or given pathname, and their values. - - - - - getfacl - - + + + + + + getfacl + 1 + Cygwin Utilities + + + + getfacl + Display file and directory access control lists (ACLs) + + + + Usage: getfacl [-adn] FILE [FILE2...] + + -Display file and directory access control lists (ACLs). - + + Options + -a, --access display the file access control list -d, --default display the default access control list -h, --help print help explaining the command line options @@ -529,7 +607,10 @@ Display file and directory access control lists (ACLs). When multiple files are specified on the command line, a blank line separates the ACLs for each file. + + + Description For each argument that is a regular file, special file or directory, getfacl displays the owner, the group, and the ACL. For directories getfacl displays additionally the @@ -558,24 +639,41 @@ line separates the ACLs for each file. default:other:perm - - - - kill - - + + + + + + kill + 1 + Cygwin Utilities + + + + kill + Send signals to processes + + + + Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...] kill -l [signal] + + -Send signals to processes - + + Options + -f, --force force, using win32 interface if necessary -l, --list print a list of signal names -s, --signal send signal (use kill --list for a list) -h, --help output usage information and exit -V, --version output version information and exit + + + Description The kill program allows you to send arbitrary signals to other Cygwin programs. The usual purpose is to end a running program from some other window when ^C won't work, but you can also send @@ -658,17 +756,30 @@ SIGPWR 29 power failure SIGUSR1 30 user defined signal 1 SIGUSR2 31 user defined signal 2 - - - - - ldd - - + + + + + + ldd + 1 + Cygwin Utilities + + + + ldd + Print shared library dependencies + + + + Usage: ldd [OPTION]... FILE... + + -Print shared library dependencies - + + Options + -h, --help print this help and exit -V, --version print version information and exit -r, --function-relocs process data and function relocations @@ -678,23 +789,39 @@ Print shared library dependencies -v, --verbose print all information (currently unimplemented) + + + Description ldd prints the shared libraries (DLLs) an executable or DLL is linked against. No modifying option is implemented yet. - - - - - locale - - + + + + + + locale + 1 + Cygwin Utilities + + + + locale + Get locale-specific information + + + + Usage: locale [-amvhV] or: locale [-ck] NAME or: locale [-usfnU] + + -Get locale-specific information. - + + Options + System information: -a, --all-locales List all available supported locales @@ -720,7 +847,10 @@ Other options: -h, --help This text -V, --version Print program version and exit + + + Description locale without parameters prints information about the current locale environment settings. @@ -830,17 +960,31 @@ nostr="no" messages-codeset="UTF-8" bash$ locale noexpr ^[nN] - - - - - minidumper - - + + + + + + + minidumper + 1 + Cygwin Utilities + + + + minidumper + Write minidump from WIN32PID to FILENAME.dmp + + + + Usage: minidumper [OPTION] FILENAME WIN32PID + + -Write minidump from WIN32PID to FILENAME.dmp - + + Options + -t, --type minidump type flags -n, --nokill don't terminate the dumped process -d, --verbose be verbose while dumping @@ -848,7 +992,10 @@ Write minidump from WIN32PID to FILENAME.dmp -q, --quiet be quiet while dumping (default) -V, --version output version information and exit + + + Description The minidumper utility can be used to create a minidump of a running Windows process. This minidump can be later @@ -867,20 +1014,30 @@ Write minidump from WIN32PID to FILENAME.dmp dumper the target process is terminated after dumping unless the -n option is given. - - - - - mkgroup - - + + + + + + mkgroup + 1 + Cygwin Utilities + + + + mkgroup + Write /etc/group-like output to stdout + + + + Usage: mkgroup [OPTION]... + + -Write /etc/group-like output to stdout - -Don't use this command to generate a local /etc/group file, unless you -really need one. See the Cygwin User's Guide for more information. - + + Options + Options: -l,--local [machine] Print local group accounts of \"machine\", @@ -907,6 +1064,13 @@ Options: Default is to print local groups on stand-alone machines, plus domain groups on domain controllers and domain member machines. + + + + Description + Don't use this command to generate a local /etc/group file, unless you + really need one. See the Cygwin User's Guide for more information. + The mkgroup program can be used to create a local /etc/group file. Cygwin doesn't need this file, @@ -954,21 +1118,31 @@ groups on domain controllers and domain member machines. samba-server or -L samba-server. The normal UNIX groups are usually not enumerated, but they can show up as a group in ls -l output. - - - - - mkpasswd - - + + + + + + mkpasswd + 1 + Cygwin Utilities + + + + mkpasswd + Write /etc/passwd-like output to stdout + + + + Usage: mkpasswd [OPTIONS]... + + -Write /etc/passwd-like output to stdout - -Don't use this command to generate a local /etc/passwd file, unless you -really need one. See the Cygwin User's Guide for more information. - -Options: + + Options + + Options: -l,--local [machine] Print local user accounts of \"machine\", from local machine if no machine specified. @@ -997,6 +1171,12 @@ Options: Default is to print local accounts on stand-alone machines, domain accounts on domain controllers and domain member machines. + + + + Description + Don't use this command to generate a local /etc/passwd file, unless you + really need one. See the Cygwin User's Guide for more information. The mkpasswd program can be used to create a /etc/passwd file. Cygwin doesn't need this file, @@ -1044,19 +1224,32 @@ on domain controllers and domain member machines. samba-server. The normal UNIX users are usually not enumerated, but they can show up as file owners in ls -l output. - - - - - mount - - + + + + + + mount + 1 + Cygwin Utilities + + + + mount + Display information about mounted filesystems, or mount a filesystem + + + + Usage: mount [OPTION] [<win32path> <posixpath>] mount -a mount <posixpath> + + -Display information about mounted filesystems, or mount a filesystem - + + Options + -a, --all mount all filesystems mentioned in fstab -c, --change-cygdrive-prefix change the cygdrive path prefix to <posixpath> -f, --force force mount, don't warn about missing mount @@ -1068,7 +1261,10 @@ Display information about mounted filesystems, or mount a filesystem -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix -V, --version output version information and exit + + + Description The mount program is used to map your drives and shares onto Cygwin's simulated POSIX directory tree, much like as is done by mount commands on typical UNIX systems. However, in contrast to mount @@ -1080,7 +1276,7 @@ Display information about mounted filesystems, or mount a filesystem the Cygwin POSIX file system and strategies for using mounts. To remove mounts temporarily, use umount - + Using mount If you just type mount with no parameters, it @@ -1225,9 +1421,9 @@ D: on /d type fat (binary,user,noumount) /etc/fstab to restore the old state. It also makes moving your settings to a different machine much easier. - + - + Cygdrive mount points Whenever Cygwin cannot use any of the existing mounts to convert @@ -1266,9 +1462,9 @@ D: on /d type fat (binary,user,noumount) - + - + Limitations Limitations: there is a hard-coded limit of 64 mount points (up to @@ -1295,18 +1491,31 @@ D: on /d type fat (binary,user,noumount) or echo * command and find . will not find mtpt. - + + + - + + + passwd + 1 + Cygwin Utilities + - - passwd + + passwd + Change USER's password or password attributes. + - + + Usage: passwd [OPTION] [USER] + + -Change USER's password or password attributes. - + + Options + User operations: -l, --lock lock USER's account. -u, --unlock unlock USER's account. @@ -1348,7 +1557,10 @@ Don't use this feature if you don't need network access within a remote session. You can delete your stored password by using `passwd -R' and specifying an empty password. + + + Description passwd changes passwords for user accounts. A normal user may only change the password for their own account, but administrators may change passwords on any account. @@ -1441,35 +1653,64 @@ specifying an empty password. Limitations: Users may not be able to change their password on some systems. - - - - - pldd - - + + + + + + pldd + 1 + Cygwin Utilities + + + + pldd + List dynamic shared objects loaded into a process + + + + Usage: pldd [OPTION...] PID + + -List dynamic shared objects loaded into a process. - + + Options + -?, --help Give this help list --usage Give a short usage message -V, --version Print program version + + + Description pldd prints the shared libraries (DLLs) loaded by the process with the given PID. - - - - - ps - - + + + + + + ps + 1 + Cygwin Utilities + + + + ps + Report process status + + + + Usage: ps [-aefls] [-u UID] + + -Report process status - + + Options + -a, --all show processes of all users -e, --everyone show processes of all users -f, --full show process uids, ppids @@ -1482,7 +1723,10 @@ Report process status -W, --windows show windows as well as cygwin processes With no options, ps outputs the long format by default + + + Description The ps program gives the status of all the Cygwin processes running on the system (ps = "process status"). Due to the limitations of simulating a POSIX environment under Windows, there is @@ -1516,17 +1760,30 @@ With no options, ps outputs the long format by default non-Cygwin Windows processes as well as Cygwin processes. The WINPID is also the PID, and they can be killed with the Cygwin kill command's -f option. - - - - - regtool - - + + + + + + regtool + 1 + Cygwin Utilities + + + + regtool + View or edit the Windows registry + + + + Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY + + -View or edit the Win32 registry - + + Options + Actions: add KEY\SUBKEY add new SUBKEY @@ -1594,7 +1851,10 @@ You can use forward slash ('/') as a separator instead of backslash, in that case backslash is treated as escape character Example: regtool get '\user\software\Microsoft\Clock\iFormat' + + + Description The regtool program allows shell scripts to access and modify the Windows registry. Note that modifying the Windows registry is dangerous, and carelessness here can result in an unusable system. Be @@ -1690,19 +1950,31 @@ Example: regtool get '\user\software\Microsoft\Clock\iFormat' By default, the last "\" or "/" is assumed to be the separator between the key and the value. You can use the -K option to provide an alternate key/value separator character. - - - - - setfacl - - + + + + + + setfacl + 1 + Cygwin Utilities + + + + setfacl + Modify file and directory access control lists (ACLs) + + + + Usage: setfacl [-r] {-f ACL_FILE | -s acl_entries} FILE... setfacl [-r] {-b|[-d acl_entries] [-m acl_entries]} FILE... + + - -Modify file and directory access control lists (ACLs) - + + Options + -b, --remove-all remove all extended ACL entries -d, --delete delete one or more specified ACL entries -f, --file set ACL entries for FILE to ACL entries read @@ -1719,7 +1991,10 @@ Modify file and directory access control lists (ACLs) At least one of (-b, -d, -f, -k, -m, -s) must be specified + + + Description For each file given as parameter, setfacl will either replace its complete ACL (-s, -f), or it will add, modify, or delete ACL entries. @@ -1811,17 +2086,32 @@ $ getfacl source_file | setfacl -f - target_file directory that contains default ACL entries will have permissions according to the combination of the current umask, the explicit permissions requested and the default ACL entries - - - - setmetamode - - + + + + + + setmetamode + 1 + Cygwin Utilities + + + + setmetamode + Get or set keyboard meta mode + + + + Usage: setmetamode [metabit|escprefix] + + -Get or set keyboard meta mode - + + Options + Without argument, it shows the current meta key mode. + metabit|meta|bit The meta key sets the top bit of the character. escprefix|esc|prefix The meta key sends an escape prefix. @@ -1830,20 +2120,36 @@ Other options: -h, --help This text -V, --version Print program version and exit + + + Description setmetamode can be used to determine and set the key code sent by the meta (aka Alt) key. - - - - - ssp - - + + + + + + ssp + 1 + Cygwin Utilities + + + + ssp + Single-step profile COMMAND + + + + Usage: ssp [options] low_pc high_pc command... + + -Single-step profile COMMAND - + + Options + -c, --console-trace trace every EIP value to the console. *Lots* slower. -d, --disable disable single-stepping by default; use OutputDebugString ("ssp on") to enable stepping @@ -1861,7 +2167,10 @@ Single-step profile COMMAND Example: ssp 0x401000 0x403000 hello.exe + + + Description SSP - The Single Step Profiler Original Author: DJ Delorie @@ -1991,17 +2300,31 @@ Each sample counts as 0.01 seconds. $ ssp -v -s -l -d 0x61001000 0x61080000 hello.exe - - - - strace - - + + + + + + strace + 1 + Cygwin Utilities + + + + strace + Trace system calls and signals + + + + Usage: strace [OPTIONS] <command-line> Usage: strace [OPTIONS] -p <pid> + + -Trace system calls and signals - + + Options + -b, --buffer-size=SIZE set size of output file buffer -d, --no-delta don't display the delta-t microsecond timestamp -e, --events log all Windows DEBUG_EVENTS (toggle - default true) @@ -2052,7 +2375,10 @@ Trace system calls and signals special 0x100000 (_STRACE_SPECIAL) Special debugging printfs for non-checked-in code + + + Description The strace program executes a program, and optionally the children of the program, reporting any Cygwin DLL output from the program(s) to stdout, or to a file with the @@ -2069,51 +2395,84 @@ $ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' &am cygcheck). As a result it does not understand symlinks. This program is mainly useful for debugging the Cygwin DLL itself. - - - - - tzset - - + + + + + + tzset + 1 + Cygwin Utilities + + + + tzset + Print POSIX-compatible timezone ID from current Windows timezone setting + + + + Usage: tzset [OPTION] + + -Print POSIX-compatible timezone ID from current Windows timezone setting - + + Options + Options: -h, --help output usage information and exit. -V, --version output version information and exit. + + -Use tzset to set your TZ variable. In POSIX-compatible shells like bash, -dash, mksh, or zsh: - - export TZ=$(tzset) - -In csh-compatible shells like tcsh: - - setenv TZ `tzset` - + + Description + Use tzset to set your TZ variable. In POSIX-compatible shells like bash, + dash, mksh, or zsh: + +export TZ=$(tzset) + + In csh-compatible shells like tcsh: + +setenv TZ `tzset` + The tzset tool reads the current timezone from Windows and generates a POSIX-compatible timezone information for the TZ environment variable from that information. That's all there is to it. For the way how to use it, see the above usage information. - - - - - umount - - + + + + + + umount + 1 + Cygwin Utilities + + + + umount + Unmount filesystems + + + + Usage: umount [OPTION] [<posixpath>] + + -Unmount filesystems - + + Options + -h, --help output usage information and exit -U, --remove-user-mounts remove all user mounts -V, --version output version information and exit + + + Description The umount program removes mounts from the mount table in the current session. If you specify a POSIX path that corresponds to a current mount point, umount will @@ -2123,6 +2482,7 @@ Unmount filesystems See in the Cygwin User's Guide for more information on the mount table. - + + -- 2.1.4