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

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

Open
zygoloid opened this issue Mar 20, 2017 · 6 comments
Labels
big An issue causing a large set of changes, scattered across most of the text.
Milestone

Comments

@zygoloid
Copy link
Member

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

@zygoloid zygoloid added the big An issue causing a large set of changes, scattered across most of the text. label Mar 20, 2017
@jensmaurer
Copy link
Member

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
Copy link
Member

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

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Mar 20, 2017
@AlisdairM
Copy link
Contributor

AlisdairM commented Mar 20, 2017

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.

@zygoloid zygoloid removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Nov 7, 2017
@zygoloid zygoloid added this to the C++20 milestone Nov 7, 2017
@jensmaurer
Copy link
Member

@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 jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Apr 3, 2018
@jensmaurer
Copy link
Member

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.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Jun 7, 2018
@Eelis
Copy link
Contributor

Eelis commented Dec 2, 2018

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

@zygoloid zygoloid modified the milestones: C++20, C++23 Mar 12, 2020
@jensmaurer jensmaurer modified the milestones: C++23, C++26 Oct 23, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
big An issue causing a large set of changes, scattered across most of the text.
Projects
None yet
Development

No branches or pull requests

4 participants