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

[lib] Referring to \requires, \effects and others #1091

Closed
jlaire opened this issue Nov 21, 2016 · 2 comments
Closed

[lib] Referring to \requires, \effects and others #1091

jlaire opened this issue Nov 21, 2016 · 2 comments

Comments

@jlaire
Copy link

jlaire commented Nov 21, 2016

Function descriptions can contain elements introduced with \requires, \effects, \sync, etc., and in some places the standard text refers to these elements. It does this in several different ways.

  • 17.5.1.4p4 uses the same macros that are used to define these elements when mentioning them. This is a bit ugly because it includes the colon.

  • A couple of places use \synopsis{Effects} or \synopsis{Throws}, which looks very wrong because it's bold.

  • There's at least one instance of ``Requires''.

  • There's at least one instance of \emph{Returns}.

Visually, I like \emph the most, since it's rendered the same way as the definitions, but without the colon.

There are also many different nouns used when talking about these: at least element, paragraph, section, clause and subclause. I wonder whether clause and subclause are correct.

I can create a pull request making these consistent if someone decides which form to use. I think either the macros themselves (already used in many places, but come with the colon) or \emph would be best. I can leave the nouns as-is or replace uses of clause/subclause with element or section.

@jensmaurer jensmaurer changed the title [whole standard] Referring to \requires, \effects and others [lib] Referring to \requires, \effects and others Nov 21, 2016
@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 21, 2016

I'm fine with keeping the colon. We do the same when we explain how "[Note:]" and "[Example:]" are typeset.

That is, just use the \requires macro etc.

@jlaire
Copy link
Author

jlaire commented Nov 21, 2016

Thanks, I'll go with that.

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

2 participants