\ref to unnumbered subsection labels gives wrong output

[muzimuzhi]

In pgfplots manual, some labels are added to un-numbered sections (\subsubsection, for example). The \ref to those labels gives numbering of the most recent \section, which is wrong. A demonstration:

%% input                  %% output
\section{Numbered}        % 4.6.3 Numbered
\subsection{Unnumbered}   % Unnumbered
\label{subsec}

see Section~\ref{subsec}  % see Section 4.6.3 << this is wrong 
on page~\pageref{subsec}  % on page xx        << alright
                          %                   << both hyperlinks are ok

A specific example, the \ref output is on pgfplots manual v1.17, page 106. https://github.com/pgf-tikz/pgfplots/blob/d85789248e5c0352ea0ec9349914e5ae87c8a0b1/doc/latex/pgfplots/pgfplots.reference.3dplots.tex#L552-L553 https://github.com/pgf-tikz/pgfplots/blob/d85789248e5c0352ea0ec9349914e5ae87c8a0b1/doc/latex/pgfplots/pgfplots.reference.closingplots.tex#L55-L57

Possible patch:

• Manually change wording to avoid \ref to un-numbered sections, and use special prefix in label names as a reminder.
• Similar to the previous one, but using \nameref instead of \ref. So the modified text would be see Section~\nameref{subsec} on page~\nameref{subsec}
• Or just make \subsection level numbered, though that is a bit ugly.

[hmenke]

You don't have to put [manual] in the issue title. That's what we have the GitHub labels for.

[muzimuzhi]

Two (sub-)types found:

1. \label of \subsection*, two occurrences in total: https://github.com/pgf-tikz/pgfplots/blob/d85789248e5c0352ea0ec9349914e5ae87c8a0b1/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex#L1982-L1983 https://github.com/pgf-tikz/pgfplots/blob/d85789248e5c0352ea0ec9349914e5ae87c8a0b1/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex#L2307-L2308

2. \label of \subsubsection(*), 12 occurrences in total (some of them might be unused): https://github.com/pgf-tikz/pgfplots/blob/d85789248e5c0352ea0ec9349914e5ae87c8a0b1/doc/latex/pgfplots/pgfplots.reference.markers-meta.tex#L886-L887 https://github.com/pgf-tikz/pgfplots/blob/d85789248e5c0352ea0ec9349914e5ae87c8a0b1/doc/latex/pgfplots/pgfplots.libs.colorbrewer.tex#L614-L615

Suggestion:

• For \subsection*, convert them to numbered form \subsection.
• For \subsubsection(*), use prefix "ssec" (starred sec) in their label names, and avoid using \ref to those label.

[Mo-Gul]

To 1.: The structure is that

• there are numbered \subsections for each \addplot handler, i.e. coordinates, table, ... up to graphics which is section 4.3.7.
• Then follows (the unlabeled) subsection 4.3.8 as "Keys To Configure Plot Graphics",
• followed by the unnumbered (but labeled and referenced) subsections
  • "Support for External Three-Dimensional Graphics"
  • and "External Three-Dimensional Graphics and Matlab",
• followed by an unnumbered (but not labeled) subsection "Summary: External Three-Dimensional Graphics"
• before the final numbered subsection for the file handler.

For me the subsections 4.3.8 "Keys To Configure Plot Graphics" to "Summary: External Three-Dimensional Graphics" should all go one level down, because they are all related to the graphics handler. Because they are then are all (at least shown) as unnumbered, they could be referenced as \namerefs (+ \pagerefs). (Because section 4.3.8. already contains some subsubsections they would have to go one down as well.)

If this isn't an option, I suggest to at least also make section 4.3.8 unnumbered.

[Mo-Gul]

To 2.: I found these instances of labels on \subsubsections (including "PGFPlotsTable" and "TeX Programming Notes"):

pgfplots.libs.colorbrewer.tex:
  614: \subsubsection*{Color Schemes as ``Swatches''}
  615  \label{sec:pgfplots:brewer:usage}

pgfplots.libs.colortol.tex:
  504: %\subsubsection*{Color Schemes as ``Swatches''}
  505  %\label{sec:pgfplots:brewer:usage}

pgfplots.libs.patchplots.tex:
  400: \subsubsection{Two-Dimensional Patch Types}
  401  \label{sec:patchplots:twodim}

pgfplots.reference.2dplots.tex:
  1673: \subsubsection{Filling Under/Between Named Plots}
  1674  \label{sec:fillbetween:in:area:plots}

pgfplots.reference.3dplots.tex:
   552: \subsubsection{Filled Lined Plots in 3D}
   553  \label{sec:pgfplots:filled:line}

  1570: \subsubsection{Providing Colors Explicitly For Each Coordinate}
  1571  \label{sec:surf:explicit:color}

  1883: \subsubsection{Providing Colors as Math Expression}
  1884  \label{sec:surf:explicit:color:math}

pgfplots.reference.errorbars.tex:
  289: \subsubsection{Error Coordinates and Coordinate Lists}
  290  \label{sec:errorvalues:coords}

pgfplots.reference.markers-meta.tex:
   886:     \subsubsection{Colormap Input Format Reference}
   887      \label{sec:colormap:input:format}

  1345: \subsubsection{Building Colormaps based on other Colormaps}
  1346  \label{sec:pgfplots:colormaps:based:on:others}

pgfplotstable.tex:
  2333: \subsubsection{Changing Number Format Display Styles}%
  2334  \label{sec:number:styles}

TeX-programming-notes.tex:
   844: \subsubsection{Counting loops}
   845  \label{sec:counting:loops}

   918: \subsubsection{Loops over list of items}
   919  \label{sec:loops:over:list:of:items}

Here I also suggest changing the \refs to \namerefs + \pagerefs. Changing the \label names is also a great idea. I personally use the prefix ssec for subsection. So that might confuse me. If you don't mind I suggest using an u for "unnumbered" as prefix to the prefix. That I don't use anywhere.

(So far I haven't figured out the logic at the \label prefixes. Maybe I/we could/should change them eventually. But that would be another issue of course.

[muzimuzhi]

For me the subsections 4.3.8 "Keys To Configure Plot Graphics" to "Summary: External Three-Dimensional Graphics" should all go one level down, because they are all related to the graphics handler.

I agree they are all related to the graphics handler. But then the new 4.3.7 subsection will be 20 pages long. A quick glance suggests

Before
4.3.7  Using External Graphics as Plot Sources ---> 4.3.7
4.3.8  Keys To Configure Plot Graphics         ---> 4.3.9
<three subsubsections>                         ---> 4.3.8
4.3.9  Reading Coordinates From Files          ---> 4.3.10

After
4.3.7  Using External two-dimensional Graphics as Plot Sources
4.3.8  Using External three-dimensional Graphics as Plot Sources
4.3.9  Keys To Configure Plot Graphics
4.3.10 Reading Coordinates From Files

PS: I haven't read the contents of those related section completely or carefully, and since I seldom use pgfplots package, my opinion here might not be reliable.

Here I also suggest changing the \refs to \namerefs + \pagerefs. Changing the \label names is also a great idea. I personally use the prefix ssec for subsection. So that might confuse me. If you don't mind I suggest using an u for "unnumbered" as prefix to the prefix. That I don't use anywhere.

(So far I haven't figured out the logic at the \label prefixes. Maybe I/we could/should change them eventually. But that would be another issue of course.

A concern about \nameref: For most cases \nameref{<label of unnumbered>} will produce much longer linked text (in blue) than \ref{<label of numbered>}. If color is used to draw attention in pgfplots manual, then the output of \nameref would be dazzling. For this reason, I prefer not using \ref nor \nameref for labels of unnumbered sections.

As long as (a) naming of label prefix is consistently used and (b) documented (for example as a wiki page, "how to contribute to manual"), I'm ok with either choice. Actually in my local changes, I tried unsec first, then considered secstar or starsec but not used either of them, at last started to think of ssec.

[Mo-Gul]

Graphics handler

I think it is not a problem when this section is 20 pages long. I think we could find other similar cases as well in the manual. If an option needs more to state, e.g. because it has more options itself/functionality, then it should be written about it ...

I am not 100% sure about how your "After" sectioning looks like in total; e.g. I am missing the "Summary". But also if it would we written somewhere I don't find it optimal. The order of the sections is fine, because (I guess) >95% of the use-cases will be 2D graphics. And in case one really needs this in a 3D graphics there are some specialties one has to consider. Besides that when changing the order of the sections, some stuff inside the sections need to be rewritten, because it is cross-referenced in them with normal wording ... So before doing that I wouldn't change anything regarding the structure.

nameref

I agree, therefore I suggest using \nameref* which will only write the text without a hyperlink. That is why we need an additional \pageref. That this is longer is no point as long it is clear. So the example given in your first comment could be reformulated to

 Closing a plot is also possible for \emph{three-dimensional axes}, see 
 Section~``\nameref*{sec:pgfplots:filled:line}'' on 
 page~\pageref{sec:pgfplots:filled:line}. 

Style guide

Unfortunately there isn't anything like that. (The same is true for tikz, except for the stuff that is written in Lua.) That is one of the reasons why I try to apply a consistent style to manual wherever possible. So when people have a look at a random part of the manual they "know" how it should look like.

My guess is that the labels are so inconsistent, because the project grew over time and behavior changed or needed to be changed. I'll ask @cfeuersaenger if there are some (hidden) rules in the naming scheme of the labels and if he cares that we would try to harmonize them.

[muzimuzhi]

I agree with your proposals about graph handler and use of \nameref*. PS: a vote up for inconsistent label naming.

[Mo-Gul]

To give an update here: So far I didn't receive an answer from @cfeuersaenger. My suggestion is that we do the changes discussed above, because he never complained about stuff that I suggested regarding the manual. And if he really should care, if he will become active again eventually, then it would be easy to revert the changes.

@muzimuzhi, do you want to do this or shall I do it?

[ilayn]

That's not open source works unfortunately. It is what it is with authors sometimes they take a break sometimes life problems are heavier than maintaining stuff. So let's not assume stuff but let's try to judge what might go wrong if these changes go in.

[Mo-Gul]

For sure. I know exactly his situation and why he currently is inactive with PGFPlots. Luckily life problems are not the reason for that :)

Do you have some concerns (not sure if that word is right) about the two points (graphics handler and \nameref*), @ilayn?

[muzimuzhi]

Since the whole list is found and applying changes is not an intelligence work, I suggest we just continue waiting. And I am willing to do the change by then.

[Mo-Gul]

ping @muzimuzhi, can you/we finish this?