Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

How to format around a codeblock #5035

Closed
burblebee opened this issue Oct 19, 2021 · 2 comments
Closed

How to format around a codeblock #5035

burblebee opened this issue Oct 19, 2021 · 2 comments

Comments

@burblebee
Copy link
Contributor

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)

@burblebee burblebee mentioned this issue Oct 19, 2021
@tkoeppe
Copy link
Contributor

tkoeppe commented 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:

  • Inline: "Something something equivalent to f().g()." Code entirely engulfed by a regular sentence.
  • Terminal codeblock: "Equivalent to: [codeblock]". Regular sentence ends with colon, code has no further punctuation.
  • Codeblock as part of the text: "As if [codeblock] but any jump statement appertains to the containing statement." There's a mild problem here that we can't put punctuation like commas inside the codeblock, nor should we have one immediately after the codeblock, even though a comma might be called for. Try to avoid that situation if possible, but worst case we can drop the comma.

(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
Copy link
Member

Documented these general codeblock rules here: https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines#code-blocks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants