You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by kf...@collab.net on 2005/11/26 19:06:06 UTC
Re: Reformat help text source, creating some long source lines
Julian Foad <ju...@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
Re: Reformat help text source, creating some long source lines
Posted by Peter Samuelson <pe...@p12n.org>.
[Julian Foad]
> Branko ??ibej wrote:
> >Looking at this from the point of view of the typesetting world,
> >there's no reason to introduce long lines in the source. Within
> >running (roman) text, the optimal line length for easy reading is
> >about 68 glyphs; anything wider makes it harder for the eye to skip
> >to the next line.
> Yes - 68 plus or minus 20 or so - it's not an exact science. Thus,
> this isn't a compelling argument in itself for reducing from 79 to 68
> or whatever, but it does provide a "feel-good factor" if we have
> another reason to reduce the width, and we do.
Right, 79 isn't *that* much greater than 68. And in a lot of option
help, lines are effectively a lot shorter anyway, due to the 2-column
layout.
> Also, in a shell window, in contrast to printed matter, we need to
> make reasonably efficient use of the horizontal space available, so
> as not to use up unreasonably much vertical space, so we shouldn't
> use a width much less than around 60 to 70 columns.
Efficient use of vertical space is important in printed matter too.
The difference is that in printed matter, when your text gets too wide,
you split it into two or more columns. On a CRT, with only 80 columns
to work with, that's not really possible, except with things like
option help where the 2-column layout is already natural.
> We could now shorten the displayed lines so as to bring the source
> back to 79 columns.
If I had a vote on these matters I'd strongly suggest that optimally
formatted output is much more important than optimally formatted source
code - and that allowing long lines in the source (as the patch in
question did) is the least painful way to achieve this.
Also, I agree that citing 68 glyphs as optimal is misleading, in light
of both vertical efficiency and existing indentation (due to 2-column
help text, or other reasons something might be indented a few spaces).
Remember, the indentation doesn't count toward a line's readable
length.
In cases where text can be reformatted to make lines shorter than (say)
70 columns, *without adding any lines*, I'd be in favor of that too.
Re: Reformat help text source, creating some long source lines
Posted by Julian Foad <ju...@btopenworld.com>.
Branko Čibej wrote:
> Julian Foad wrote:
>> kfogel@collab.net wrote:
>>> Julian Foad <ju...@btopenworld.com> writes:
>>>
>>>> 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 - OK - done - r17522.
>
> I wish I'd seen this thread before...
Sorry - I did rush it through a bit - but I don't think the change was a bad
thing in itself. We can now more easily edit the text to reduce the column
count if we want to.
In fact, the column count used within the help on different commands varies
quite a bit. Consistency wouldn't hurt. But, I also think a lot of the help
text could do with a jolly good overhaul. Making these things easier was my goal.
> Looking at this from the point of view of the typesetting world, there's
> no reason to introduce long lines in the source. Within running (roman)
> text, the optimal line length for easy reading is about 68 glyphs;
> anything wider makes it harder for the eye to skip to the next line.
Yes - 68 plus or minus 20 or so - it's not an exact science. Thus, this isn't
a compelling argument in itself for reducing from 79 to 68 or whatever, but it
does provide a "feel-good factor" if we have another reason to reduce the
width, and we do.
Also, in a shell window, in contrast to printed matter, we need to make
reasonably efficient use of the horizontal space available, so as not to use up
unreasonably much vertical space, so we shouldn't use a width much less than
around 60 to 70 columns.
> What I'm getting at is: shorten the displayed text lines, don't widen
> the source.
We could now shorten the displayed lines so as to bring the source back to 79
columns. In running text, that's fine. (On the occasional line that really
benefits from being between 69 and 79 characters long, such as some syntax
lines, we can either split the source or leave a long source line, whichever
seems best.)
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Reformat help text source, creating some long source lines
Posted by Branko Čibej <br...@xbc.nu>.
Julian Foad wrote:
> kfogel@collab.net wrote:
>> Julian Foad <ju...@btopenworld.com> writes:
>>
>>> 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 - OK - done - r17522.
I wish I'd seen this thread before...
Looking at this from the point of view of the typesetting world, there's
no reason to introduce long lines in the source. Within running (roman)
text, the optimal line length for easy reading is about 68 glyphs;
anything wider makes it harder for the eye to skip to the next line.
(And that's why I'll never understand those people who expand their Web
browser windows across the whole screen, then get a crick in their neck
trying to follow the text.)
What I'm getting at is: shorten the displayed text lines, don't widen
the source.
-- Brane
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Reformat help text source, creating some long source lines
Posted by Julian Foad <ju...@btopenworld.com>.
kfogel@collab.net wrote:
> Julian Foad <ju...@btopenworld.com> writes:
>
>>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 - OK - done - r17522.
Max Bowsher wrote:
> Doing this does, of course, mean that as soon as you put the text into a
> line-wrapping mailer, it goes wonky, but overall, I agree with Julian's
> point about stifling maintenance.
>
> I have a slight extension of the proposal:
>
> If we limit our output text to 76 characters of width, and decide to
> permit long multiline text blocks to be totally *non-indented*, then we
> will avoid the need for the extra line breaks in the source which are
> the cause of the awkwardness, whilst still keeping lines within 80
> characters:
That's certainly another possibility but, as well as slightly restricting the
output, the indentation would be ugly for everyone all of the time.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org