[utility], [bitset] Introduce a separate heading for the synopsis. #1213
Conversation
| @@ -40,7 +40,7 @@ | |||
| \indextext{\idxhdr{utility}}% | |||
| \indexlibrary{\idxhdr{utility}}% | |||
| \indexlibrary{\idxcode{rel_ops}}% | |||
| \synopsis{Header \tcode{<utility>} synopsis} | |||
| \rSec2[utility.syn]{Header \tcode{<utility>} synopsis} | |||
There was a problem hiding this comment.
I had thought about this, too, but until now no "Synopsis" section that has a numbered heading has an introductory paragraph. That's why I haven't made this change yet, I wonder if we need some more rewording.
There was a problem hiding this comment.
I don't follow. Before the change, we had an unnumbered "synopsis" not-quite heading directly under 20.9 "Class template bitset". With this change, we have the synopsis in a separate numbered section. In neither case is there an introductory paragraph. (For the paragraph that follows, we could move it directly under 20.9 as an introduction, if desired.)
There was a problem hiding this comment.
Right, with this change we would have a numbered section called "Synopsis" that does not start with a code block. That'd be new, and moreover it seems that all these introductory sentences don't really add any normative value. So maybe we could revise this on at a slightly larger scale?
There was a problem hiding this comment.
Ah, this is talking about <utility>, which somehow made it into the [bitset] patch. Sorry, I was confused.
There was a problem hiding this comment.
@tkoeppe: I like those introductory sentences. They add a bit of context for the unsuspecting reader. But maybe they're better of at level x-1 instead of next to the synopsis.
There was a problem hiding this comment.
Yeah, maybe -- I have never managed to make up my mind about this one. (And I have looked at this case before, and others awkward cases like <algoritms>.) Not sure what the best way is to present this.
There was a problem hiding this comment.
This interacts somewhat with #574. If we remove those "in general" clauses everywhere and move their contents to level x-1, the introductory sentence for <utility> can simply go at that level, too.
| @@ -5887,10 +5887,10 @@ | |||
| \end{example} | |||
| \end{itemdescr} | |||
|
|
|||
| \rSec1[template.bitset]{Class template \tcode{bitset}}% | |||
| \rSec1[bitset]{Bitsets} | |||
| \indexlibrary{\idxcode{bitset}}% | |||
There was a problem hiding this comment.
This change is fine, I'd gladly merge this on its own.
Partially addresses cplusplus#566.
|
Ok, I've moved the introductory comment for <utility> to the bottom of the synopsis. This is the same as for bitset. |
jensmaurer
changed the title
Partially addresses #566.