You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Peter Samuelson <pe...@p12n.org> on 2007/04/22 06:26:43 UTC

Re: [PROPOSAL] Change of convention for multiline string literals

[Jonathan Gilbert]
> +/**
> + * A shorter version of APR_EOL_STR; holds the native linefeed for the
> + * current platform. E.g., on UNIX systems, this will be "\n", while on
> + * Windows, it will be "\r\n". This is defined privately because the
> + * macro lacks a namespacing prefix. Used to terminate lines in large
> + * multi-line string literals.
> + */
> +#define NL APR_EOL_STR

IMHO there is no need to use /** here; that's for extracting API
documentation from source files, and NL is not going to become part of
any API.

Indeed, I'm not sure I would document it at all: if anyone doesn't know
what APR_EOL_STR is, they can look it up easily enough.  And, speaking
only for myself, the first time I saw APR_EOL_STR in use it was pretty
obvious what it was for anyway.

> +   "This directory holds run-time configuration information for
> Subversion"  NL
> +   "clients.  The configuration files all share the same syntax, but you"
>   NL
> +   "should examine a particular file to learn what configuration"
>   NL

And you'll want to tell your email client not to wrap lines when you
paste patches....

Re: Re: [PROPOSAL] Change of convention for multiline string literals

Posted by Jonathan Gilbert <o2...@sneakemail.com>.
At 02:39 AM 4/22/2007 -0500, Peter Samuelson wrote:
>> >And you'll want to tell your email client not to wrap lines when you
>> >paste patches....
>> 
>> I *did* mention at the head of the inline patch that the attached
>> gzipped copy should be used instead for precisely this reason. I
>> don't think my e-mail client has such an option.
>
>Fair enough.  The most common workaround for that problem is to attach
>patches uncompressed, as regular text files (MIME type text/plain).
>That way you don't need to paste a separate copy, as we will see the
>attachment inline.  To encourage an email client to label the file as
>text/plain, if you don't have direct control over this, give it a name
>of "something.txt".

I can give that a try next time, though I'll have to manually convert the
newlines; I know from experience that my e-mail client does not do that,
and my SMTP relay refuses to accept (non-conformant) e-mails containing
bare LF characters.

Jonathan Gilbert

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: [PROPOSAL] Change of convention for multiline string literals

Posted by Peter Samuelson <pe...@p12n.org>.
[Jonathan Gilbert]
> >Indeed, I'm not sure I would document it at all: if anyone doesn't know
> >what APR_EOL_STR is, they can look it up easily enough.  And, speaking
> >only for myself, the first time I saw APR_EOL_STR in use it was pretty
> >obvious what it was for anyway.
> 
> Perhaps a more brief comment, then?:
> 
> /* Used to terminate lines in large multi-line string literals. */

*nod*

> >And you'll want to tell your email client not to wrap lines when you
> >paste patches....
> 
> I *did* mention at the head of the inline patch that the attached
> gzipped copy should be used instead for precisely this reason. I
> don't think my e-mail client has such an option.

Fair enough.  The most common workaround for that problem is to attach
patches uncompressed, as regular text files (MIME type text/plain).
That way you don't need to paste a separate copy, as we will see the
attachment inline.  To encourage an email client to label the file as
text/plain, if you don't have direct control over this, give it a name
of "something.txt".

Re: [PROPOSAL] Change of convention for multiline string literals

Posted by Jonathan Gilbert <o2...@sneakemail.com>.
At 01:26 AM 4/22/2007 -0500, Peter Samuelson wrote:
>[Jonathan Gilbert]
>> +/**
>> + * A shorter version of APR_EOL_STR; holds the native linefeed for the
>> + * current platform. E.g., on UNIX systems, this will be "\n", while on
>> + * Windows, it will be "\r\n". This is defined privately because the
>> + * macro lacks a namespacing prefix. Used to terminate lines in large
>> + * multi-line string literals.
>> + */
>> +#define NL APR_EOL_STR
>
>IMHO there is no need to use /** here; that's for extracting API
>documentation from source files, and NL is not going to become part of
>any API.

Ah, I wasn't aware that /** had special meaning.

>Indeed, I'm not sure I would document it at all: if anyone doesn't know
>what APR_EOL_STR is, they can look it up easily enough.  And, speaking
>only for myself, the first time I saw APR_EOL_STR in use it was pretty
>obvious what it was for anyway.

Perhaps a more brief comment, then?:

/* Used to terminate lines in large multi-line string literals. */

>> +   "This directory holds run-time configuration information for
>> Subversion"  NL
>> +   "clients.  The configuration files all share the same syntax, but you"
>>   NL
>> +   "should examine a particular file to learn what configuration"
>>   NL
>
>And you'll want to tell your email client not to wrap lines when you
>paste patches....

I *did* mention at the head of the inline patch that the attached gzipped
copy should be used instead for precisely this reason. I don't think my
e-mail client has such an option.

Jonathan Gilbert

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org