Skip to content

[utility], [bitset] Introduce a separate heading for the synopsis. #1213

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Dec 13, 2016
Merged

[utility], [bitset] Introduce a separate heading for the synopsis. #1213

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions source/utilities.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,12 +40,7 @@
\indextext{\idxhdr{utility}}%
\indexlibrary{\idxhdr{utility}}%
\indexlibrary{\idxcode{rel_ops}}%
\synopsis{Header \tcode{<utility>} synopsis}

\pnum
The header \tcode{<utility>} defines several types and function templates
that are described in this Clause. It also defines the template \tcode{pair}
and various function templates that operate on \tcode{pair} objects.
\rSec2[utility.syn]{Header \tcode{<utility>} synopsis}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Member Author

@jensmaurer jensmaurer Dec 13, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, this is talking about <utility>, which somehow made it into the [bitset] patch. Sorry, I was confused.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@jensmaurer jensmaurer Dec 13, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


\begin{codeblock}
#include <initializer_list>
Expand Down Expand Up @@ -250,6 +245,11 @@
}
\end{codeblock}

\pnum
The header \tcode{<utility>} defines several types and function templates
that are described in this Clause. It also defines the template \tcode{pair}
and various function templates that operate on \tcode{pair} objects.

\pnum
The type \tcode{chars_format}
is a bitmask type~(\ref{bitmask.types})
Expand Down Expand Up @@ -5886,10 +5886,10 @@
\end{example}
\end{itemdescr}

\rSec1[template.bitset]{Class template \tcode{bitset}}%
\rSec1[bitset]{Bitsets}
\indexlibrary{\idxcode{bitset}}%
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change is fine, I'd gladly merge this on its own.


\synopsis{Header \tcode{<bitset>} synopsis}%
\rSec2[bitset.syn]{Header \tcode{<bitset>} synopsis}%

\indextext{\idxhdr{bitset}}%
\indexlibrary{\idxhdr{bitset}}%
Expand Down Expand Up @@ -5924,6 +5924,7 @@
and several related functions for representing
and manipulating fixed-size sequences of bits.

\rSec2[template.bitset]{Class template \tcode{bitset}}%
\indexlibrary{\idxcode{bitset}}%
\begin{codeblock}
namespace std {
Expand Down Expand Up @@ -6049,7 +6050,7 @@
\indexlibrary{\idxcode{overflow_error}}%
\end{itemize}

\rSec2[bitset.cons]{\tcode{bitset} constructors}
\rSec3[bitset.cons]{\tcode{bitset} constructors}

\indexlibrary{\idxcode{bitset}!constructor}%
\begin{itemdecl}
Expand Down Expand Up @@ -6159,7 +6160,7 @@
\end{itemdescr}


\rSec2[bitset.members]{\tcode{bitset} members}
\rSec3[bitset.members]{\tcode{bitset} members}

\indexlibrarymember{operator\&=}{bitset}%
\begin{itemdecl}
Expand Down