Could you be a bit more specific about the aspects of the current formatting that you find ugly? How would you prefer it to be formatted?

Please see examples mentioned above. As explained, the numbered paragraphs in examples/effects/etc. make it look like the paragraphs aren't part of the examples/effects/etc. - don't you agree? It's especially bad for \effects (and similar clauses), where there is no "-- end example]" to clarify where the clause ends and paragraphs which aren't part of the clause begin.

So:

1. bla bla [Example:

   foo();
   

   bla bla

2. bla bla

3. bla bla -- end example]

Should instead be:

1. bla bla [Example:

   foo();
   

   bla bla

   bla bla

   bla bla -- end example]

This can be done in Latex by replacing the embedded \pnums with blank lines (unless someone can suggest another method please?).

Seems eminently sensible to me. Notes and examples should either be a paragraph of their own, or be wholly contained within one paragraph.

What about the effects/returns/etc. clauses? After a quick review, I'm not so sure about them anymore. There are so many cases of \pnums within these clauses that I'm thinking one is supposed to read them as being part of the previous clause?

I assume the paragraphs are only numbered to make it easy for people to cite them individually. (If there are other reasons, please let me know.)

So if it's reasonable to expect that no one would want to cite a paragraph in the middle of an example, note, etc., then I see no reason to number those paragraphs.

Now that we're using real environments for notes and examples, at least, we could even programmatically disable paragraph numbering within the environment scope.

I don't think removing paragraph numbers within effects/returns etc. elements would be an improvement. Removing the line breaks and paragraph spacing would definitely not help readability, and keeping the spacing but not numbering the paragraphs just makes it harder to refer to them.

I'll add that I generally find the examples easiest to read when they have their own \pnum, rather than appearing nested in the middle of normative text in a larger paragraph. I am neutral on whether large examples merit multiple \pnums, but would advocate that, as far as possible, each example /should/ have its own \pnum, and consecutive examples should each get their own \pnum.

An example of something described in a paragraph should be part of that paragraph. If an example applies to several previous paragraphs, then it should have its own \pnum. That said, for an example which belongs as part of a paragraph, we can add a blank line before the example so that the [Example: looks like a new but unnumbered paragraph. I think we should do that for large examples.

@godbyk I like your idea of not increasing the paragraph numbers inside examples and notes! Can we also have a \pnonum (or something) for this for use outside examples/notes? That way we could use it instead of blank lines to force a break in the text - the problem with the blank lines is that someone can come along and delete them, not knowing they were put there intentionally for formatting reasons. A \pnonum would make this explicit so another editor would make sure to leave it be. I don't know Latex well enough to do this myself - would you be able to do these two things? If you do them, let me know so I can go and add the \pnonums to some wording I've added recently that need it.

@jwakely As for the effects/returns etc., the problem I was trying to raise was that it's not possible to tell when a new paragraph is part of an effects clause, or is a new paragraph that happens to follow an effects clause.
For example, where do the effects end in the following? :

1. Effects: bla bla.
2. bla bla bla. This paragraph is part of the effects.
3. Let X be bla. This is a new paragraph introducing X for the paragraphs that follow.
4. Returns: X.

This makes it clear:

1. Effects: bla bla.
   
   bla bla bla. This paragraph is part of the effects.
2. Let X be bla. This is a new paragraph introducing X for the paragraphs that follow.
3. Returns: X.

It would be good to have a way to fix the issue above. If not by replacing \pnums with blank lines (or the new \pnonums), then how?

@burblebee I think something like the following would work. Modify these lines in macros.tex:

\newenvironment{note}[1][Note]{\let\pnum\par\noteintro{#1}}{\noteoutro{note}\xspace}
\newenvironment{example}[1][Example]{\let\pnum\par\noteintro{#1}}{\noteoutro{example}\xspace}

And add the following to define a \pnonum macro:

\let\pnonum\par

This \pnonum starts a new paragraph (the same way a blank line does) and so will insert the same interparagraph spacing.

To just insert a line break (without starting a new paragraph), use \\.

@godbyk Thanks! I'll make those changes after the post-Oulu WD is ready (so as to minimize merge conflicts). That resolves the problem with \pnums in examples and notes...

@ALL Do folks have opinions on what to do about the \pnums in effects/returns/etc. clauses issue, as demonstrated by the example in my previous comment? Do we want to use \pnonums instead of \pnums within such clauses? Any other ideas?

I like the idea of not continuing the numbers inside examples. I'm also strongly of the opinion that an example should be either wholly contained inside a paragraph, or be a paragraph unto its own.

I'd be happy not to use any macro trickery here and just use \par instead of \pnum, though I don't care strongly how you solve this.

On the general use of \pnum. I'm kind of getting the impression that the distinction between \pnum and a regular paragraph (whether introduced through a blank line or \par or equivalent) is getting lost.

Is \pnum being used explicitly to introduced a numbered paragraph or just as the de facto way of creating a new paragraph (and the numbered part may just be an unintentional side effect).

In LaTeX a paragraph ends and a new one begins when there is a blank line or when \par (or very occasionally \endgraf) appears. The \pnum macro should only be used to introduce a numbered paragraph.

A better solution (as opposed to the quick-fix redefinition of \pnum within the note and example environments above) would be to edit replace all uses of \pnum with a blank line (which I usually prefer) or \par (but please don't use \endgraf). To help in this endeavor, we could instruct LaTeX to emit a log file containing pointers to all the places where \pnum has been used within a note or example environment.

An alternative proposal. Instead of removing paragraph numbers within examples and notes, we could number them in the same way we do bulleted lists ((5.1), (5.2), (5.3), etc.). This would allow people to still reference an individual paragraph within an example/note but also make it clear that those paragraphs are still within the the example/note. This could be accomplished with something like the following (untested):

\newenvironment{note}[1][Note]{%
  \def\pnum{\parabullnum{Bullets1}{0pt}}%
  \noteintro{#1}}{\noteoutro{note}\xspace}
\newenvironment{example}[1][Example]{%
  \def\pnum{\parabullnum{Bullets1}{0pt}}%
  \noteintro{#1}}{\noteoutro{example}\xspace}

Typesetting effects, returns, etc. To enable more flexibility in the formatting of these, it might be useful to either change the \effects et al. macros to take the text as an argument or turn it into an environment similar to note and example. This would allow us to change the formatting of the text of each environment easily. Unfortunately, both of those options requires editing the source document extensively.

NB: I don't have a strong opinion on this issue; I'm just offering some options. I'm happy to help implement a solution for whatever the desired formatting should look like.

@tkoeppe Sure, we can use \par instead of \pnonum, but \pnonum does give us a little more flexibility if we decide to do something different with it. Either way is fine with me, so \par it is :).

@godbyk For creating unnumbered paragraphs, I prefer \par to a blank line because another editor might not realize the blank line was intentional white space and delete it (I've made this mistake myself).

As to whether folks are using \pnum where they should be using \par, I'd say "yes", but others may disagree. I think folks use \pnum everywhere because they are just following convention. If we start using \par, and come up with some guidelines are to when to use it vs. \pnum, folks will start following that convention.

I don't like the "alternate proposal", because most notes/examples are only 1 paragraph, so it would introduce extra noise (although your Latex writing skills are impressive! :) ).

I like the idea of having a \begin{clause} ... \end{clause} - it would allow us to see what belongs to the clause, giving us the option to treat embedded \pnums differently. However, I would make it an optional addition to the \effects, for use only when a clause contains multiple paragraphs (thus avoiding the extensive edits). So we'd have: ... \pnum \effects \begin{clause} para1 \pnum para2 \end{clause} .... That said, we'd still need to figure out how those embedded \pnums should be treated differently. :)

On the idea of an optional environment for the clauses: That may be fine as long as we don't need to do anything crazy (where having a scoped environment makes it easy to undo those settings at the end of the scope), but I'd worry we'd run into the same problem we have in C++ with if statements: it works fine if you only have a single statement, but when you add a second statement you must remember to add the braces. Sometimes people forget or are unaware of the need.

(That feels like a run-on sentence, but I'm hoping my punctuation saved me.)

After some thought, I'm not liking the optional environment idea so much either. I'll just tackle the examples and notes raised in this issue then. Do folks think it's worth opening a separate issue for the unsolved problem of \pnums in clauses?

Sorry, could you remind me what the issue of "\pnums in clauses" is?

@tkoeppe: (repasting from comment above):
... the problem I was trying to raise was that it's not possible to tell when a new paragraph is part of an effects clause, or is a new paragraph that happens to follow an effects clause.
For example, where do the effects end in the following? :

1. Effects: bla bla.
2. bla bla bla. This paragraph is part of the effects.
3. Let X be bla. This is a new paragraph introducing X for the paragraphs that follow.
4. Returns: X.

This makes it clear:

1. Effects: bla bla.
   
   bla bla bla. This paragraph is part of the effects.
2. Let X be bla. This is a new paragraph introducing X for the paragraphs that follow.
3. Returns: X.

It would be good to have a way to fix the issue above. If not by replacing \pnums with \pars, then how?

Ah yes, thanks. I agree, that's unfortunate and worth improving.

I'm not sure how, though. Unnumbered paragraph breaks might work. Or we could separate paragraphs not through whitespace, but with a pilcrow like in the olden days.

Is \pnum being used explicitly to introduced a numbered paragraph or just as the de facto way of creating a new paragraph (and the numbered part may just be an unintentional side effect).

Wait, what?

\pnum doesn't introduce a new paragraph, it just introduces a number. If you use it without a blank line then you get a paragraph number in the centre of the page!

Here's what happens if I try to introduce a new paragraph with \pnum before is_move_assignable (look at the word true):

i.e. \pnum is being used as intended: to add a number.

If you want a new paragraph, create a new paragraph. If you want a paragraph number, add a paragraph number.

@jwakely My question wasn't about what \pnum actually does but rather what the author's intent is when using it (trying to determine the author's mental model of what \pnum does and how it should be used).

Unless I'm overlooking occurrences, for notes this issue has now been resolved.

@zygoloid seems to agree \pnum inside notes (and, presumably, inside examples) is to be avoided. Better split the note in two independent ones.

Cases of \pnum in note environments:

• declarators.tex line 1160
• declarators.tex line 1187
• templates.tex line 7288

Cases of \pnum in example environments:

• basic.tex line 1847
• basic.tex line 1889
• statements.tex line 478
• declarations.tex line 3921
• declarations.tex line 3928
• derived.tex line 256
• derived.tex line 267
• derived.tex line 290
• derived.tex line 510
• derived.tex line 840
• derived.tex line 868
• access.tex line 143
• access.tex line 971
• templates.tex line 7523
• templates.tex line 7540
• templates.tex line 7556
• templates.tex line 7590
• utilities.tex line 445
• utilities.tex line 489
• locales.tex line 5547
• locales.tex line 5551
• locales.tex line 5557
• locales.tex line 5636
• iostreams.tex line 12070
• iostreams.tex line 12074
• iostreams.tex line 12080
• iostreams.tex line 13446
• iostreams.tex line 13459
• iostreams.tex line 14694
• iostreams.tex line 14732

I'm not touching [facets.examples]; this is scary.

A couple more examples with \pnums in them:
https://github.com/cplusplus/draft/blob/master/source/derived.tex#L493 (class.member.lookup#10)
https://github.com/cplusplus/draft/blob/master/source/derived.tex#L808 (class.virtual#12)

Looks like that took care of all the \pnums in note environments. Here are the ones I still see in the example environments:

• derived.tex line 512
• derived.tex line 842
• derived.tex line 870
• locales.tex line 5547
• locales.tex line 5551
• locales.tex line 5557
• locales.tex line 5636

If you want to throw a LaTeX error when someone uses \pnum inside a note or example environment, modify those environments the macros.tex file as follows:

\newenvironment{note}[1][Note]{\noteintro{#1}\def\pnum{\ClassError{std}{Don't use \string\pnum\space inside the note environment}{Consider splitting the note into two separate notes\MessageBreak or removing the \string\pnum\space and keeping the paragraphs.}}}{\noteoutro{note}\xspace}
\newenvironment{example}[1][Example]{\noteintro{#1}\def\pnum{\ClassError{std}{Don't use \string\pnum\space inside the example environment}{Consider splitting the example into two separate examples\MessageBreak or removing the \string\pnum\space and keeping the paragraphs.}}}{\noteoutro{example}\xspace}

LaTeX will then generate an error like the following:

! Class std Error: Don't use \pnum inside the example environment.

See the std class documentation for explanation.
Type  H <return>  for immediate help.
 ...

l.512 \pnum

?h
Consider splitting the example into two separate examples
or removing the \pnum and keeping the paragraphs.

@godbyk: Yeah, seems I missed those in derived.tex.

The others are in [facets.examples]; I won't be touching those. Please read that section yourself; I have serious doubts this section should exist in the standard in the first place.