More builtin documention moved to external files

Move the libcmd builtin documentation into files separate from the
source code.

Related #507

src/cmd/ksh93/cmds/basename.c

@@ -30,42 +30,12 @@
 
 #include <string.h>
 
+#include "builtins.h"
 #include "error.h"
 #include "option.h"
 #include "sfio.h"
 #include "shcmd.h"
 
-static const char usage[] =
-    "[-?\n@(#)$Id: basename (AT&T Research) 2010-05-06 $\n]" USAGE_LICENSE
-    "[+NAME?basename - strip directory and suffix from filenames]"
-    "[+DESCRIPTION?\bbasename\b removes all leading directory components "
-    "from the file name defined by \astring\a. If the file name defined by "
-    "\astring\a has a suffix that ends in \asuffix\a, it is removed as "
-    "well.]"
-    "[+?If \astring\a consists solely of \b/\b characters the output will be "
-    "a single \b/\b. Trailing "
-    "\b/\b characters are removed, and if there are any remaining \b/\b "
-    "characters in \astring\a, all characters up to and including the last "
-    "\b/\b are removed. Finally, if \asuffix\a is specified, and is "
-    "identical the end of \astring\a, these characters are removed. The "
-    "characters not removed from \astring\a will be written on a single line "
-    "to the standard output.]"
-    "[a:all?All operands are treated as \astring\a and each modified "
-    "pathname is printed on a separate line on the standard output.]"
-    "[s:suffix?All operands are treated as \astring\a and each modified "
-    "pathname, with \asuffix\a removed if it exists, is printed on a "
-    "separate line on the standard output.]:[suffix]"
-    "\n"
-    "\n string [suffix]\n"
-    "string ...\n"
-    "\n"
-    "[+EXIT STATUS?]"
-    "{"
-    "[+0?Successful Completion.]"
-    "[+>0?An error occurred.]"
-    "}"
-    "[+SEE ALSO?\bdirname\b(1), \bgetconf\b(1), \bbasename\b(3)]";
-
 static void namebase(Sfio_t *outfile, char *pathname, char *suffix) {
     char *first, *last;
     int n = 0;
@@ -106,7 +76,7 @@ int b_basename(int argc, char **argv, Shbltin_t *context) {
     int n;
 
     if (cmdinit(argc, argv, context, 0)) return -1;
-    while ((n = optget(argv, usage))) {
+    while ((n = optget(argv, sh_optbasename))) {
         switch (n) {  //!OCLINT(MissingDefaultStatement)
             case 'a':
                 all = 1;

src/cmd/ksh93/cmds/cat.c

@@ -33,51 +33,12 @@
 #include <string.h>
 
 #include "ast.h"
+#include "builtins.h"
 #include "error.h"
 #include "option.h"
 #include "sfio.h"
 #include "shcmd.h"
 
-static const char usage[] =
-    "[-?\n@(#)$Id: cat (AT&T Research) 2013-09-13 $\n]" USAGE_LICENSE
-    "[+NAME?cat - concatenate files]"
-    "[+DESCRIPTION?\bcat\b copies each \afile\a in sequence to the standard"
-    "   output. If no \afile\a is given, or if the \afile\a is \b-\b,"
-    "   \bcat\b copies from standard input starting at the current location.]"
-
-    "[b:number-nonblank?Number lines as with \b-n\b but omit line numbers from"
-    "   blank lines.]"
-    "[d:dos-input?Input files are opened in \atext\amode which removes carriage"
-    "   returns in front of new-lines on some systems.]"
-    "[e?Equivalent to \b-vE\b.]"
-    "[n:number?Causes a line number to be inserted at the beginning of each line.]"
-    "[s?Equivalent to \b-S\b for \aatt\a universe and \b-B\b otherwise.]"
-    "[t?Equivalent to \b-vT\b.]"
-    "[u:unbuffer?The output is not delayed by buffering.]"
-    "[v:show-nonprinting|print-chars?Print characters as follows: space and "
-    "printable characters as themselves; control characters as \b^\b "
-    "followed by a letter of the alphabet; and characters with the high bit "
-    "set as the lower 7 bit character prefixed by \bM^\b for 7 bit "
-    "non-printable characters and \bM-\b for all other characters. If the 7 "
-    "bit character encoding is not ASCII then the characters are converted "
-    "to ASCII to determine \ahigh bit set\a, and if set it is cleared and "
-    "converted back to the native encoding. Multibyte characters in the "
-    "current locale are treated as printable characters.]"
-    "[A:show-all?Equivalent to \b-vET\b.]"
-    "[B:squeeze-blank?Multiple adjacent new-line characters are replace by one"
-    "   new-line.]"
-    "[D:dos-output?Output files are opened in \atext\amode which inserts carriage"
-    "   returns in front of new-lines on some systems.]"
-    "[E:show-ends?Causes a \b$\b to be inserted before each new-line.]"
-    "[S:silent?\bcat\b is silent about non-existent files.]"
-    "[T:show-blank?Causes tabs to be copied as \b^I\b and formfeeds as \b^L\b.]"
-
-    "\n"
-    "\n[file ...]\n"
-    "\n"
-
-    "[+SEE ALSO?\bcp\b(1), \bgetconf\b(1), \bpr\b(1)]";
-
 static char *stdin_argv[] = {"-", NULL};
 
 #define RUBOUT 0177
@@ -354,7 +315,7 @@ int b_cat(int argc, char **argv, Shbltin_t *context) {
     if (cmdinit(argc, argv, context, 0)) return -1;
     att = !path_is_bsd_universe();
     mode = "r";
-    while ((flag = optget(argv, usage))) {
+    while ((flag = optget(argv, sh_optcat))) {
         n = 0;
         switch (flag) {  //!OCLINT(MissingDefaultStatement)
             case 'A':

src/cmd/ksh93/cmds/chmod.c

@@ -36,6 +36,7 @@
 
 #include "ast.h"
 #include "ast_assert.h"
+#include "builtins.h"
 #include "error.h"
 #include "option.h"
 #include "sfio.h"
@@ -49,101 +50,6 @@
 #endif
 #endif
 
-static const char usage[] =
-    "[-?\n@(#)$Id: chmod (AT&T Research) 2012-04-20 $\n]" USAGE_LICENSE
-    "[+NAME?chmod - change the access permissions of files]"
-    "[+DESCRIPTION?\bchmod\b changes the permission of each file "
-    "according to mode, which can be either a symbolic representation "
-    "of changes to make, or an octal number representing the bit "
-    "pattern for the new permissions.]"
-    "[+?Symbolic mode strings consist of one or more comma separated list "
-    "of operations that can be perfomed on the mode. Each operation is of "
-    "the form \auser\a \aop\a \aperm\a where \auser\a is zero or more of "
-    "the following letters:]{"
-    "[+u?User permission bits.]"
-    "[+g?Group permission bits.]"
-    "[+o?Other permission bits.]"
-    "[+a?All permission bits. This is the default if none are specified.]"
-    "}"
-    "[+?The \aperm\a portion consists of zero or more of the following letters:]{"
-    "[+r?Read permission.]"
-    "[+s?Setuid when \bu\b is selected for \awho\a and setgid when \bg\b "
-    "is selected for \awho\a.]"
-    "[+w?Write permission.]"
-    "[+x?Execute permission for files, search permission for directories.]"
-    "[+X?Same as \bx\b except that it is ignored for files that do not "
-    "already have at least one \bx\b bit set.]"
-    "[+l?Exclusive lock bit on systems that support it. Group execute "
-    "must be off.]"
-    "[+t?Sticky bit on systems that support it.]"
-    "}"
-    "[+?The \aop\a portion consists of one or more of the following characters:]{"
-    "[++?Cause the permission selected to be added to the existing "
-    "permissions. | is equivalent to +.]"
-    "[+-?Cause the permission selected to be removed to the existing "
-    "permissions.]"
-    "[+=?Cause the permission to be set to the given permissions.]"
-    "[+&?Cause the permission selected to be \aand\aed with the existing "
-    "permissions.]"
-    "[+^?Cause the permission selected to be propagated to more "
-    "restrictive groups.]"
-    "}"
-    "[+?Symbolic modes with the \auser\a portion omitted are subject to "
-    "\bumask\b(2) settings unless the \b=\b \aop\a or the "
-    "\b--ignore-umask\b option is specified.]"
-    "[+?A numeric mode is from one to four octal digits (0-7), "
-    "derived by adding up the bits with values 4, 2, and 1. "
-    "Any omitted digits are assumed to be leading zeros. The "
-    "first digit selects the set user ID (4) and set group ID "
-    "(2) and save text image (1) attributes. The second digit "
-    "selects permissions for the user who owns the file: read "
-    "(4), write (2), and execute (1); the third selects permissions"
-    "for other users in the file's group, with the same values; "
-    "and the fourth for other users not in the file's group, with "
-    "the same values.]"
-
-    "[+?For symbolic links, by default, \bchmod\b changes the mode on the file "
-    "referenced by the symbolic link, not on the symbolic link itself. "
-    "The \b-h\b options can be specified to change the mode of the link. "
-    "When traversing directories with \b-R\b, \bchmod\b either follows "
-    "symbolic links or does not follow symbolic links, based on the "
-    "options \b-H\b, \b-L\b, and \b-P\b.]"
-
-    "[+?When the \b-c\b or \b-v\b options are specified, change notifications "
-    "are written to standard output using the format, "
-    "\b%s: mode changed to %0.4o (%s)\b, with arguments of the "
-    "pathname, the numeric mode, and the resulting permission bits as "
-    "would be displayed by the \bls\b command.]"
-
-    "[+?For backwards compatibility, if an invalid option is given that is a valid "
-    "symbolic mode specification, \bchmod\b treats this as a mode "
-    "specification rather than as an option specification.]"
-
-    "[H:metaphysical?Follow symbolic links for command arguments; otherwise don't "
-    "follow symbolic links when traversing directories.]"
-    "[L:logical|follow?Follow symbolic links when traversing directories.]"
-    "[P:physical|nofollow?Don't follow symbolic links when traversing directories.]"
-    "[R:recursive?Change the mode for files in subdirectories recursively.]"
-    "[c:changes?Describe only files whose permission actually change.]"
-    "[f:quiet|silent?Do not report files whose permissioins fail to change.]"
-    "[h|l:symlink?Change the mode of symbolic links on systems that "
-    "support \blchmod\b(2). Implies \b--physical\b.]"
-    "[i:ignore-umask?Ignore the \bumask\b(2) value in symbolic mode "
-    "expressions. This is probably how you expect \bchmod\b to work.]"
-    "[n:show?Show actions but do not change any file modes.]"
-    "[F:reference?Omit the \amode\a operand and use the mode of \afile\a "
-    "instead.]:[file]"
-    "[v:verbose?Describe changed permissions of all files.]"
-    "\n"
-    "\nmode file ...\n"
-    "\n"
-    "[+EXIT STATUS?]{"
-    "[+0?All files changed successfully.]"
-    "[+>0?Unable to change mode of one or more files.]"
-    "}"
-    "[+SEE ALSO?\bchgrp\b(1), \bchown\b(1), \blchmod\b(1), \btw\b(1), \bgetconf\b(1), "
-    "\bls\b(1), \bumask\b(2)]";
-
 #ifndef ENOSYS
 #define ENOSYS EINVAL
 #endif
@@ -172,7 +78,7 @@ int b_chmod(int argc, char **argv, Shbltin_t *context) {
     // invocations, to terminate the loop even though they look like unrecognized short flags.
     //
     bool optget_done = false;
-    while (!optget_done && (flag = optget(argv, usage))) {
+    while (!optget_done && (flag = optget(argv, sh_optchmod))) {
         switch (flag) {
             case 'c':
                 notify = 1;

src/cmd/ksh93/cmds/cmp.c

@@ -37,57 +37,12 @@
 #include <sys/stat.h>
 #include <sys/types.h>
 
+#include "builtins.h"
 #include "error.h"
 #include "option.h"
 #include "sfio.h"
 #include "shcmd.h"
 
-static const char usage[] =
-    "[-?\n@(#)$Id: cmp (AT&T Research) 2010-04-11 $\n]" USAGE_LICENSE
-    "[+NAME?cmp - compare two files]"
-    "[+DESCRIPTION?\bcmp\b compares two files \afile1\a and \afile2\a. "
-    "\bcmp\b writes no output if the files are the same. By default, if the "
-    "files differ, the byte and line number at which the first difference "
-    "occurred are written to standard output. Bytes and lines are numbered "
-    "beginning with 1.]"
-    "[+?If \askip1\a or \askip2\a are specified, or the \b-i\b option is "
-    "specified, initial bytes of the corresponding file are skipped before "
-    "beginning the compare. The skip values are in bytes or can have a "
-    "suffix of \bk\b for kilobytes or \bm\b for megabytes.]"
-    "[+?If either \afile1\a or \afiles2\a is \b-\b, \bcmp\b uses standard "
-    "input starting at the current location.]"
-    "[b:print-bytes?Print differing bytes as 3 digit octal values.]"
-    "[c:print-chars?Print differing bytes as follows: non-space printable "
-    "characters as themselves; space and control characters as \b^\b "
-    "followed by a letter of the alphabet; and characters with the high bit "
-    "set as the lower 7 bit character prefixed by \bM^\b for 7 bit space and "
-    "non-printable characters and \bM-\b for all other characters. If the 7 "
-    "bit character encoding is not ASCII then the characters are converted "
-    "to ASCII to determine \ahigh bit set\a, and if set it is cleared and "
-    "converted back to the native encoding. Multibyte characters in the "
-    "current locale are treated as printable characters.]"
-    "[d:differences?Print at most \adifferences\a differences using "
-    "\b--verbose\b output format. \b--differences=0\b is equivalent to "
-    "\b--silent\b.]#[differences]"
-    "[i:ignore-initial|skip?Skip the the first \askip1\a bytes in \afile1\a "
-    "and the first \askip2\a bytes in \afile2\a. If \askip2\a is omitted "
-    "then \askip1\a is used.]:[skip1[::skip2]]:=0::0]"
-    "[l:verbose?Write the decimal byte number and the differing bytes (in "
-    "octal) for each difference.]"
-    "[n:count|bytes?Compare at most \acount\a bytes.]#[count]"
-    "[s:quiet|silent?Write nothing for differing files; return non-zero exit "
-    "status only.]"
-    "\n"
-    "\nfile1 file2 [skip1 [skip2]]\n"
-    "\n"
-    "[+EXIT STATUS?]"
-    "{"
-    "[+0?The files or portions compared are identical.]"
-    "[+1?The files are different.]"
-    "[+>1?An error occurred.]"
-    "}"
-    "[+SEE ALSO?\bcomm\b(1), \bdiff\b(1), \bcat\b(1)]";
-
 #define CMP_VERBOSE 0x01
 #define CMP_SILENT 0x02
 #define CMP_CHARS 0x04
@@ -235,7 +190,7 @@ int b_cmp(int argc, char **argv, Shbltin_t *context) {
     int flags = 0;
 
     if (cmdinit(argc, argv, context, 0)) return -1;
-    while ((n = optget(argv, usage))) {
+    while ((n = optget(argv, sh_optcmp))) {
         switch (n) {  //!OCLINT(MissingDefaultStatement)
             case 'b':
                 flags |= CMP_BYTES;

src/cmd/ksh93/cmds/cut.c

@@ -34,59 +34,13 @@
 #include <wchar.h>
 
 #include "ast.h"
+#include "builtins.h"
 #include "error.h"
 #include "option.h"
 #include "sfio.h"
 #include "shcmd.h"
 #include "stk.h"
 
-static const char usage[] =
-    "[-?\n@(#)$Id: cut (AT&T Research) 2010-08-11 $\n]" USAGE_LICENSE
-    "[+NAME?cut - cut out selected columns or fields of each line of a file]"
-    "[+DESCRIPTION?\bcut\b bytes, characters, or character-delimited fields "
-    "from one or more files, contatenating them on standard output.]"
-    "[+?The option argument \alist\a is a comma-separated or blank-separated "
-    "list of positive numbers and ranges.  Ranges can be of three "
-    "forms.  The first is two positive integers separated by a hyphen "
-    "(\alow\a\b-\b\ahigh\a), which represents all fields from \alow\a to "
-    "\ahigh\a.  The second is a positive number preceded by a hyphen "
-    "(\b-\b\ahigh\a), which represents all fields from field \b1\b to "
-    "\ahigh\a.  The last is a positive number followed by a hyphen "
-    "(\alow\a\b-\b), which represents all fields from \alow\a to the "
-    "last field, inclusive.  Elements in the \alist\a can be repeated, "
-    "can overlap, and can appear in any order.  The order of the "
-    "output is that of the input.]"
-    "[+?One and only one of \b-b\b, \b-c\b, or \b-f\b must be specified.]"
-    "[+?If no \afile\a is given, or if the \afile\a is \b-\b, \bcut\b "
-    "cuts from standard input.   The start of the file is defined "
-    "as the current offset.]"
-    "[b:bytes]:[list?\bcut\b based on a list of byte counts.]"
-    "[c:characters]:[list?\bcut\b based on a list of character counts.]"
-    "[d:delimiter]:[delim?The field character for the \b-f\b option is set "
-    "to \adelim\a.  The default is the \btab\b character.]"
-    "[f:fields]:[list?\bcut\b based on fields separated by the delimiter "
-    "character specified with the \b-d\b optiion.]"
-    "[n!:split?Split multibyte characters selected by the \b-b\b option.]"
-    "[R|r:reclen]#[reclen?If \areclen\a > 0, the input will be read as fixed length "
-    "records of length \areclen\a when used with the \b-b\b or \b-c\b "
-    "option.]"
-    "[s:suppress|only-delimited?Suppress lines with no delimiter characters, "
-    "when used with the \b-f\b option.  By default, lines with no "
-    "delimiters will be passsed in untouched.]"
-    "[D:line-delimeter|output-delimiter]:[ldelim?The line delimiter character for "
-    "the \b-f\b option is set to \aldelim\a.  The default is the "
-    "\bnewline\b character.]"
-    "[N!:newline?Output new-lines at end of each record when used "
-    "with the \b-b\b or \b-c\b option.]"
-    "\n"
-    "\n[file ...]\n"
-    "\n"
-    "[+EXIT STATUS?]{"
-    "[+0?All files processed successfully.]"
-    "[+>0?One or more files failed to open or could not be read.]"
-    "}"
-    "[+SEE ALSO?\bpaste\b(1), \bgrep\b(1)]";
-
 typedef struct Delim_s {
     char *str;
     int len;
@@ -534,7 +488,7 @@ int b_cut(int argc, char **argv, Shbltin_t *context) {
     wdelim.chr = '\t';
     ldelim.chr = '\n';
     wdelim.len = ldelim.len = 1;
-    while ((n = optget(argv, usage))) {
+    while ((n = optget(argv, sh_optcut))) {
         switch (n) {  //!OCLINT(MissingDefaultStatement)
             case 'b':
             case 'c':