Skip to content

Q & A

Jump to bottom
burblebee edited this page Nov 27, 2018 · 16 revisions

  • Q. When to use \term{} vs. \defn{}?

  • A. \defn adds an index entry, \term doesn't. As a general rule, all definitions in the spec should be indexed, and common terms or terms that are referenced outside of the immediate vicinity must be indexed. Therefore \term{} should be avoided except when defining a term that is only used locally. There's also \defnx{name of term}{index entry} if the name of term and the index entry should be different. For instance:

    \defnx{point of instantiation}{instantiation, point of}

  • Q. How does \impldef{} work and when to use it?

  • A. \impldef does two things. First, it expands to the words "implementation-defined". Second, it adds an entry to the index of implementation-defined behaviors at the very end of the standard. (The content of that index entry is the text between the braces.)

  • Q. I noticed some things were added to the index while others were not – when should something be indexed?

  • A. Whenever it'd be useful to find something in the index, we should add an index entry.

  • Q. In CWG1750, we have “reference to possibly cv-qualified T”; why whole phrase in "s here?

  • A. This is the standard's "internal representation" of types, after the algorithm in [dcl.meaning] converts a declarator into the represented type. See the subclauses of [dcl.meaning] for examples. In LaTeX, these "s should be created using `` and '' as the delimiters (double-backtick and double-apostrophe).

  • Q. In CWG609,

         “For a type \cv\ \tcode{T},”

    Why isn’t this “\tcode{cv T},”?

         “of that type are those denoted by \cv.”

    Is “\cv” some special thing in the std?

  • A. We use \cv{} to get an italicized 'cv'. This is a special notation in the standard, see [basic.type.qualifier]p5. You should always use \cv{} to get the spacing with the following text correct. If you need 'cv1' and similar, use \cvqual{cv1}.

  • Q. cv in cv-unqualified is sometimes in italics, other times not (eg. 20.4.2.5). Which is right?

  • A. The 'cv' in 'cv-unqualified' should never be italics. For instance:

       An expression of type cv T can be converted to cv-unqualified T

    The first 'cv' should be \cv{} (as a placeholder), thus italicized; the second is just part of the word 'cv-unqualified', which is an adjective to 'T'. Note that the 'cv-unqualified' in the example is redundant, because the introduction of 'T' with 'cv T' makes it clear that the cv-qualification of the type in question is considered separately. 20.4.2.5's uses of cv-unqualified should not be italicized.

  • Q. What are "overfull hbox" warnings and how to you fix them?

  • A. This means that LaTeX was not able to add a linebreak to prevent text flowing into the right margin. This usually happens when a line contains a long chunk of text using \tcode. The easiest way to find them is to change the document class option final (in std.tex) to draft, which will show a black box in the right margin wherever the text runs into the margin: createdir

    There are a few ways to fix them, not all are appropriate or possible in all cases:

    • Extract inline code into a code block.
    • Insert discretionary break points between tokens using \brk, like \tcode{CreateDirectoryExW(\brk{}existing_p\brk{}.c_str(), p\brk{}.c_str()[...].
    • Insert hyphenation hints to break up a word like \tcode{Copy\-Constructible}.
    • Rephrase the wording so the block of \tcode text is in the middle of the line.
    • Split the block of text into pieces, e.g. change "If \tcode{foo_v<T> && bar_v<T> && (baz_v<T> || !xyzzy_v<T>)} is \tcode{true}" to "If \tcode{foo_v<T>} is \tcode{true} and \tcode{bar_v<T>} is \tcode{true} and \tcode{baz_v<T> || !xyzzy_v<T>} is \tcode{true}".

    Do not force a linebreak (using \\) or manually split the \tcode on token boundaries (for instance, \tcode{very_long_foobar_function(} \tcode{very_long_argument_to_foobar}) since that will result in undesirable output if the paragraph is reflowed (a premature linebreak in the former case and an unwanted space inside a code unit in the latter case).

    Extended discussion can go in Issue #693.

  • Q. How should "..." be coded when representing a list of arguments, as in C<A1, A2, ..., An>?

  • A. This is a mathematical ellipses rather than a code ellipses, so it should be either \ldots or \cdots; we tend to use \cdots in contexts such as this where there could otherwise be confusion with actual ellipses and parameter packs. So in this case, it should be coded as \tcode{C<A$_1$, A$_2$, $\cdots$, A$_n$>}.

Clone this wiki locally