index entries for library declarations should point at the declaration itself, not the start of the synopsis

[zygoloid]

This is particularly obvious for very long synopses. We generally write index entries at the start of the synopsis block, but we should really be pointing them at the point within the synopsis where the indexed entity is declared.

We probably need a new macro for marking up a library entity in a synopsis that adds an index entry and emits the name of that entity, so we can write something like:

int @\libdecl{myfunction}@(int, int);

to emit and index the name (with another form for member functions).

[jensmaurer]

For [string], we seem to create the index entries with the \itemdecl details, and not with the synopsis. That seems to be the preferable general approach to me. (I do understand that, in a few cases, we only have the synopsis entry and no \itemdecl. For these, I agree with the approach outlined above.)
@AlisdairM?

[jensmaurer]

@zygoloid: Do you think this is editorial cleanup that could / should be applied post-DIS, but pre-publication of C++17?

[AlisdairM]

IIRC, the reason I did not do this in my last indexing spree is that I don't know LaTeX well enough to handle all the un-escaping in an appropriate macro. My memory is that placing the index macro above the declarations in the synopsis created duplicate entries in the index. We get a similar problem with the container requirements and type traits tables, that actually provide the majority of the definitions for those clauses.

[jensmaurer]

@zygoloid: What exactly is the desired approach here? Put index entries next to the \itemdecl details (where \itemdecl is used at all), and for the remaining functions, implement your \libdecl suggestion to put index markers in the synopsis? Or annotate the synopsis only?

[jensmaurer]

Editorial meeting consensus: Index \itemdecl where they exist, and limit indexing of synopses to names only appearing there. Index entries for synopsis items should be inline. Add a special LaTeX macro (e.g. \libdecl) that adds the text to a code block and adds an index entry.

[Eelis]

I guess if we switch from makeindex to xindy (an option explored in #1917), its capabilities might help here, too.

For cxxdraft-htmlgen, having library index entries point to the actual declarations of the entities would be fantastic, because really, it's what people expect on a hyperlinked web page. :)