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

Adding index cross-references for definitions where index entry is for a different term #2067

Closed
jwakely opened this issue May 11, 2018 · 13 comments
Labels
big An issue causing a large set of changes, scattered across most of the text.

Comments

@jwakely
Copy link
Member

jwakely commented May 11, 2018

We have:

A \defnx{trivially copyable class}{class!trivially copyable} is a class:

This defines the term trivially copyable class but adds an index subentry for "class, trivially copyable". That means "trivially copyable class" can't be found in the index!

We need to manually add that entry (see #2065 for that change):

\indextext{trivially copyable class|see{class, trivially copyable}}%

Is there any way to automate that through \defnx or some other macro, or at least make it easier? Maybe something like this (although it would need to replace foo!bar with foo, bar in #2):

\newcommand{\defnxx}[2]{\indexdefn{#2}\indextext{#1|see{#2}}\textit{#1}}
@godbyk
Copy link
Contributor

godbyk commented May 11, 2018

If we redefine \defnx as follows:

\newcommand{\defnx}[2]{%
  \indexdefn{#2}%
  \ifthenelse{\NOT\equal{#1}{#2}}{%
    \indextext{#1|see{#2}}%
  }{}%
  \textit{#1}%
}

then \defnx{trivially copyable class}{class!trivially copyable} and \defn{blah} would both do what you want.

@jensmaurer
Copy link
Member

Issue #1033 is related; we did decide that the page numbers go with the decomposed index entry. (That doesn't mean we should not have "see" entries for the other form.)
It is not obvious that the "see" form is always non-decomposed. For example "class, trivially copyable" has the page numbers and "trivially copyable, class" has the "see". There might also be a "trivially copyable, type" with another "see" to "type, trivially copyable" that points to [basic.types] or so.
@jwakely, I believe such an approach would still make the index useful to find "trivially copyable class"; do you agree?

@jensmaurer
Copy link
Member

@godbyk, I'm avoiding the \ifthenelse for now. I have
\newcommand{\defnc}[2]{\indextext{#1|see{#2}}\indexdefn{#2}\textit{#1}}
used as \defnc{trivially copyable class}{class!trivially copyable}.
This does not produce an index entry for "trivially copyable class", most likely because of the "|" in the 'see' part of the entry. (The "see" seems to need a comma-separated thing.)
Any obvious ideas I'm missing, otherwise I'll redesign the macro so that we must use it as \defnc{trivially copyable}{class}?

@jwakely
Copy link
Member Author

jwakely commented May 24, 2018

@jwakely, I believe such an approach would still make the index useful to find "trivially copyable class"; do you agree?

Yes. As long as I can go to T in the index and find "trivially copyable class" in some form or another I think that's fine. Currently it's not there at all under T.

I tried using additional packages so I could replace the "|" with ", " in the index entry, but didn't get it working. Breaking it into two arguments seems like a better solution.

@jensmaurer
Copy link
Member

jensmaurer commented May 24, 2018

In #2080, there is a specific change to create a \defnc for compound defined terms with uniform indexing. We should form an opinion whether that's the way to go, and then apply it everywhere.

@jensmaurer jensmaurer added big An issue causing a large set of changes, scattered across most of the text. decision-required A decision of the editorial group (or the Project Editor) is required. labels May 24, 2018
@godbyk
Copy link
Contributor

godbyk commented May 24, 2018

@jensmaurer Why are we avoiding \ifthenelse?

The definition of \defnc in #2080 seems rather narrow in that it only works for x y → y, x transforms. Wouldn't a more general function (like what my \defnx macro above provides) be better? Using \defnc also means that authors and editors have to learn yet another macro.

@jensmaurer
Copy link
Member

jensmaurer commented May 24, 2018

@godbyk: The point is not the \ifthenelse. I'm not seeing that your \defnx macro above converts an exclamation mark to a comma, as required to form a proper "see".

@godbyk
Copy link
Contributor

godbyk commented May 25, 2018

@jensmaurer Ah, sorry. My brain was still in xindy mode when I wrote it. (xindy requires you use x!y instead of x, y for cross-references.)

Try replacing the existing \defnx macro with the following code:

\usepackage{xstring}
\newcommand{\defnx}[2]{%
  \indexdefn{#2}%
  \ifthenelse{\NOT\equal{#1}{#2}}{%
    \StrSubstitute{#2}{!}{, }[\stdtemp]%
    \indextext{#1|see{\stdtemp}}%
  }{}%
  \textit{#1}%
}

It replaces all instances of ! with , in the index entry so the cross-reference should work again. (If we switch to xindy in the future, we'll want to skip the substitution, though.)

@jensmaurer
Copy link
Member

@godbyk: Ah. So, we get the correct "see" when using exclamation marks once xindy lands (see #1917). Thanks.
I'd like to point out, though, that the \defnc macro reduces redundancy in the source code, because every word appears only once. (A \defnx repeats the words in a different order.) Although it's awkward that the position of the exclamation mark is indicated by }{ (i.e. starting the second argument).

@godbyk
Copy link
Contributor

godbyk commented May 25, 2018

@jensmaurer Yeah. xindy actually checks to see if the cross-reference target exists and complains if it doesn't. It's found a few errors in our current indexing.

It's true that it reduces the number of words you have to type, but only for that particular construction. If you want to do any other type of cross-reference, you're stuck using \defnx anyway. I think using \defnx in all cases will reduce the mental load on authors: it provides consistency and clarity.

@jensmaurer
Copy link
Member

@godbyk Right, but I suspect we'll have a lot of use for \defnc once we actually get going with #1033. Let's have the editorial team discuss this in Rapperswil.

@jensmaurer
Copy link
Member

Editorial meeting consensus: \defnc as presented in #2080 is approved and even liked by the Project Editor. Yes, it covers only two-part terms, but that's likely > 95% of the cases, so good enough.

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

"trivially copyable class" was fixed. There's no point in leaving this open. Please create a new issue for specific bad index entries.

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

3 participants