From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from re-prd-fep-042.btinternet.com (mailomta23-re.btinternet.com [213.120.69.116]) by sourceware.org (Postfix) with ESMTPS id CC4463985456 for ; Wed, 16 Jun 2021 16:20:16 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org CC4463985456 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=dronecode.org.uk Authentication-Results: sourceware.org; spf=none smtp.mailfrom=dronecode.org.uk Received: from re-prd-rgout-002.btmx-prd.synchronoss.net ([10.2.54.5]) by re-prd-fep-042.btinternet.com with ESMTP id <20210616162016.OAUD11727.re-prd-fep-042.btinternet.com@re-prd-rgout-002.btmx-prd.synchronoss.net>; Wed, 16 Jun 2021 17:20:16 +0100 Authentication-Results: btinternet.com; none X-SNCR-Rigid: 5ED9C0CC37B36E4E X-Originating-IP: [86.139.156.26] X-OWM-Source-IP: 86.139.156.26 (GB) X-OWM-Env-Sender: jonturney@btinternet.com X-VadeSecure-score: verdict=clean score=0/300, class=clean X-RazorGate-Vade: gggruggvucftvghtrhhoucdtuddrgeduledrfedvledgleekucetufdoteggodetrfdotffvucfrrhhofhhilhgvmecuueftkffvkffujffvgffngfevqffopdfqfgfvnecuuegrihhlohhuthemuceftddunecunecujfgurhephffvufffkffojghfggfgsedtkeertdertddtnecuhfhrohhmpeflohhnucfvuhhrnhgvhicuoehjohhnrdhtuhhrnhgvhiesughrohhnvggtohguvgdrohhrghdruhhkqeenucggtffrrghtthgvrhhnpeefieduveehgfffffeuueehleefgeevfedvffeljeefheduteelteelvdettefhvdenucfkphepkeeirddufeelrdduheeirddvieenucevlhhushhtvghrufhiiigvpedunecurfgrrhgrmhephhgvlhhopehlohgtrghlhhhoshhtrdhlohgtrghlughomhgrihhnpdhinhgvthepkeeirddufeelrdduheeirddviedpmhgrihhlfhhrohhmpeeojhhonhdrthhurhhnvgihsegurhhonhgvtghouggvrdhorhhgrdhukheqpdhrtghpthhtohepoegthihgfihinhdqphgrthgthhgvshestgihghifihhnrdgtohhmqedprhgtphhtthhopeeojhhonhdrthhurhhnvgihsegurhhonhgvtghouggvrdhorhhgrdhukheq X-RazorGate-Vade-Verdict: clean 0 X-RazorGate-Vade-Classification: clean Received: from localhost.localdomain (86.139.156.26) by re-prd-rgout-002.btmx-prd.synchronoss.net (5.8.340) (authenticated as jonturney@btinternet.com) id 5ED9C0CC37B36E4E; Wed, 16 Jun 2021 17:20:16 +0100 From: Jon Turney To: cygwin-patches@cygwin.com Cc: Jon Turney Subject: [PATCH 2/2] Cygwin: Use cmdsynopsis element in utils documentation Date: Wed, 16 Jun 2021 17:19:18 +0100 Message-Id: <20210616161918.41015-3-jon.turney@dronecode.org.uk> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210616161918.41015-1-jon.turney@dronecode.org.uk> References: <20210616161918.41015-1-jon.turney@dronecode.org.uk> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-1198.7 required=5.0 tests=BAYES_00, FORGED_SPF_HELO, GIT_PATCH_0, KAM_DMARC_STATUS, KAM_LAZY_DOMAIN_SECURITY, RCVD_IN_BARRACUDACENTRAL, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_PASS, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: cygwin-patches@cygwin.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Cygwin core component patch submission and discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 16 Jun 2021 16:20:19 -0000 Use element markup in utils docbook documentation, rather than some preformatted text inside . (This didn't happen as part of 646745cb, when we first started using refentry elements to make it possible to generate manpages) This helps produce better looking manpages: * uses bold (for command names) and italic (for replaceable items) * different output formats inconsistently treat tabs inside (so we have to be careful to not use them in that preformatted text) Also clean up various issues: * Replace '[OPTIONS]' with a real synopsis of the options * Consistently use 'ITEM...' rather than 'ITEM1 [ITEM2...]' for an item which should appear 1 or more times (cygcheck -f, getfacl, kill) * Consistently document the '-h | -V' invocation form * Since replaceable items are now marked up so they have some formatting indicating they are replaceable, we can drop wrapping them in angle brackets, as is done in some places * Add missing '-W' and '-p PID' options to ps synopsis * Adjust cygpath synopsis to show that only one 'System information' option is allowed, possibly modified by -A Future work: * Sync up the actual help emitted by the util, where it's been improved * Also don't use for formatting 'OPTIONS' section of manpage * pldd inconsistently uses '-?' rather than '-h'! --- winsup/doc/utils.xml | 658 +++++++++++++++++++++++++++++++++++++------ 1 file changed, 567 insertions(+), 91 deletions(-) diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml index 55594ef5f..1d9b8488c 100644 --- a/winsup/doc/utils.xml +++ b/winsup/doc/utils.xml @@ -26,9 +26,26 @@ - -chattr [-RVfHv] [+-=mode]... [file]... - + + chattr + -RVf + + + + + - + = + + MODE + + FILE + + + chattr + + -H + -v + + @@ -91,17 +108,54 @@ chattr [-RVfHv] [+-=mode]... [file]... - -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 -h - + + cygcheck + -v + -h + PROGRAM + + + cygcheck + -c + -d + PACKAGE + + + cygcheck + -s + -r + -v + -h + + + cygcheck + -k + + + cygcheck + -f + FILE + + + cygcheck + -l + PACKAGE + + + cygcheck + -p REGEXP + + + cygcheck + --delete-orphaned-installation-keys + + + cygcheck + + -h + -V + + @@ -302,12 +356,44 @@ coreutils-5.3.0-6 GNU core utilities (includes fileutils, sh-utils and t - -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 + -i + CONVERSION_OPTION + NAME + + + cygpath + -c HANDLE + + + cygpath + -A + + -D + -H + -O + -P + -S + -W + -F ID + + + + cygpath + + -h + -V + + @@ -489,9 +575,21 @@ explorer $XPATH & - -dumper [OPTION] FILENAME WIN32PID - + + dumper + -n + -d + -q + FILENAME + WIN32PID + + + dumper + + -h + -V + + @@ -553,10 +651,24 @@ error_start=x:\path\to\dumper.exe - -getconf [-v specification] variable_name [pathname] -getconf -a [pathname] - + + getconf + -v specification + variable_name + pathname + + + getconf + -a + pathname + + + getconf + + -h + -V + + @@ -617,9 +729,18 @@ Other options: - -getfacl [-adceEn] FILE [FILE2...] - + + getfacl + -adceEn + FILE + + + getfacl + + -h + -V + + @@ -685,10 +806,26 @@ line separates the ACLs for each file. - -kill [-f] [-signal] [-s signal] pid1 [pid2 ...] -kill -l [signal] - + + kill + -f + -signal + -s signal + pid + + + kill + -l + signal + + + kill + + -h + -V + + + @@ -811,9 +948,18 @@ SIGUSR2 31 user defined signal 2 - -ldd [OPTION]... FILE... - + + ldd + -ruv + FILE + + + ldd + + -h + -V + + @@ -861,11 +1007,27 @@ ldd [OPTION]... FILE... - -locale [-amvhV] -locale [-ck] NAME -locale [-iusfnU] - + + locale + -amvhV + + + locale + -ck + NAME + + + locale + -iusfnU + + + locale + + -h + -V + + + @@ -1041,9 +1203,18 @@ bash$ locale noexpr - -lsattr [-RVadhln] [file]... - + + lsattr + -Radln + FILE + + + lsattr + + -h + -V + + @@ -1106,9 +1277,22 @@ lsattr [-RVadhln] [file]... - -minidumper [OPTION] FILENAME WIN32PID - + + minidumper + -d + -n + -q + -t TYPE + FILENAME + WIN32PID + + + minidumper + + -h + -V + + @@ -1159,9 +1343,30 @@ minidumper [OPTION] FILENAME WIN32PID - -mkgroup [OPTION]... - + + mkgroup + + + -l + -L + + MACHINE + + -d DOMAIN + -c + -S CHAR + -o OFFSET + -g GROUPNAME + -b + -U GROUPLIST + + + mkgroup + + -h + -V + + @@ -1261,9 +1466,30 @@ groups on domain controllers and domain member machines. - -mkpasswd [OPTIONS]... - + + mkpasswd + + + -l + -L + + MACHINE + + -d DOMAIN + -c + -S CHAR + -o OFFSET + -u USERNAME + -b + -U USERLIST + + + mkpassword + + -h + -V + + @@ -1371,11 +1597,41 @@ on domain controllers and domain member machines. - -mount [OPTION] [<win32path> <posixpath>] -mount -a -mount <posixpath> - + + mount + -f + -o MOUNT_OPTION, + + WIN32PATH + POSIXPATH + + + + mount + -a + + + mount + POSIXPATH + + + mount + -m + + + mount + + -c POSIXPATH + -p + + + + mount + + -h + -V + + @@ -1637,9 +1893,52 @@ D: on /d type fat (binary,user,noumount) - -passwd [OPTION] [USER] - + + passwd + + -S + + + -l + -u + + + -c + -C + + + -e + -E + + + -p + -P + + + + -d SERVER + USER + + + passwd + -R + + + passwd + + -i NUM + -n MINDAYS + -x MAXDAYS + -L LEN + + + + passwd + + -h + -V + + @@ -1798,9 +2097,18 @@ specifying an empty password. - -pldd [OPTION...] PID - + + pldd + PID + + + pldd + + -? + --usage + -V + + @@ -1832,9 +2140,19 @@ pldd [OPTION...] PID - -ps [-aefls] [-u UID] - + + ps + -aeflsW + -u UID + -p PID + + + ps + + -h + -V + + @@ -1905,9 +2223,87 @@ With no options, ps outputs the long format by default - -regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY - + + regtool + -qvwW + add|check|get|list|remove|unset|load|unload|save + KEY + + PATH + DATA + + + + regtool + add + KEY\SUBKEY + + + regtool + check + KEY + + + regtool + -bnx + get + KEY + + + regtool + -klp + list + KEY + + + regtool + remove + KEY + + + regtool + -bDeimnQsf + set + KEY\VALUE + DATA + + + regtool + -f + unset + KEY\VALUE + + + regtool + load + KEY\SUBKEY + PATH + + + regtool + unload + KEY\SUBKEY + + + regtool + save + KEY\SUBKEY + PATH + + + regtool + -f + restore + KEY/SUBKEY + PATH + + + regtool + + -h + -V + + @@ -2098,10 +2494,34 @@ Example: - -setfacl [-n] {-f ACL_FILE | -s acl_entries} FILE... -setfacl [-n] {[-bk]|[-x acl_entries] [-m acl_entries]} FILE... - + + setfacl + -n + + -f ACL_FILE + -s acl_entries + + FILE + + + setfacl + -n + + + -bk + -x acl_entries + + -m acl_entries + + FILE + + + setfacl + + -h + -V + + @@ -2247,9 +2667,20 @@ $ getfacl source_file | setfacl -f - target_file - -setmetamode [metabit|escprefix] - + + setmetamode + + metabit + escprefix + + + + setmetamode + + -h + -V + + @@ -2295,9 +2726,20 @@ Other options: - -ssp [options] low_pc high_pc command... - + + ssp + -cdelstv + low_pc + high_pc + command + + + ssp + + -h + -V + + @@ -2466,10 +2908,28 @@ $ ssp -v -s -l - -strace [OPTIONS] <command-line> -strace [OPTIONS] -p <pid> - + + strace + -defnqtuw + -b SIZE + -m MASK + -o FILENAME + -f PERIOD + + command-line + + -T + -p pid + + + + + strace + + -h + -V + + @@ -2561,9 +3021,13 @@ $ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' &am - -tzset [OPTION] - + + tzset + + -h + -V + + @@ -2609,9 +3073,21 @@ setenv TZ `tzset` - -umount [OPTION] [<posixpath>] - + + umount + POSIXPATH + + + umount + -U + + + umount + + -h + -V + + -- 2.31.1