(To everyone, but Karl in particular I think:)
May I re-format the source lines of the built-in help text such that output
lines are not broken over two source lines? The present layout is so awkward
that I feel it is stifling maintenance of that text.
Here is an example of the before:
" 2. Exports a clean directory tree from the working copy specified "
"by\n"
" PATH1, at revision REV if it is given, otherwise at WORKING, "
"into\n"
" PATH2. If PATH2 is omitted, the last component of the "
"PATH1 is used\n"
" for the local directory name. If REV is not specified,"
" all local\n"
" changes will be preserved. Files not under version "
"control will\n"
" not be copied.\n"
"\n"
" If specified, PEGREV determines in which revision the target is "
"first\n"
" looked up.\n"),
and after:
" 2. Exports a clean directory tree from the working copy specified by\n"
" PATH1, at revision REV if it is given, otherwise at WORKING, into\n"
" PATH2. If PATH2 is omitted, the last component of the PATH1 is used\n"
" for the local directory name. If REV is not specified, all local\n"
" changes will be preserved. Files not under version control will\n"
" not be copied.\n"
"\n"
" If specified, PEGREV determines in which revision the target is first\n"
" looked up.\n"),
The re-formatting creates quite a few source lines over 80 columns wide; I hope
you will agree that an exception to our rule will be worthwhile in this case.
I have taken a couple of measures to make a few columns more room so that not
so many lines go over 80 columns.
Obviously keeping the output text below 80 columns is important: it will be
seen by users in a wide range of contexts and we do not expect the users to
know how to (or to have to) control the width or wrapping or scrolling
behaviour of the displays that they may be using, especially when the task is
viewing help text. However, developers can reasonably be expected to cope with
and work around what might be an inconvenience to some of them, some of the time.
The other relevant point is that allowing arbitrarily long lines in our source
would cause inconvenience for almost all developers, because someone would use
lines longer than anyone else finds convenient. This patch does not open the
door to arbitrary lengths, because it is limited to a small indentation plus
fewer than 80 columns of output plus a few characters of syntax (quotes,
commas, and the like).
[[[
Reformat the source code of help text such that output lines are not split
across source lines. This makes it easier to read and edit, but breaks our
rule of keeping source code lines within 80 columns; an exception seems
worthwhile. The text itself is unchanged.
* subversion/clients/cmdline/main.c (svn_cl__options, svn_cl__cmd_table),
* subversion/svnadmin/main.c (options_table, cmd_table, subcommand_help),
* subversion/svnlook/main.c (options_table, cmd_table),
* subversion/svnversion/main.c (help):
Concatenate adjacent strings. To make more lines fit in 80 columns,
unindent file-scope initialiser blocks (we have no consistency in that
respect), and move "N_" onto the previous line.
]]]
The attached diff is one ignoring the white space changes and showing no
context (GNU "diff -bwBU0"). The full patch is at
<http://www.foad.me.uk/tmp/help-long-lines.patch>.
Thoughts or approval, please.
- Julian
Index: subversion/clients/cmdline/main.c
===================================================================
--- subversion/clients/cmdline/main.c (revision 17521)
+++ subversion/clients/cmdline/main.c (working copy)
@@ -77,2 +77 @@
- " \"{\" DATE \"}\" revision at start "
- "of the date\n"
+ " \"{\" DATE \"}\" revision at start of the date\n"
@@ -80,6 +79,3 @@
- " \"BASE\" base rev of item's "
- "working copy\n"
- " \"COMMITTED\" last commit at or "
- "before BASE\n"
- " \"PREV\" revision just before "
- "COMMITTED")
+ " \"BASE\" base rev of item's working copy\n"
+ " \"COMMITTED\" last commit at or before BASE\n"
+ " \"PREV\" revision just before COMMITTED")
@@ -100 +96,2 @@
- {"extensions", 'x', 1, N_("pass ARG to --diff-cmd as options (default: '-u')")},
+ {"extensions", 'x', 1,
+ N_("pass ARG to --diff-cmd as options (default: '-u')")},
@@ -192,2 +189,2 @@
- { "add", svn_cl__add, {0},
- N_("Put files and directories under version control, scheduling\n"
+ { "add", svn_cl__add, {0}, N_
+ ("Put files and directories under version control, scheduling\n"
@@ -200,2 +197,2 @@
- { "blame", svn_cl__blame, {"praise", "annotate", "ann"},
- N_("Output the content of specified files or\n"
+ { "blame", svn_cl__blame, {"praise", "annotate", "ann"}, N_
+ ("Output the content of specified files or\n"
@@ -210,2 +207,2 @@
- { "cat", svn_cl__cat, {0},
- N_("Output the content of specified files or URLs.\n"
+ { "cat", svn_cl__cat, {0}, N_
+ ("Output the content of specified files or URLs.\n"
@@ -232,2 +229,2 @@
- { "cleanup", svn_cl__cleanup, {0},
- N_("Recursively clean up the working copy, removing locks, resuming\n"
+ { "cleanup", svn_cl__cleanup, {0}, N_
+ ("Recursively clean up the working copy, removing locks, resuming\n"
@@ -238,2 +235,2 @@
- { "commit", svn_cl__commit, {"ci"},
- N_("Send changes from your working copy to the repository.\n"
+ { "commit", svn_cl__commit, {"ci"}, N_
+ ("Send changes from your working copy to the repository.\n"
@@ -249,3 +246,2 @@
- { "copy", svn_cl__copy, {"cp"},
- N_("Duplicate something in working copy or repository, remembering "
- "history.\n"
+ { "copy", svn_cl__copy, {"cp"}, N_
+ ("Duplicate something in working copy or repository, remembering history.\n"
@@ -262,2 +258,2 @@
- { "delete", svn_cl__delete, {"del", "remove", "rm"},
- N_("Remove files and directories from version control.\n"
+ { "delete", svn_cl__delete, {"del", "remove", "rm"}, N_
+ ("Remove files and directories from version control.\n"
@@ -278,2 +274,2 @@
- { "diff", svn_cl__diff, {"di"},
- N_("Display the differences between two paths.\n"
+ { "diff", svn_cl__diff, {"di"}, N_
+ ("Display the differences between two paths.\n"
@@ -281,2 +277 @@
- " 2. diff [-c M | -r N[:M]] --old=OLD-TGT[@OLDREV] "
- "[--new=NEW-TGT[@NEWREV]] \\\n"
+ " 2. diff [-c M | -r N[:M]] --old=OLD-TGT[@OLDREV] [--new=NEW-TGT[@NEWREV]] \\\n"
@@ -286,2 +281 @@
- " 1. Display the changes made to TARGETs as they are seen in REV "
- "between\n"
+ " 1. Display the changes made to TARGETs as they are seen in REV between\n"
@@ -290,4 +284,2 @@
- " N defaults to BASE if any TARGET is a working copy path, otherwise "
- "it\n"
- " must be specified. M defaults to the current working version if "
- "any\n"
+ " N defaults to BASE if any TARGET is a working copy path, otherwise it\n"
+ " must be specified. M defaults to the current working version if any\n"
@@ -297,10 +289,5 @@
- " 2. Display the differences between OLD-TGT as it was seen in OLDREV "
- "and\n"
- " NEW-TGT as it was seen in NEWREV. PATHs, if given, are relative "
- "to\n"
- " OLD-TGT and NEW-TGT and restrict the output to differences for "
- "those\n"
- " paths. OLD-TGT and NEW-TGT may be working copy paths or "
- "URL[@REV]. \n"
- " NEW-TGT defaults to OLD-TGT if not specified. -r N makes OLDREV "
- "default\n"
+ " 2. Display the differences between OLD-TGT as it was seen in OLDREV and\n"
+ " NEW-TGT as it was seen in NEWREV. PATHs, if given, are relative to\n"
+ " OLD-TGT and NEW-TGT and restrict the output to differences for those\n"
+ " paths. OLD-TGT and NEW-TGT may be working copy paths or URL[@REV]. \n"
+ " NEW-TGT defaults to OLD-TGT if not specified. -r N makes OLDREV default\n"
@@ -310,2 +297 @@
- " 3. Shorthand for 'svn diff --old=OLD-URL[@OLDREV] "
- "--new=NEW-URL[@NEWREV]'\n"
+ " 3. Shorthand for 'svn diff --old=OLD-URL[@OLDREV] --new=NEW-URL[@NEWREV]'\n"
@@ -313,2 +299 @@
- " Use just 'svn diff' to display local modifications in "
- "a working copy.\n"),
+ " Use just 'svn diff' to display local modifications in a working copy.\n"),
@@ -320,2 +305,2 @@
- { "export", svn_cl__export, {0},
- N_("Create an unversioned copy of a tree.\n"
+ { "export", svn_cl__export, {0}, N_
+ ("Create an unversioned copy of a tree.\n"
@@ -330,10 +315,5 @@
- " 2. Exports a clean directory tree from the working copy specified "
- "by\n"
- " PATH1, at revision REV if it is given, otherwise at WORKING, "
- "into\n"
- " PATH2. If PATH2 is omitted, the last component of the "
- "PATH1 is used\n"
- " for the local directory name. If REV is not specified,"
- " all local\n"
- " changes will be preserved. Files not under version "
- "control will\n"
+ " 2. Exports a clean directory tree from the working copy specified by\n"
+ " PATH1, at revision REV if it is given, otherwise at WORKING, into\n"
+ " PATH2. If PATH2 is omitted, the last component of the PATH1 is used\n"
+ " for the local directory name. If REV is not specified, all local\n"
+ " changes will be preserved. Files not under version control will\n"
@@ -342,2 +322 @@
- " If specified, PEGREV determines in which revision the target is "
- "first\n"
+ " If specified, PEGREV determines in which revision the target is first\n"
@@ -349,2 +328,2 @@
- { "help", svn_cl__help, {"?", "h"},
- N_("Describe the usage of this program or its subcommands.\n"
+ { "help", svn_cl__help, {"?", "h"}, N_
+ ("Describe the usage of this program or its subcommands.\n"
@@ -358,2 +337,2 @@
- { "import", svn_cl__import, {0},
- N_("Commit an unversioned file or tree into the repository.\n"
+ { "import", svn_cl__import, {0}, N_
+ ("Commit an unversioned file or tree into the repository.\n"
@@ -371,2 +350,2 @@
- { "info", svn_cl__info, {0},
- N_("Display information about a local or remote item.\n"
+ { "info", svn_cl__info, {0}, N_
+ ("Display information about a local or remote item.\n"
@@ -380,2 +359,2 @@
- { "list", svn_cl__ls, {"ls"},
- N_("List directory entries in the repository.\n"
+ { "list", svn_cl__ls, {"ls"}, N_
+ ("List directory entries in the repository.\n"
@@ -385,4 +364,2 @@
- " they exist in the repository. If TARGET is a working copy path, "
- "the\n"
- " corresponding repository URL will be used. If specified, REV "
- "determines\n"
+ " they exist in the repository. If TARGET is a working copy path, the\n"
+ " corresponding repository URL will be used. If specified, REV determines\n"
@@ -391,2 +368 @@
- " The default TARGET is '.', meaning the repository URL of the "
- "current\n"
+ " The default TARGET is '.', meaning the repository URL of the current\n"
@@ -405,2 +381,2 @@
- { "lock", svn_cl__lock, {0},
- N_("Lock working copy paths or URLs in the repository, so that\n"
+ { "lock", svn_cl__lock, {0}, N_
+ ("Lock working copy paths or URLs in the repository, so that\n"
@@ -414,2 +390,2 @@
- { "log", svn_cl__log, {0},
- N_("Show the log messages for a set of revision(s) and/or file(s).\n"
+ { "log", svn_cl__log, {0}, N_
+ ("Show the log messages for a set of revision(s) and/or file(s).\n"
@@ -426,2 +402 @@
- " With -q, don't print the log message body itself (note that "
- "this is\n"
+ " With -q, don't print the log message body itself (note that this is\n"
@@ -430,2 +405 @@
- " Each log message is printed just once, even if more than one "
- "of the\n"
+ " Each log message is printed just once, even if more than one of the\n"
@@ -433,2 +407 @@
- " follow copy history by default. Use --stop-on-copy to "
- "disable this\n"
+ " follow copy history by default. Use --stop-on-copy to disable this\n"
@@ -446,2 +419,2 @@
- { "merge", svn_cl__merge, {0},
- N_("Apply the differences between two sources to a working copy path.\n"
+ { "merge", svn_cl__merge, {0}, N_
+ ("Apply the differences between two sources to a working copy path.\n"
@@ -453,2 +426 @@
- " N and M. These are the two sources to be compared. The "
- "revisions\n"
+ " N and M. These are the two sources to be compared. The revisions\n"
@@ -457,4 +429,2 @@
- " 2. In the second form, the URLs corresponding to the source "
- "working\n"
- " copy paths define the sources to be compared. The revisions "
- "must\n"
+ " 2. In the second form, the URLs corresponding to the source working\n"
+ " copy paths define the sources to be compared. The revisions must\n"
@@ -477,2 +447,2 @@
- { "mkdir", svn_cl__mkdir, {0},
- N_("Create a new directory under version control.\n"
+ { "mkdir", svn_cl__mkdir, {0}, N_
+ ("Create a new directory under version control.\n"
@@ -484,2 +454 @@
- " 1. Each directory specified by a working copy PATH is created "
- "locally\n"
+ " 1. Each directory specified by a working copy PATH is created locally\n"
@@ -488,2 +457 @@
- " 2. Each directory specified by a URL is created in the repository "
- "via\n"
+ " 2. Each directory specified by a URL is created in the repository via\n"
@@ -492,2 +460 @@
- " In both cases, all the intermediate directories must already "
- "exist.\n"),
+ " In both cases, all the intermediate directories must already exist.\n"),
@@ -497,2 +464,2 @@
- { "move", svn_cl__move, {"mv", "rename", "ren"},
- N_("Move and/or rename something in working copy or repository.\n"
+ { "move", svn_cl__move, {"mv", "rename", "ren"}, N_
+ ("Move and/or rename something in working copy or repository.\n"
@@ -510,2 +477,2 @@
- { "propdel", svn_cl__propdel, {"pdel", "pd"},
- N_("Remove a property from files, dirs, or revisions.\n"
+ { "propdel", svn_cl__propdel, {"pdel", "pd"}, N_
+ ("Remove a property from files, dirs, or revisions.\n"
@@ -521,2 +488,2 @@
- { "propedit", svn_cl__propedit, {"pedit", "pe"},
- N_("Edit a property with an external editor.\n"
+ { "propedit", svn_cl__propedit, {"pedit", "pe"}, N_
+ ("Edit a property with an external editor.\n"
@@ -533,2 +500,2 @@
- { "propget", svn_cl__propget, {"pget", "pg"},
- N_("Print the value of a property on files, dirs, or revisions.\n"
+ { "propget", svn_cl__propget, {"pget", "pg"}, N_
+ ("Print the value of a property on files, dirs, or revisions.\n"
@@ -552,2 +519,2 @@
- { "proplist", svn_cl__proplist, {"plist", "pl"},
- N_("List all properties on files, dirs, or revisions.\n"
+ { "proplist", svn_cl__proplist, {"plist", "pl"}, N_
+ ("List all properties on files, dirs, or revisions.\n"
@@ -564,2 +531,2 @@
- { "propset", svn_cl__propset, {"pset", "ps"},
- N_("Set the value of a property on files, dirs, or revisions.\n"
+ { "propset", svn_cl__propset, {"pset", "ps"}, N_
+ ("Set the value of a property on files, dirs, or revisions.\n"
@@ -573,2 +540 @@
- " The value may be provided with the --file option instead of "
- "PROPVAL.\n"
+ " The value may be provided with the --file option instead of PROPVAL.\n"
@@ -578,2 +544 @@
- " svn:ignore - A newline separated list of file patterns to "
- "ignore.\n"
+ " svn:ignore - A newline separated list of file patterns to ignore.\n"
@@ -581,2 +546 @@
- " URL, HeadURL - The URL for the head version of "
- "the object.\n"
+ " URL, HeadURL - The URL for the head version of the object.\n"
@@ -584,4 +548,2 @@
- " Date, LastChangedDate - The date/time the object was last "
- "modified.\n"
- " Rev, Revision, - The last revision the object "
- "changed.\n"
+ " Date, LastChangedDate - The date/time the object was last modified.\n"
+ " Rev, Revision, - The last revision the object changed.\n"
@@ -589,2 +551 @@
- " Id - A compressed summary of the "
- "previous\n"
+ " Id - A compressed summary of the previous\n"
@@ -603,2 +564 @@
- " svn:needs-lock - If present, indicates that the file should be "
- "locked\n"
+ " svn:needs-lock - If present, indicates that the file should be locked\n"
@@ -607,4 +567,2 @@
- " The svn:keywords, svn:executable, svn:eol-style, svn:mime-type "
- "and\n"
- " svn:needs-lock properties cannot be set on a directory. A "
- "non-recursive\n"
+ " The svn:keywords, svn:executable, svn:eol-style, svn:mime-type and\n"
+ " svn:needs-lock properties cannot be set on a directory. A non-recursive\n"
@@ -617,2 +575,2 @@
- { "resolved", svn_cl__resolved, {0},
- N_("Remove 'conflicted' state on working copy files or directories.\n"
+ { "resolved", svn_cl__resolved, {0}, N_
+ ("Remove 'conflicted' state on working copy files or directories.\n"
@@ -626,2 +584,2 @@
- { "revert", svn_cl__revert, {0},
- N_("Restore pristine working copy file (undo most local edits).\n"
+ { "revert", svn_cl__revert, {0}, N_
+ ("Restore pristine working copy file (undo most local edits).\n"
@@ -630,4 +588,2 @@
- " Note: this subcommand does not require network access, and "
- "resolves\n"
- " any conflicted states. However, it does not restore removed "
- "directories.\n"),
+ " Note: this subcommand does not require network access, and resolves\n"
+ " any conflicted states. However, it does not restore removed directories.\n"),
@@ -645,2 +601 @@
- " First column: Says if item was added, deleted, or otherwise "
- "changed\n"
+ " First column: Says if item was added, deleted, or otherwise changed\n"
@@ -713,2 +668,2 @@
- { "switch", svn_cl__switch, {"sw"},
- N_("Update the working copy to a different URL.\n"
+ { "switch", svn_cl__switch, {"sw"}, N_
+ ("Update the working copy to a different URL.\n"
@@ -718,2 +673 @@
- " 1. Update the working copy to mirror a new URL within the "
- "repository.\n"
+ " 1. Update the working copy to mirror a new URL within the repository.\n"
@@ -721,2 +675 @@
- " move a working copy to a branch or tag within the same "
- "repository.\n"
+ " move a working copy to a branch or tag within the same repository.\n"
@@ -724,6 +677,3 @@
- " 2. Rewrite working copy URL metadata to reflect a syntactic change "
- "only.\n"
- " This is used when repository's root URL changes (such as a "
- "scheme\n"
- " or hostname change) but your working copy still reflects the "
- "same\n"
+ " 2. Rewrite working copy URL metadata to reflect a syntactic change only.\n"
+ " This is used when repository's root URL changes (such as a scheme\n"
+ " or hostname change) but your working copy still reflects the same\n"
@@ -734,2 +684,2 @@
- { "unlock", svn_cl__unlock, {0},
- N_("Unlock working copy paths or URLs.\n"
+ { "unlock", svn_cl__unlock, {0}, N_
+ ("Unlock working copy paths or URLs.\n"
@@ -742,2 +692,2 @@
- { "update", svn_cl__update, {"up"},
- N_("Bring changes from the repository into the working copy.\n"
+ { "update", svn_cl__update, {"up"}, N_
+ ("Bring changes from the repository into the working copy.\n"
@@ -749,2 +699 @@
- " For each updated item a line will start with a character reporting "
- "the\n"
+ " For each updated item a line will start with a character reporting the\n"
@@ -759,4 +708,2 @@
- " A character in the first column signifies an update to the actual "
- "file,\n"
- " while updates to the file's properties are shown in the second "
- "column.\n"
+ " A character in the first column signifies an update to the actual file,\n"
+ " while updates to the file's properties are shown in the second column.\n"
@@ -764,2 +711 @@
- " been broken or stolen.\n"
- ),
+ " been broken or stolen.\n"),
Index: subversion/svnadmin/main.c
===================================================================
--- subversion/svnadmin/main.c (revision 17457)
+++ subversion/svnadmin/main.c (working copy)
@@ -323,2 +323 @@
- "a diff against the previous revision, instead of the usual"
- " fulltext.\n"),
+ "a diff against the previous revision, instead of the usual fulltext.\n"),
@@ -354,2 +353 @@
- "one specified in the stream. Progress feedback is sent to"
- " stdout.\n"),
+ "one specified in the stream. Progress feedback is sent to stdout.\n"),
@@ -390,4 +388,2 @@
- "Set the log-message on revision REVISION to the contents of FILE."
- " Use\n"
- "--bypass-hooks to avoid triggering the revision-property-related"
- " hooks\n"
+ "Set the log-message on revision REVISION to the contents of FILE. Use\n"
+ "--bypass-hooks to avoid triggering the revision-property-related hooks\n"
@@ -643,2 +639 @@
- "Type 'svnadmin help <subcommand>' for help on a specific"
- " subcommand.\n"
+ "Type 'svnadmin help <subcommand>' for help on a specific subcommand.\n"
Index: subversion/svnlook/main.c
===================================================================
--- subversion/svnlook/main.c (revision 17457)
+++ subversion/svnlook/main.c (working copy)
@@ -148,2 +147 @@
- "Print the contents of a file. Leading '/' on FILE_PATH is "
- "optional.\n"),
+ "Print the contents of a file. Leading '/' on FILE_PATH is optional.\n"),
Index: subversion/svnversion/main.c
===================================================================
--- subversion/svnversion/main.c (revision 17457)
+++ subversion/svnversion/main.c (working copy)
@@ -124,2 +124 @@
- " If invoked without arguments WC_PATH will be the current "
- "directory.\n"
+ " If invoked without arguments WC_PATH will be the current directory.\n"
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Nov 26 20:17:54 2005