Re: Where to start?

From: Joe Peschel (jpeschel_at_no.spam.org)
Date: 02/16/04


Date: Mon, 16 Feb 2004 04:53:52 -0000


"Arthur J. O'Dwyer" <ajo@nospam.andrew.cmu.edu> wrote in
news:Pine.LNX.4.58-035.0402151856550.12058@unix44.andrew.cmu.edu:

>
> On Sun, 15 Feb 2004, Joe Peschel wrote:
>>
>> Michael Amling <nospam@nospam.com> wrote...
>> > Joe Peschel wrote:
>> >> "Douglas A. Gwyn" <DAGwyn@null.net> wrote...
>> >>>Joe Peschel wrote:
>> >>>
>> >>>>The usage has been changing? No, it hasn't -- at least not in
>> >>>>any well edited American periodical. What you've seen in the
>> >>>>computing community is likely the result of ignorance; technical
>> >>>>publications usually are poorly edited.
>
> [I don't find this to be the case. It's usually the non-technical
> publications -- local papers, Web pages, et al. -- that have the most
> mistakes. But that's irrelevant to anyone's point.]

I agree that small local papers and web pages have quite a few mistakes.
Take a look, however, at some of the "professional" cryptology papers
available on-line. Much of the writing, if not atrocious, is poor.

>
>> >>>No, it isn't ignorance. In fact I've had this discussion with
>> >>>very good tech writers.
>> >
>> > Douglas Gwyn is right. There's a niche of documentation where
>> > nothing
>> > extraneous should go between the quotation marks.
>>
>> I think that documentation might be better presented indented upon
>> the page.
>
> In some cases, you may be right.

Thank you. No one gave a specific example, so my suggestion isn't
appropriate in every case. It's far better to solve specific problems one
at a time.

> For example, were I to discuss the
> program fragment "if (x==42) { foobar(); } else { barfoo("quux"); }",
> it would be much less confusing to present the code as a block quote:
>
> if (x==42) { foobar(); } else { barfoo("quux"); }
>

Yes.

> This for two reasons, at least: firstly, because it solves the issue
> of what to do with literal quotes in the quoted material (the usual
> solution of alternating double and single quotes doesn't work for
> more than one level in plain text, and doesn't work at all for C
> code, in which ' and " mean different things); and secondly, because
> it makes plain where the quote begins and ends, without forcing the
> casual reader to scan back and forth for quote marks.
>
> [re: those who put commas outside of quotes]
>> >> Certainly, it is ignorance. Those you talked to are poor writers.
> <snip>
>
> This is not a valid conclusion from the evidence presented.

No one, so far, presented any evidence.

> How, pray tell,

Such diction! :-)

> is a technical writer supposed to discuss in ASCII text
> the different effects of the command-line options "-a", "-b", and "-,"
> on "myprog"?
> How is he to discuss the BF program ",-[+.,-]", or any
> other such example, without resorting to the common idiom of placing
> the quoted text in quotes and the un-quoted punctuation outside them?

An effective way to describe command-line options is to create a table
describing each option. No need for quotation marks at all.

>
> Now, this is a niche usage, as many people here have pointed out.
> But it is a usage whose niche is computer programming -- the subject
> of this newsgroup -- so you shouldn't be surprised to see it pop up
> here from time to time.

I know. It has popped up quite a bit, however, in Doug's prose lately.

>
> You'll never see a newspaper article intentionally contain
> sentences punctuated like this:
>
> Many teachers have never read "Hamlet", or Proust, or Dickinson.
>
> because that use of '"foo",' just looks really ugly in a proportional
> typeface. (I speak from experience.)

I know what you mean; I write for a living, too.

> It survives in plain-text
> media such as Usenet because it doesn't look half as awful in (e.g.)
> Courier font, and because while it's not ambiguous to write
> '"Hamlet,"', it can be ambiguous to write '"-a,"', as I avoided in my
> earlier example.
>
> Finally, one reason for the comma-outside-quote convention on Usenet
> is the prevalent use of pairs of special characters to simulate
> *boldface* or /italics/ in plain text. When a newspaper article
> references /Steppenwolf/, for example, it does not place the comma in
> italics (or, if it does underlining of book titles, it does not
> underline the comma).

I usually, but not always, try to use the hypertext code for italics when
referring on-line to book titles. In a manuscript, however, you designate
italics by a single underline. Newspapers often replace italics with
quotation marks.

> So Usenet idiom follows the same convention for
> // and **. Consistency then dictates that when using quotation marks
> to indicate special remove, rather than actual quotation (e.g., the
> way I write 'int' on Usenet), the comma is not placed inside "".
>
> And two final problems with Joe Peschel's suggested fix of placing
> all quoted material in block quotes: that would make it very difficult
> to discuss differences between the
>
> -a
>
> ,
>
> -b
>
> , and
>
> -,
>
> options to
>
> myprog

Again, just put information in a table.

>
> . Also, as you can see, it makes placement of commas still
> problematic. This is actually a problem currently in mathematical
> texts -- when we discuss a formula such as
>
> <big_complicated_formula>
>
> should we even bother with a comma? If we need a comma after
>
> <big_complicated_formula>,
>
> should it go inside the blockquote and risk confusing the reader,
> or should the comma go after the blockquote containing
>
> <big_complicated_formula>
>
> , and risk looking incredibly silly, sitting there by its lonesome
> at the beginning of the line? I know of no general solution to
> this problem, and my personal solution is usually to re-arrange the
> sentence appropriately, or else simply omit the comma as in the
> first of those three examples.
>
>
>> >>>The traditional usage is *illogical*, thus reasonably discarded
>> >>>when it starts to cause problems, as it did in some earlier
>> >>>computer documentation.
>
> [Now, with this assertion I disagree. Traditional usage is just
> as logical as the English language itself -- that is, not much, but
> it looks really nice. :-) ]
>
> -Arthur
>

I think most of your example problems can be solved be arranging the
information in tables. Thanks, however, for your concrete examples.

J

-- 
__________________________________________
When will Bush come to his senses?
Joe Peschel 
D.O.E. SysWorks                                 
http://members.aol.com/jpeschel/index.htm
__________________________________________


Relevant Pages

  • Re: Where to start?
    ... On Sun, 15 Feb 2004, Joe Peschel wrote: ... of what to do with literal quotes in the quoted material (the usual ... if it does underlining of book titles, it does not underline the comma). ... So Usenet idiom follows the same convention for // and **. ...
    (sci.crypt)
  • Re: How do I include quotation marks in a TOC field code?
    ... As for the commas inside/outside the quotes, ... >>> you use italics, ... >>> Microsoft MVP ...
    (microsoft.public.word.docmanagement)
  • Re: Basic Program to Import a CSV file
    ... Also if you then have quotes arround ... csv is more than just a string of comma delimited data, ... OPENSEQ CSVFILE TO SEQIN ELSE STOP ...
    (comp.databases.pick)
  • Re: Excel Save As Options
    ... Many times the item description has double quotes in it for inch ... separator character from a comma to a vertical bar, ... then tell Excel to export the data to a comma separated .CSV file. ...
    (microsoft.public.excel)
  • Excel Save As Options
    ... Many times the item description has double quotes in it for inch ... separator character from a comma to a vertical bar, ... then tell Excel to export the data to a comma separated .CSV file. ...
    (microsoft.public.excel)