Repository navigation
How to format around a codeblock #5035
Description
How should we format wording where a codeblock is used for an expression at the end of a sentence, e.g.:
Remarks: The expression inside explicit is equivalent to:
!(is_convertible_v<decltype(get<I>(FWD(u))), Types> && ...)
This isn't an effects clause, but let's keep the formatting similar (see "Writing Effects: in a function description" in https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines). That said, this would most closely fit the "Effects: Equivalent to expression." case, but appending a "." at the end of the codeblock might look a bit strange. So we could instead follow the multi-statement codeblock case which is introduced via "Effects: Equivalent to:", because we're not completing the sentence here. We could adopt whatever formatting is used most consistently elsewhere in the spec - what's that? I think we typically don't use a ":" when we can complete the sentence with more text after the codeblock, and use a ":" to introduce the codeblock otherwise.
We should come up with guidelines for how to format normative wording that contains a codeblock and add examples to https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines, something like:
Some wording that introduces a codeblock with no text afterwards:
expression_part1
expression_part2
Some wording that contains a codeblock
expression_part1
expression_part2
but has more text afterwards, so can be part of a complete a sentence.
We should also expand the guidelines for how to write \effects clauses to include these cases.
Originally posted by @burblebee in #5024 (comment)
Activity
tkoeppe commentedon Oct 19, 2021
This all seems reasonable, and I don't see how it could be any other way.
So just to recap, we have the following possiblities:
f().g()." Code entirely engulfed by a regular sentence.(All this is quite similar to how one would typeset mathematical formulas and equations in mathematical text, except that it is often quite doable to include textual punctuation at the end of displayed-maths.)
Finally, I don't think these rules should be limited to Effects: and Remarks:, they seem rather general -- the goal is simply to have complete sentences, and to take into account whether a piece of code reads more like a complete sentence or like a smaller phrase.
jensmaurer commentedon Oct 21, 2021
Documented these general codeblock rules here: https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines#code-blocks