Julian Foad <julianfoad@btopenworld.com> writes:
> (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.
I'm not opposed -- your argument makes sense to me. Can you update
www/hacking.html in the obvious way if you do this, though?
Thanks,
-K
> 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
--
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Nov 26 21:28:55 2005