ACAA Header
 

Ada Issue (AI) Format and Style Guide

This 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.
For Google Docs, be careful to eliminate any links to the RM or AARM (particularly draft RM versions). These can come along when cutting and pasting from the HTML versions of the RM and AARM. These include links to index entries, term definitions, and syntax. These tend to change the color of text (sometimes interfering with insertion and deletion markings), and potentially are different in each draft. They also can point at the local users hard disk (if they have a local copy of the RM) rather than a public website. Ensure any links that remain are significant to the text (not just something that happens to exist in the source) and link to public websites.

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 Wording

RM 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 RM

Cross-references to other parts of the RM are encouraged. An number of rules should be followed for cross-references:
  • Cross-references for a given concept should only occur once in each subclause. It is not necessary to put a cross-reference on each use of an unfamiliar term or concept. We expect that most readers will look at the majority of a subclause, especially if they are having trouble understanding a topic. However, we do not assume that readers have read other subclauses, even if they are adjacent.
  • Forward references to defined terms should have cross-references to the definition [usually of the form "(see xx)"]. Cross-references to terms defined previously in the RM are needed only if the term is unfamiliar or differs in an important way from the intuitive meaning. As noted above, there should only be one such cross-reference in each subclause (preferably near the first use of the term in the subclause).
  • Cross-references to other parts of the standard always should include the subclause number. (The @RefSecFullNum command should be used in the RM source). It should not include other information except as follows:
  • [A] For a reference to an entire clause or annex, the number or latter should be prefixed by "Clause" or "Annex" (Note: This should happen automatically as part of the @RefSecFullNum). The word "subclause" should not prefix the subclause number (it's mainly noise, almost everything is a subclause).
    [B] The command @RefSecFull includes the title of the annex, clause, or subclause along with the reference. This should only be used in three cases:
    • If the title of the subclause adds additional context to the cross-reference (such as the group of rules where an important rule is found). In particular, the title should not be given if the surrounding text includes the same information.
    • If the subclause number could be mistaken for a decimal number. That is never the case for parenthesized cross-references like "(see nn.nn)", and it rarely should be the case if the subclause number is prefixed with "in" (as in "given in nn.nn").
    • If there are a number of cross-references in the same paragraph or adjacent paragraphs that include the title for one of the other reasons, then they all should (otherwise, the ones that do not have a title are jarring).
    [C] The existing usage of cross-references does not always follow these rules. The older commands @RefSec and @RefSecNum may be used, and titles are overused by these criteria. One should follow the these rules rather than existing practice when creating new 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:
@@Literal @ => "@".
@}Literal } => "}".
@>Literal > => ">".
@ Hard space (non-breaking space). (The command is "@ ".)
@b{text}Boldface text.
@fx{text}Set the font to x for text:
x=A (Arial), x=C (Courier), x=T (Times).
@hrHard return (always put a line break here).
@i{text}Italicize text.
@snn{text}Set the font size to nn points. nn in 6 .. 49.
@tabInsert a tab.
@piThe Greek PI character.
@emdashGenerate a long dash.
@endashGenerate a shorter dash (but longer than a hyphen).
@lquoteGenerate a left single quote.
@rquoteGenerate a right single quote.
@unicode{num}Generate a Unicode character with code num.
@xyyyy{text}Text has format yyyy.
yyyy=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).
Directions for Corrigendum and Amendment documents:
@dpreplPartial replace "In paragraph xxx, replace:"
@dreplFull replace "Replace paragraph xxx:"
@dbyReplacement "By:"
@dinsaInsert after "Insert after paragraph xxx:"
@dinsbInsert before "Insert before paragraph xxx:"
@ddelDelete "Delete paragraph xxx:"
@dinstInsert text "The paragraph:"
@dinssInsert text "The paragraphs:"
@dinscInsert (sub)clause "Insert new clause:"
@dinslList insert "In the list in paragraph xxx, add:"
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).