Version 1.1 of acs/ac-00316.txt

Unformatted version of acs/ac-00316.txt version 1.1
Other versions for file acs/ac-00316.txt

!standard 1(1)          19-02-01 AC95-00316/00
!class presentation 19-02-01
!status received no action 19-02-01
!status received 19-01-18
!subject Two spaces are better (?) than one
!summary
!appendix

From: Tucker Taft
Sent: Friday, January 18, 2019  9:46 AM

>...
>
>>It goes without saying that I had to delete a bunch of extra spaces after
>>periods. :-)
>
>I hope I get some credit for being consistent... ;-)

Please check out this article:

  https://www.theatlantic.com/science/archive/2018/05/two-spaces-after-a-period/559304/

Us old fogies actually had a reason for wasting all of that space after periods
(aka "full stops"!).

***************************************************************

From: Jeff Cousins
Sent: Friday, January 18, 2019  10:48 AM

I was taught double spacing (a bit like Ada versus C - slightly longer to write
but easier to read), "race conditions," not  "race conditions", indent new
paragraphs, and "full stops" not 'full stops' (most English people have changed
to the latter whereas most Americans still use the former I believe). It's the
kind of split that crossed the usual party lines and causes a disproportionate
amount of anger, a bit like Brexit.

***************************************************************

From: Randy Brukardt
Sent: Friday, January 18, 2019  3:13 PM

>Us old fogies actually had a reason for wasting all of that space after
periods (aka "full stops"!).

For the record, I too was taught to use two spaces after a period. However,
there was software that caused problems with that (more below), so I tended to
use one or two depending on how I was feeling and/or which document I was
working on. When I started this job, people complained a lot about double
periods in AIs and other ARG documents, so I had to retrain myself to avoid them
(there being no reason on modern computers/software to use them). When I
complain about that, I'm just trying to avoid having to fix those after the fact
because someone else does complain.

Bob wrote in a message that he apparently didn't want some of you to see :-)
:

>If someone could explain to me the harm the 2-spaces does, I'd be grateful.

>Especially if the explanation makes sense.  ;-)

You mentioned word processors. Not all of them are smart enough to properly
apportion the spaces. The photo typesetter we used for our early manuals had a
major problem with that - if you double spaced after a period, it put *all* of
the extra space there. Which led to text like:

    ...shall not use "others".                Otherwise, pestilence will occur.

That wasn't quite what we were hoping for when we avoided using a dot matrix
printer for the manual.

I note that at least some modern word processors seem to be dumb in this regard.
They ought to put more of the space after a period than anywhere else, but it
seems to be distributed randomly instead. Which leads to less space after a
period than after anything else.

As far as the harm in fixed space text, it's marginal but real: you get more
text on a fixed-length line when you don't double space after periods. For
programming in particular, that can help readability by keeping large comments
shorter (and inside of the text window!). (A comment that takes up four lines
instead of five lets the more of the actual code be seen.)

Not sure there is an real harm in AI text, other than keeping the number of
complaints I get down.

P.S. Tucker, I haven't been passing on the editorial complaints from a certain
editorial reviewer about putting periods inside of quote marks. That is,
something like:

        ...shall not use "others." Someone will be unhappy.

This particular reviewer has me changing those all over various AIs written by
you. So I could find plenty of other things to complain about if I was just
looking to complain. :-)

***************************************************************

From: Tucker Taft
Sent: Friday, January 18, 2019  8:46 PM

Does this particular reviewer want the periods inside or outside the " ... "?  I
generally put them inside (since that is what I was taught), but I realize in
some cases where we are quoting a piece of syntax that is a bit weird.  What
rule does this reviewer want enforced?  Unlike the two spaces after a period, I
am willing to try to follow a more complicated rule for commas and periods and
quotes.

***************************************************************

From: Randy Brukardt
Sent: Friday, January 18, 2019  9:03 PM

This reviewer wants the punctuation outside unless it is part of the quoted
text. As a programmer, that's the rule that makes the most sense to me, too. You
don't write:

             Name := "Randy;"

:-)

***************************************************************

From: John Barnes
Sent: Sunday, January 20, 2019  10:07 AM

Here is some chatter after Sunday lunch. My thoughts on this topic, mostly
from Addison Wesley are attached.

I tried to read the article from the atlantic.com but it required some
permission stuff so I didn't.

***************************************************************

From: John Barnes
Sent: Monday, January 21, 2019  3:12 AM

I tried to send a paper I knocked up to the ARG list but it didn't seem to work.
At least I didn't get a copy.  So here it is as raw text.
[It needed to be approved for distribution, and John couldn't wait until a
weekday for that to happen - Editor.]

The rules I use are those I got from Addison-Wesley (A-W) when I started to
typeset my books myself. That was with Programming in Ada 95. They made a cock
up of the last version of the 83 book so I took to doing the typesetting myself.

The main topics are spaces, strings, commas, and hyphens. But also z versus s
etc.

Spaces

I used to put two spaces after each sentence. I got a hard ticking off from A-W
for that. Certainly in the old days when typesetting with individual bits of
lead type, double spaces were not used. It seems that the introduction of the
typewriter with uniform font width triggered the change to double spaces between
sentences. It may be that since some letters such as i or l were thin and had a
lot of space around them made the presence or absence of a deliberate space
somewhat uncertain. So to make sure one put two spaces between sentences.

But the rule these days is only single spaces.

It is of course ironic that our AIs are txt files in Courier which is a uniform
font. If you look at books from before the war we find that spaces abounded.
There was always a space before a question mark, exclamation mark, colon, and
semicolon. Only stops (periods) and commas did not have a space before them.

Another important point is that typesetting programs (such as the elderly
QuarkXpress that I use) defines several other different spaces anyway.

A punctuation space (ctrl shift space) is the width of a period.
An en space (ctrl shift 6) is the width of n. Usually also the width of digits.
An em space (ctrl shift =) is the width of m.

A plain space is less than an en space. I often use en spaces.

Strings

The question is whether a stop or comma following a closing quote should be
moved into the string. Thus do we write

style A. The following string has 6 characters "rabbit".
or
style B. The following string has 6 characters "rabbit."

It is pretty clear in this context that B is very strange since the string now
has 7 characters.

British publishers have used A for many years. US publishers often use B as I
discovered one day in 1995 when visiting Alsys in California and talking to
someone about stylistic matters. I was actually quite amazed.

However, typesetters in Britain would probably have used B before the war. One
just reads without noticing. So why was it done? It was clearly felt to be more
elegant. It may have had something to do with typesetting speech in novels. What
else were strings used for? Programming hadn't been invented so quoted stuff was
mostly speech.

Suppose John says "O shit, I hate ******** Brexit."

Note that John has a comma and a stop in his speech. When writing a novel, we
need to put said John somewhere. If it is a long sentence then we don't want to
wait to the end to find out who said it so perhaps we write

"O shit," said John, "I hate ********* Brexit."
And the comma and stop are inside the quotes. Voila!!

But when talking about Ada strings and quoted text in general, we need to put
the stop outside the string.

I feel very strongly about this.

Commas

This is another contentious topic. In a list of items do we write

style A. ... ape, bear, cat, and dog.
or
style B. ... ape, bear, cat and dog.

I think it's fair to say that style A is normal in the US whereas style B is
dominant with British publishers except Oxford. Indeed the comma before "and" is
often called the Oxford comma.

I used to use style B (I think Programming in Ada 2012 is like that.) But these
days I have switched to A when I remember (as in Nice Numbers).

The arguments revolve around the question of how to distinguish when individual
items have "and" in them such as in.

The food available is fish and chips, bacon and eggs, and sausages and mash.

Hyphens

This topic is a mess. US publishers use more hyphens than British.

Fowlers Modern English Usage is really against hyphens. Some new words are born
with hyphens and then lose them. Thus originally cock-tail was hyphenated but is
now a consolidated word.

70 years ago today and tomorrow were written as to-day and to-morrow, So there
is a trend to lose hyphens. I was in Boston once and was amazed to see that the
Boston Globe referred to young people as teen-agers.

Fowler quotes a "spare room heater" as a good example. Is it a heater for the
spare room or is it an extra heater for rooms in general. US practice mght be to
use hyphens thus: spare-room heater or spare room-heater. British might use
spareroom heater and spare roomheater.

It seems difficult to be assertive over this topic.

Z and S and C

Optimize is correct. it comes from the Greek zeta. But the slovenly Brits took
to using optimise around 1980. Corrupted by the French.

Another interesting topic is pairs such as practice and practise, and licence
and license. British English uses s for a verb and c for a noun. I believe that
US approach is to make noun and verb the same. Thus License is always with s but
Practice is always with c. (I think.)

Note that some pairs are pronounced differently such as in "some advice" (noun)
and "to advise" (verb).

***************************************************************

From: Tucker Taft
Sent: Monday, January 21, 2019  6:40 AM

Excellent!  And very helpful... ;-)

***************************************************************

From: Randy Brukardt
Sent: Monday, January 21, 2019  3:13 PM

> Excellent!  And very helpful... ;-)

Yes. Note that with reviewers like John (who likes to write me notes like this
one on whatever topic he notices in the AI he's reviewing), I have a good reason
for trying to adhere to these rules myself.

Kiyoshi used to complain every time that someone wrote "See !discussion."
instead of "(See discussion.)". Among other things that he wanted to be
consistent.

***************************************************************

From: Randy Brukardt
Sent: Monday, January 21, 2019  3:29 PM

I took this opportunity to refresh the AI style guide and write down the rules that John just described. I've been following them for years, but they might as well to included in the style guide. Note that the style guide was mainly written for me, but per
haps the rest of you would like to see it. So it follows.

            Randy Brukardt, ARG Editor.

===============================================

AI formatting rules:

This document is a short AI style guide. (These rules have been used in
formatting AIs since Corrigendum 1 for Ada 95. Various rules have been added in
succeeding years.)

Titles: All lower case (except the first letter and proper names), no period
    (but a question mark is allowed).

Answers:
    In the question section, short answers are allowed. These are formatted
    in parens, with a period [(Yes.) not (yes) or (YES)]. Answers of more than
    3 or 4 words should be omitted completely.

If a section refers completely to another, it should say:
    (See summary.)   or (See wording.)
(formatted as above.) The tools detect such sections and omit them from the
Defect Reports. It is preferable for the recommendation to reference the
summary, as opposed to the summary to reference the recommendation; but we allow
the latter in the case where the recommendation depends on the question in order
to be understandable (which ought to be avoided when possible, but not to the
point of making it harder to understand).

Never use "ARM" or "RM" or "RM95". Always say "the standard".

Never use "Ada 95": either say "Ada" or "the standard". Use of "Ada 83" is OK.

Always indent paragraphs quoted from the standard. Never use paragraph numbers
in these quotes.

Never mix RM and AARM references. Always prefix AARM references with AARM.

Never say "paragraph xxx" or (worse) "This paragraph".

Paragraph number ranges always use a dash: "13.14(10-11)", not "13.14(10..11)".
AARM references always include a dot (.) and both ends of a range are written
out: "13.14(11.a-11.b)", not "13.14(11.a-b)" or "13.14(11a-11b)".

Avoid using "pointed to" or "pointer type"; use "referenced" and "access type"
instead.

Avoid unfamiliar abbreviations: don't use "spec" (specification) or "typo"
(typographical error), for example.

For !wording sections, use the form "Modify <subclause(paranum)>:" if there are
change brackets ('{' and '}' for insertions, and '[' and ']' for deletions). Use
the form "Replace <subclause(paranum)> with:" if there are no change brackets.
If the text is syntax rules or an example containing aggregates, always use a
full replacement. Avoid showing only part of a paragraph, context usually
matters.

If one wants to mark a section of wording as redundant (which is marked with
square brackets in the AARM), use "Redundant[" to mark the beginning so as to
show the difference from a text deletion. When reasonable, include an AARM
Proof: note to explain where the redundant text is given normatively. (Not
necessary if it is in the same subclause of the Standard.)

---

General English text rules (applies to AIs everywhere, and to Standard text as
well, and even to comments in examples, but not computer code):

Always use one space after periods, not two.

If giving a list of three or more items, always use a comma before the combining
word: for instance "one, two, or three messages", not "one, two or three
messages". [John Barnes tells us this is known as the "Oxford comma".]

Hyphens should mainly be used when a pair of words is used as an adjective.
Otherwise, the words should be written with a space. Thus "two mode-conformant
parameters" and "two parameters are mode conformant if:". Made-up words
(including those starting with "non") should not have a hyphen, thus
"nonlimited". Note that the Standard is not very consistent with these rules, so
there may be cases where it is better to match the existing style, even if it is
wrong. Thus, we usually write "class-wide" rather than "classwide" even though
the latter would be preferred by the above rules.

Punctuation should not appear in quoted strings, unless an entire quotation is
involved. Thus,
  The following string has 6 characters "rabbit".
not
  The following string has 6 characters "rabbit."
But:
  John complains "I hate Brexit."
is OK.

----

About the header tags:

Note that we use the comment date in "received", and the construction date in
the other places. The /01 after the number is the version.

!priority is Critical, High, Medium, Low, Very_Low.

!difficulty is Easy, Medium, Hard.

!qualifier is used only for BIs, it is Omission, Error, or Clarification (this
is for ISO purposes, these are the only reasons to fix a standard.)

!standard is the section and paragraph number(s) in the (original) standard
concerned. There can be multiple !standard lines; only the first has the date
and number. *Every* wording change needs to be represented with a !standard
line; other lines can be given for related sections as well. These are
cross-referenced in the index in the web site, so they need to be accurate.

!reference (not actually used for anything) can give the sections in other
relevant standards (like Ada for ASIS).

The !summary tag ends the header; it's required. It is followed by a short
summary of the AI.

The tags of !question, !recommendation, and !wording are required for Binding
Interpretation AIs and Presentation AIs. The tags !problem, !proposal and
!wording are required for Amendment AIs. The tags !question and !response are
required for Ramification and Confirmation AIs; !wording is allowed (but not
required)) for Ramification AIs - the wording can only be AARM notes or other
non-normative material; !wording is not allowed for Confirmation AIs.

Every AI should have a !discussion and !example section. They can be omitted if
there really is nothing to say or demonstrate, but that should be rare (mainly
in presentation and confirmation AIs).

We also use !corrigendum tags (to give formatted wording updates for documents)
and !ACATS Test tags to give information about the impact on ACATS. !ASIS tags
give information about the impact on ASIS. The !ACATS Test and !ASIS tags are
required for Ada 2012 AIs.

!appendix tells the tools to stop reading (the stuff following is not in any
format, so all kinds of bad things could happen if it was read). So it's not
optional. If there is no mail, just follow it with the line of stars.

----

The formatting codes for the !corrigendum section:

        @@              - Literal @ => "@".
        @>              - Literal > => ">".
        @               - Hard space (non-breaking space). (The command is "@ ".)
        @b<text>        - Boldface "text".
        @fx<text>       - Set the font to x for the text:
                          x=A (Arial), x=C (Courier), x=T (Times).
        @hr             - Hard return (always put a line break here).
        @i<text>        - Italicize "text".
        @snn<text>      - Set the font size to nn points. 'nn' in 6 .. 49.
        @tab            - Insert a tab.
        @pi             - The Greek PI character.
        @emdash         - Generate a long dash.
        @endash         - Generate a shorter dash (but longer than a hyphen).
        @lquote         - Generate a left single quote.
        @rquote         - Generate a right single quote.
        @unicode<num>   - Generate a Unicode character with code num.
        @xyyyy<text>    - Text has format yyyy.
                        - yyy=Code (code, keep returns, indenting);
                        - Bullet (bullet, indented).
                        - Indent (indented).
                        - Hang  (indented, @xterm text hangs out).
                        - InBull (bullet, indented to fit in an indented list).
                        - I2Bull (bullet, indented to fit as a nested bullet
                                  in an Inbull).
                        - Term (part of Hang; must not contain any @X or
                        -     @Ds, ought to be short. Term on separate line).
                        - Terms (part of Hang; must not contain any @X or
                        -     @Ds, ought to be short. Term on same line, if possible).

     Specific to Corrigendum:
        @dxxxx          - Directions.
           @dprepl      - Partial replace "In paragraph xxx, replace:"
           @drepl       - Full replace "Replace paragraph xxx:"
           @dby         - Replacement "By:"
           @dinsa       - Insert after "Insert after paragraph xxx:"
           @dinsb       - Insert before "Insert before paragraph xxx:"
           @ddel        - Delete "Delete paragraph xxx:"
           @dinst       - Insert text "The paragraph:"
           @dinss       - Insert text "The paragraphs:"
           @dinsc       - Insert (sub)clause "Insert new clause:"
           @dinsl       - List insert "In the list in paragraph xxx, add:"

***************************************************************

From: John Barnes
Sent: Monday, January 21, 2019  4:47 PM

Gosh yes I remember Kiyoshi. Gosh there was one chatter about the use of
apostrophes.

I think I said that apostrophes should not be used with inanimate objects. Don't
say the table's leg but the leg of the table.

I seem to remember that I stressed this by actually saying:

"Don't say the table's  leg but the leg of the fucking table." which caused some
mirth.

A good example concerns legs of lamb.

The leg of lamb makes an excellent meal. The poor lamb's leg is broken.

***************************************************************

From: Randy Brukardt
Sent: Monday, January 21, 2019  5:25 PM

Gee, John, all of your mail is getting moderated because of the use of bad
words. That will definitely cause it to be delayed.

P.S. I expect this reply to get moderated, too.

***************************************************************

Questions? Ask the ACAA Technical Agent