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

[std] Improve index by adding cross-references to defined terms #1939

Open
jensmaurer opened this issue Feb 24, 2018 · 5 comments
Open

[std] Improve index by adding cross-references to defined terms #1939

jensmaurer opened this issue Feb 24, 2018 · 5 comments
Labels
big An issue causing a large set of changes, scattered across most of the text.

Comments

@jensmaurer
Copy link
Member

jensmaurer commented Feb 24, 2018

Consider "odr-use": We're pretty good at sticking a cross-reference to [basic.def.odr] after each mention of the term, but the index still only lists page 27, where the term is defined.

Suggestion:

  • Introduce new macros \usedefn{term}{xref} and \usedefnx{term}{index-term}{xref}. They would render as term\iref{xref} and also put add an index entry for term or index-term, respectively.
  • We could make the index entry bold for the location where we define a term.
  • Replace all appearances of odr-use\iref{basic.def.odr} with \usedefn{odr-use}{basic.def.odr} etc.

Opinions?

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

Eelis commented Feb 25, 2018

This would be fantastic for cxxdraft-htmlgen! For turning uses of defined terms into links, I currently use my own big but incomplete patch that basically does the third step you mention. The suggested change would severely reduce the need for this patching.

@jensmaurer
Copy link
Member Author

Editorial meeting consensus: Yes, we want to do this. Optional: Have use of terms show they are defined terms somehow. \defn/x should write to a separate, non-displayed hidden index so that the section lookup can be made automatic. Investigate details to retrieve the section number from that hidden index. Use \term (once freed) for use of a defined term.

@zygoloid zygoloid removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Mar 16, 2018
@jensmaurer jensmaurer added the big An issue causing a large set of changes, scattered across most of the text. label Mar 21, 2018
@jensmaurer
Copy link
Member Author

@godbyk, I believe I need some LaTeX help here. Essentially, I want a macro \define{blah} that adds "blah" to some index such that another macro \use{blah} anywhere in the document can retrieve the section number where \define{blah} appeared. (Of course, \define{blah} will only appear once in the document per "blah". We want "blah" to be able to contain spaces, if that poses extra difficulties.)

@godbyk
Copy link
Contributor

godbyk commented Jul 24, 2018

@jensmaurer Happy to help!

Initially, it sounds like \label and \ref might be what you're looking for, but that may not be a complete solution. You could give them a try, though. Using \label{blah} (in place of \define{blah}) to add a hidden marker and then \ref{blah} (in lieu of \use{blah}) to get the section number. Similarly, \pageref{blah} will return the page number containing the label blah. You can't define the same label twice but it can be references any number of times.

By convention, we usually don't use spaces with labels. It can cause some problems in some obscure circumstances, but in the normal cases, should be just fine. The labels are case-sensitive.

If you want \ref{blah} to typeset something other than the section number, we can make that happen, too.

Can you give me an example of the input and desired output? I'd be happy to put the code together for you.

@jensmaurer
Copy link
Member Author

@godbyk: Thanks, that helps.
Except we first need to clean up Latex found 14 multiply defined reference(s), obviously.

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