Ada Issue (AI) Format and Style GuideThis page describes the overall format and meaning
of an Ada Issue, gives style advice for Ada Issues (and other Ada Reference
Manual related material), and gives details of some of the sections in an Ada
Issue. Note that Ada Issues are processed with a variety of tools that
create agendas, indexes, Corrigenda, and other documents, so most deviations
from the specified format cannot be tolerated.
The following topic areas are covered here:
Format and Meaning
An AI is a series of header tags, in a specified order. It is organized as
three parts: a header that consists only of header tags, a body that
consists of a series of header tags separating text, and an appendix that
contains free-form correspondence about the AI.
Header tags are formatted as a line starting with a '!' and a keyword; no other
lines in an AI should start with '!'. The tags should always be given in an AI
in the order that they are defined below.
!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 AI number/version. 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.
The date of construction of the AI is used in the
initial !standard line. The /01 after the AI number is the version. It and the
associated date should change for any significant changes other than mail
filing in the !appendix.
!reference (not currently used by any tools) can give the sections in other
relevant standards (like Ada for ASIS) or other AIs.
!class is followed by the AI classification and the date that that
classification was assigned. There is only one !class line; if the
classification is changed, the line is changed with a new date. The classes
are defined in the ARG procedures. Common classifications include
"presentation", "confirmation", "ramification", "binding interpretation",
and "amendment".
!status specifies the status of the AI. There
are multiple status lines, one
for each status change, with the newest status changes toward the begining.
There is one special rule: a status line indicating the document that the AI
belongs to (such as "Corrigendum 1-2022") always comes first. The date of
a status change is given in each change, with the exception of the initial
"received" line - this uses the date of the initial comment (if known).
Status changes that involve a vote (such as ARG Approved) include the vote
between the status name and the date, in the form For-Against-Abstain.
Statuses are defined in the ARG procedures; common AI status lines include
"received", "work item", "ARG Approved", "No Action", "Hold", "Deleted", and
"WG9 Approved". Every AI should include a "received" status line.
!priority is Critical, High, Medium, Low, Very_Low.
!difficulty is Easy, Medium, Hard.
!qualifier is used only for Binding Interpretations,
it is Omission, Error, or Clarification (this is for ISO purposes, these are the
only reasons to fix a standard.)
The !subject tag is required, it is followed (on the
same line) with a short description of the topic of the AI. The Subject is
formatted as all lower case (except the first letter and proper names); it
should not have a period at the end (but a question mark is allowed when
appropriate). The Subject needs to be short (under about 60 characters);
shorten it if it is longer than that.
The !summary tag ends the header; it's required. It is
followed by a short summary of the AI. It must stand-alone; it must NOT refer
to other parts of the AI.
The !issue tag precedes a brief description of the
issue that the AI addresses; it is required of all AIs.
The !recommendation tag precedes a description of the
solution to the issue. It should not include wording changes. If the summary
is sufficient to explain the solution, use "(See summary.)"; do not repeat the
summary text.
[Note: For Ada 95, 2005, and 2012 AIs, we used tags
that differed for each classification of AI, instead of !issue and
!recommendation. For reference,
we give a brief description of these tags. For such AIs, the tags of !question
and !recommendation were required for Binding Interpretation AIs and
Presentation AIs. The tags !problem and !proposal were required for Amendment
AIs. The tags !question and !response were required for Ramification and
Confirmation AIs.]
A !wording tag is required except for AIs of classes
Ramification and Confirmation. When !wording is given, it should be followed by
detailed wording changes formatted as described elsewhere in this document.
!Wording is not allowed for a Confirmation AI -- if wording is needed, the
AI has the wrong classification. !Wording for a Ramification AI is optional,
and if present, it may contain only non-normative wording, such as
notes, Redundant text, and AARM notes.
Every AI should have a !discussion section. Most AIs
should have an !example section; it can be omitted if there really is nothing
to demonstrate, but
that should be rare (mainly in presentation and confirmation AIs). If the
discussion or example is given elsewhere, use a "(See <other part>.)" body,
do not omit the section.
We also use !corrigendum tags (to give formatted
wording updates for documents). There can be as many of these as necessary (one
per changed paragraph). If there are normative wording changes and the AI is
approved, there should be equivalent !corrigendums given for the wording. We
allow these to be omitted in AIs in Work Item status, as formatting wording
that is not yet settled is just extra work. The markup language is described
below.
An !ACATS Test tag is used give information about the
impact on ACATS. It is always allowed, and it is required for all AIs except
for AIs of classes Ramification and Confirmation. [Note: It was not required
for Ada 95 and Ada 2005 AIs.]
An !ASIS tags gives information about the impact on
ASIS. It was optional for Ada 2005 AIs and required for Ada 2012 AIs. It is not
used in Ada 95 AIs nor in Ada 2022 AIs.
!appendix is required; it marks the start of
correspondence on the subject of the AI. It also tells the tools to stop
reading (the correspondence following is not in any format, and may even
include parts of an AI including AI tags, so all kinds of bad things could
happen if it was read). Each individual message is followed by a line of stars.
Messages are identified by the author and date, by message headers if possible,
and by an added header if not. If there are no messages, just follow the
!appendix with the line of stars.
AIs can be formatted in plain text or in HTML (via Google Docs). AIs for Ada 95,
Ada 2005, and Ada 2012 are always formatted in plain text.
More modern AIs (for Ada 2022 and later) are formatted in HTML and are created
in Google Docs. A template is available in the active AI Google Docs repository
at https://arg.adaic.org/ada-interpretations;
it should be used to create new AIs (never from scratch). A tool is then used
to convert the Google Docment as exported in HTML into the AI format (the AI
format uses a fixed style sheet to keep a consistent style and keep differences
from editing to a minimum).
Content Rules
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 strongly recommended for the recommendation to reference the summary, as opposed to the summary referencing the recommendation; but we allow the latter in the case where the recommendation depends on the issue in order to be understandable (which ought to be avoided when possible, but not to the point of making it harder to understand).
For text files, lines longer than 80 characters should be broken before 80
characters unless it is Ada code that needs to be longer to illustrate a point.
For Google Docs/HTML files, only break between paragraphs.
Never use "ARM" or "RM95". For Ada 2022 AIs and later, use "RM" or (better)
"Reference Manual". In older AIs, always say "the standard" rather than "RM".
Never use "Ada 2022" (or whatever the current version of Ada is), just say "Ada".
Use of earlier versions are OK: "Ada 83", "Ada 95", "Ada 2005", and
"Ada 2012" are OK presuming you are talking specifically about a previous
version of Ada.
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; do
not prefix RM references with RM.
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" (oe "designated")
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:" the wording is a
complete replacement. Change brackets should never appear in replacement wording.
If the text is syntax rules or an example
containing aggregates, always use a full replacement (this avoids confusion
in the meaning of '{', '}', '[', and ']'). 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.)
In the issue section (question in AIs for Ada 2012 and before), short
answers are allowed to questions (which must end in a question mark).
These are formatted in parens, with a period [(Yes.) not (yes) or (YES)].
Answers are always optional; answers of more than 3 or 4 words should be
omitted completely.
Rules for English Text
These rules apply to text in all AI sections (except of course in e-mail in
an !appendix, such e-mail is recorded as received other than to reduce
redundant quoting). They also apply to Ada Reference Manual text, and even to
comments in examples. They do not apply to code in Ada or another programming
language (outside of comments).
American spelling is used. If in doubt, the
spelling used in Webster's Third New International Dictionary of the English
Language is used.
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 a modifier for
a following word. 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 Ada Reference Manual 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.
Following the above, in new text, we write "runtime",
not "run-time". The RM is split almost 50-50 between these spellings; we change
them when we can. However, "compile-time" is considered a pair of words and is
always written with a hyphen when it is a modifier.
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.
Possesives should be avoided for inanimate objects (like language constructs).
Don't say "the table's leg" but rather the "the leg of the table". More
relevantly, don't say "the subprogram's parameter" but rather "the parameter
of the subprogram".
Additional Rules for RM WordingRM Wording should be worded in accordance with the
latest JTC1 directives, and ought to follow the informal ISO interpretations
of those directives. These rules have changed substantially beginning in
2018, and some wording that was recommended in the past are no longer allowed
at all. Note that these rules only apply to RM wording; AARM notes just need
to follow the rules in the previous section. A brief summary of the rules as of
the 2021 version of the directives follows.
Requirements use "shall" preferably, or phrases
involving forms of "require", "has to", or "it is necessary". Other words should
not be used to express requirements. (But keep in mind that definitions are
not requirements; definitions usually use "is".) Negative requirements are
allowed, using "shall not" and similar forms.
External requirements, such as government laws, use
"must". We use "must" in respect to target constraints (that is, requirements
of the target hardware or software), but that usage should be rare.
Recommendations use "should" preferably, or phrases
involving forms of "recommend" or "ought to". Negative recommendations are
allowed, using "should not" and similar forms. Note that recommendations are
mainly Implementation Advice in the RM.
Permissions should use "may" preferably, or phrases
using forms of "permit" or "allow". "Might" is not allowed in this context.
Negative forms are not allowed (no "may not"); permissions must be positive.
A quote: "Rather than using negative permissions, either rewrite the sentence
to state what is permitted, or rewrite as a requirement/recommendation not to
do something." Prior to 2018, "need not" was recommended for negative
permissions, and that form used to occur frequently in the RM. That is no
longer allowed; do not use "need not" in new text. Permissions are mainly
found in Implementation Permissions in the RM; other text often should be
using a form of possibility instead (see the next paragraph).
Possibility should use "can", or phrases using forms
of "able" or "possible". Negative possibilities use "cannot", "unable", and
"impossible". Be careful, because one often wants to say that there is a
possibility that something does not happen, that is NOT a negative possibility
(which is the case that something is not possible). Most non-normative material
(like notes) should be using some form of possibility.
The words "could", "might", and the phrases "need to"
and "need not" should not appear anywhere in the RM. They are not allowed
in any of the forms above, and can easily be condused with them. The words
"shall", "should", and "may" (and their synonyms as noted above) should not
appear in any non-normative material (notes, examples, and so on). The word
"must" may only be used for external requirements as described above; this
usage is very rare in the RM, so any occurrence of "must" should be considered
suspicious.
There does not appear to be any allowed wording
which allows the expression of definite consequences (as opposed to possible
consequences). For instance, one would say that "a type conversion can raise
an exception" to express that a possible result of doing a type conversion
is an exception being raised (Ada 95 used "might" for this frequently). But
finding wording for consequences that always occur is difficult. For runtime
events, "will" can be used: "A relative delay statement with a positive time
will always result in blocking the current task." If "will" does not work,
however, most other wording runs afoul of the other other requirements. Hopefully,
this will be fixed in a future Directives.
Cross-references in the RMCross-references to other parts of the RM are encouraged.
An number of rules should be followed for cross-references:
Corrigendum Section Markup
Corrigendum Sections (each starts with !corrigendum) use a simple markup
language to specify what will appear in a Corrigendum or Amendmant document.
(Note that Ada versions that are ultimately revisions still create an Amendment
document; we have tools to compare that document to the consolidated RM in order
to find errors in both AIs and the RM text.)
For Ada 95, 2005, and 2012 AIs, these codes use angle brackets "<" and ">"
instead of "{" and "}". (Angle brackets must be encoded in HTML so we changed
to curly brackets to minimize needed encoding.)
General formatting markup:
Directions for Corrigendum and Amendment documents:
For the above, xxx is the paragraph number given
with the !corrigendum command). The above are used by giving the initial
direction with the xxx first, followed by the original or anchor paragraph
text, followed by a second direction with no xxx, finishing up with the
new or replacement paragraph(s).
|