[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Reformat help text source, creating some long source lines

From: Max Bowsher <maxb1_at_ukf.net>
Date: 2005-11-26 20:33:56 CET

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Julian Foad wrote:
> (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.

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:

'"' + 76 characters + '\n"' = 80 characters.

Max.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Cygwin)

iD8DBQFDiLikfFNSmcDyxYARAlVMAJwJRDYrxYBhHuEG8EqkuwiRuCiOagCg21H9
goIzORxtHGToQTJ3pszDct0=
=kA+c
-----END PGP SIGNATURE-----

---------------------------------------------------------------------
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:34:40 2005

This is an archived mail posted to the Subversion Dev mailing list.