Naming labels more consistently

[muzimuzhi]

Keeping a complete and consistent label naming scheme would require unnecessary amount of work, but some kind of consistent is helpful for manual writing and maintaining.

General

• Use : as separator, for example \label{sec:number:printing}.

Discussion

• Does pgfplots required in label names? See \label{sec:pgfplots:lineplots} vs \label{sec:lineplots}.

Suggestion

Type (label of)	Prefix	Note
chapters	cha	remind to use Chapter~\ref{...} done in PR #361
numbered (sub)sections	sec
unnumberd (sub)sections	ssec?	remind not to use \ref
option key	key
command	cmd
(to be continued)

[Mo-Gul]

I personally use ssec for labeling \subsection (and sssec for labeling \subsubsection). At least also using a different prefix for \subsection may also help, because these are also not numbered and thus \ref shouldn't be used.

To "mark" unnumbered (sub)sections I therefore suggest the prefix u (for unnumbered) to the prefix. Thus, \subsection* should have a prefix usec.

[muzimuzhi]

@Mo-Gul Use sec for numbered sections only, and usec for all the other unnumbered sections and subsections?

Since you've done change "Subsection~ --> Section~" in https://github.com/pgf-tikz/pgfplots/pull/361/commits/33b4bf687879f1f1c21debe0b71defaecac79fd1, there would be no difference between writing \nameref and \pageref to unnumbered sections and subsections. It would always be "see Section~``\nameref{usec:...}'' on page~\pageref{usec:...}'".

[Mo-Gul]

I am not sure if I got your point 100% so I'll try to explain in other words.

I did the "subsection" change because of consistency reasons. There was this single instance only, although there are plenty of references to subsections, but naming them everywhere else just "section". So either name all subsections "subsections" or none.

You are right then in the written words there would be no difference between references to unnumbered sections and subsections. But we could change this as well if this would be beneficial. Personally I would be fine with both (as long as we do it consistently).

So far I would only favor your suggestion

Use sec for numbered sections only, and usec for all the other unnumbered sections and subsections?

if this would mean significant less work. Assuming I would have to do the work (which I happily would do, because that would be one of the things I could do and you could focus on stuff that I can't do) I would (have to?) go through each and every "sec" label anyway.

Also the risk of breaking something is very low by just changing the label prefixes in a first step, because I would store a reference PDF before changing them and would compare/diff it afterwards with the final PDF. Only when these two PDFs are identical I would start changing the \refs with the \nameref/\pageref stuff.

At present I can't see were using your approach would save some time. Do I miss something?

[muzimuzhi]

So far I would only favor your suggestion

Use sec for numbered sections only, and usec for all the other unnumbered sections and subsections?

if this would mean significant less work. Assuming I would have to do the work

By analyzing all the .aux files of pgfplots.tex, there are currently

• 62 labels of numbered sections
• 25 labels of numbered subsections
• 11 labels of unnumbered (sub)sections (there are undistinguishable by \newlabel lines in .aux files)

So the amount of required work is not much different (between using (u)sec, (u)ssec, (u)sssect and using sec and usec only).

[muzimuzhi]

You are right then in the written words there would be no difference between references to unnumbered sections and subsections. But we could change this as well if this would be beneficial. Personally I would be fine with both (as long as we do it consistently).

The written words can be automatically changed by macros.

Here is a first draft showing the auto-ref possibilities. It is not flexible yet.

• new command \autonameref(*){<label name>} is provided
• now unnumbered sections is distinguishable by their \@currentHref names: section<level>*.<num>. For example \section* has section1*.<num> and \subsection* has section2*.<num>.
• Implementation is not based on cleveref package which provides a flexible way to config the range of hyperlink, because I am not familiar with its code base.

Full implementation

\documentclass{article}
\usepackage{pgffor}
\usepackage{xcolor}
\usepackage{xpatch}

\usepackage{hyperref}
\hypersetup{colorlinks, linkcolor=blue}

\makeatletter
% config autorefnames
\renewcommand*{\sectionautorefname}{Section}
\renewcommand*{\subsectionautorefname}{Subsection}
\@namedef{section1*autorefname}{Section}
\@namedef{section2*autorefname}{Subsection}

% \@startsection is defined in latex.ltx (latex2e)
% store current section level in \Hy@sec@level
% TODO: use counter "section@level" defined in nameref.sty?
\xpatchcmd\@startsection
  {\@ifstar}
  {\def\Hy@sec@level{#2}\@ifstar}
  {}{\fail}

% nameref.sty is loaded in \Hy@AtBeginDocument, so delay the patch as well
\Hy@AtBeginDocument{
  % \NR@sect is defined in nameref.dtx (let to \@sect)
  % \@sect is redefined in hyperref's backend file, e.g., hpdftex.def
  \xpatchcmd\NR@sect
    {\Hy@MakeCurrentHrefAuto{section*}}
    {\Hy@MakeCurrentHrefAuto{section\Hy@sec@level*}}
    {}{\fail}

  % \NR@ssect is similar to \NR@sect
  \xpatchcmd\NR@ssect
    {\Hy@MakeCurrentHrefAuto{section*}}
    {\Hy@MakeCurrentHrefAuto{section\Hy@sec@level*}}
    {}{\fail}
}

% similar to definitions of \autoref, \HyRef@autoref, and \HyRef@autosetref
\DeclareRobustCommand*{\autonameref}{%
  \leavevmode
  \@ifstar{\HyRef@autonameref\@gobbletwo}{\HyRef@autonameref\hyper@@link}%
}

\def\HyRef@autonameref#1#2{%
  \begingroup
    \Hy@safe@activestrue
    \expandafter\HyRef@autonamesetref\csname r@#2\endcsname{#2}{#1}%
  \endgroup
}

\def\HyRef@autonamesetref#1#2#3{% link command, csname, refname
  \HyRef@ShowKeysRef{#2}%
  \ifcase 0\ifx#1\relax 1\fi\ifx#1\Hy@varioref@undefined 1\fi\relax
    \edef\HyRef@thisref{%
      \expandafter\@fourthoffive#1\@empty\@empty\@empty
    }%
    \expandafter\HyRef@testreftype\HyRef@thisref.\\%
    \Hy@safe@activesfalse
    % move autoname out of hyperlink
    \HyRef@currentHtag
    #3{%
      \expandafter\@fifthoffive#1\@empty\@empty\@empty
    }{%
      \expandafter\@fourthoffive#1\@empty\@empty\@empty
    }{%
      % \HyRef@currentHtag
      % use \@thirdoffive to retrive \@currentlabelname and add quotes
      ``\expandafter\@thirdoffive#1\@empty\@empty\@empty''%
      \null
    }%
  \else
    \protect\G@refundefinedtrue
    \nfss@text{\reset@font\bfseries ??}%
    \@latex@warning{%
      Reference `#2' on page \thepage\space undefined%
    }%
  \fi
}

% move autoname out of hyperlink
\def\HyRef@autosetref#1#2#3{% link command, csname, refname
  \HyRef@ShowKeysRef{#2}%
  \ifcase 0\ifx#1\relax 1\fi\ifx#1\Hy@varioref@undefined 1\fi\relax
    \edef\HyRef@thisref{%
      \expandafter\@fourthoffive#1\@empty\@empty\@empty
    }%
    \expandafter\HyRef@testreftype\HyRef@thisref.\\%
    \HyRef@currentHtag
    \Hy@safe@activesfalse
    #3{%
      \expandafter\@fifthoffive#1\@empty\@empty\@empty
    }{%
      \expandafter\@fourthoffive#1\@empty\@empty\@empty
    }{%
      \expandafter\@firstoffive#1\@empty\@empty\@empty
      \null
    }%
  \else
    \protect\G@refundefinedtrue
    \nfss@text{\reset@font\bfseries ??}%
    \@latex@warning{%
      Reference `#2' on page \thepage\space undefined%
    }%
  \fi
}

% move \HyRef@autopagerefname out of hyperlink
\def\HyRef@autopageref#1{%
  \HyRef@autopagerefname\hyperref[{#1}]{\pageref*{#1}}%
}
\makeatother


\begin{document}
\section{title}\label{sec}
\subsection{subtitle}\label{sec2}

\section*{starred title}\label{usec}
\subsection*{starred subtitle}\label{usec2}

\parindent=0pt
\foreach \i in {sec, sec2, usec, usec2} {
  see \autonameref{\i} on \autopageref{\i},
  see \autonameref*{\i} on \autopageref{\i} \par
}
\end{document}

Usage example

\documentclass{article}
\usepackage{pgffor}
\usepackage{xcolor}
\usepackage{hyperref}
\hypersetup{colorlinks, linkcolor=blue}

% patch codes, see full implementation

\begin{document}
\section{title}\label{sec}
\subsection{subtitle}\label{sec2}

\section*{starred title}\label{usec}
\subsection*{starred subtitle}\label{usec2}

\parindent=0pt
\foreach \i in {sec, sec2, usec, usec2} {
  see \autonameref{\i} on \autopageref{\i},
  see \autonameref*{\i} on \autopageref{\i} \par
}

\end{document}

Edit: An extra level of abstraction based on \autoref and \autonameref can even get rid of using different label prefixes (sec and usec). For example, it's possible to provide a \smartAutoref that \smartAutoref{sec:...} will work like \autoref and \smartAutoref{usec:...} will work like \autonameref.

It seems this comment leads the discussion to another direction: to make manual high quality, write more codes to make machines do more logic and provide easier markup interface to humans, or formulate more rules that humans should obey? In general a balance between complexity of code logic and length of rules should be kept, but in current specific label-prefix situation, I vote for "more code, less markup rules".

Edit 2: Added usage example of \autonameref*.

[Mo-Gul]

ping @muzimuzhi, can you/we finish this?