[std] Use \libmember and \libglobal everywhere

[Eelis]

These macros were added by #3096 but are currently almost unused. That's a shame, because in principle their use enables more precise indexing and linking, which I would love to take advantage of in cxxdraft-htmlgen.

For example, a link such as http://eel.is/c++draft/string.iterators#lib:basic_string,cbegin currently points to begin rather than cbegin, because the index entry for cbegin is actually located just before the itemdecl that declares both begin and cbegin. Had \libmember been used here, I could link specifically to the declaration of cbegin.

Although.. that brings up the question of how these macros are intended to be used with overloaded names like begin. Is the intent to:

1. use the macro on all overloads
2. use the macro only on the first overload
3. not use the macro at all for overloaded names
4. something else? :)

I'd be happy to make a pull request to use these macros everywhere, but do need guidance on this issue of how to handle overloaded names. @jensmaurer do you remember whether you considered overloaded names when you made these macros?

[jensmaurer]

I don't think I thought about overloads.

We do not use \libmember broadly right now, because we sometimes have // comments later in the same line, aligned with nearby comments. And the necessary LaTeX escape-foo plus the \libmember macro invocation makes the alignment non-obvious in the source code, which doesn't help the editing.

So, please hold back on global \libmember patches.

[Eelis]

Ah I see, makes sense.

An alternative idea I had was that perhaps there could be an environment that wraps a whole declaration, so that instead of

struct X {
  int @\libmember{f}{X}@();
};

you get something more along the lines of

struct X {
  @\begin{libmember}{f}{X}@
  int f();
  @\end{libmember}@
};

Bit more verbose, but easy to edit, and even better for cxxdraft-htmlgen because then I can make it highlight the whole declaration instead of just the name.

I have no idea if mixing environments with @ like this is even possible in LaTeX though.

[jensmaurer]

Add-on: I think we're looking forward to \libmember patches where the library member is defined in the class or header synopsis and does not have a separate \itemdecl. (The status quo here is that we either have no index entry, or an index entry that points to the start of the synopsis. Neither option is good.)

[zygoloid]

struct X {
  @\begin{libmember}{f}{X}@
  int f();
  @\end{libmember}@
};

There's a problem with this: the codeblock environment respects whitespace, so the above will render as

struct X {
  
  int f();
  
};

(with blank lines before and after f). This means we need really ugly markup for a lot of the cases where we try to put index entries inside codeblocks. :-(

IIRC this kind of formatting works OK:

struct X {
  // comment for the below typedef@%
  \libindex{...}%
  \libindex{...}@
  using foobar_t = int;
}

... but you need to be careful about which linebreaks you do and do not comment out, and not all declarations are preceded by a comment that can be so annotated.

As a general goal, every library declaration should have an index entry. If it has an \itemdecl, we want an index entry pointing to that. If it has a synopsis entry, we want an index entry pointing to that (ideally to the right place in the synopsis, using either the above technique or using \libmember, depending on the situation, but a lot of pre-existing entries point to the start of the synopsis, and that might be OK in limited cases if the synopsis is very short, but is usually undesirable). I don't think we have any current intention to index both places for entities with an \itemdecl, though we could reconsider that if people think it's useful.

[sdkrystian]

Somewhat on the topic: There's a few instances where \libraryglobalindex is not being parsed correctly, and showing up naked in the text, for example http://eel.is/c++draft/new.syn. Not sure if it's an eel.is issue or what have you, just wanted to point that out :)

[JohelEGP]

That's Eelis/cxxdraft-htmlgen#71, so I guess it's an eel.is's issue.