Skip to content

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

Open
@jensmaurer

Description

@jensmaurer

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?

Activity

added
decision-requiredA decision of the editorial group (or the Project Editor) is required.
on Feb 24, 2018
Eelis

Eelis commented on Feb 25, 2018

@Eelis
Contributor

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

jensmaurer commented on Mar 16, 2018

@jensmaurer
MemberAuthor

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.

removed
decision-requiredA decision of the editorial group (or the Project Editor) is required.
on Mar 16, 2018
added
bigAn issue causing a large set of changes, scattered across most of the text.
on Mar 21, 2018
jensmaurer

jensmaurer commented on Jul 24, 2018

@jensmaurer
MemberAuthor

@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

godbyk commented on Jul 24, 2018

@godbyk
Contributor

@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

jensmaurer commented on Jul 26, 2018

@jensmaurer
MemberAuthor

@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

Metadata

Metadata

Assignees

No one assigned

    Labels

    bigAn issue causing a large set of changes, scattered across most of the text.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @Eelis@godbyk@zygoloid@jensmaurer

        Issue actions

          [std] Improve index by adding cross-references to defined terms · Issue #1939 · cplusplus/draft