Make macro used in section title behave differently in toc

Question

I am writing lecture notes for a course and use a macro to insert week numbers into section titles as indicated:

The latex code would be

\subsection{Finite fields\weektag}

The week number is stored in a counter

\newcounter{weekcounter}

I would now like either or both of the following two behaviors in the table of content:

Contents
...
3.3 Topic before
3.4 Week 7: Finite fields
3.5 Topic after
...

or that actually every subsection (so not only those where the macro is used in the section title) gets the week number attached

Contents
...
3.3 Week 6: Topic before
3.4 Week 7: Finite fields
3.5 Week 7: Topic after
...

where the subsection title lines read

\subsection{Topic before}
...
\subsection{Finite fields\weektag}
...
\subsection{Topic after}

So my first question is

How can I determine inside the macro whether I am in the table of contents or in the body of the text to alter the macro's behavior depending on the situation?

and my second question is

How can I use the above counter to generally write something into all subsection table of content entries?

Many thanks!

An MWE that I currently have is

\documentclass{article}

\usepackage{amsmath}
\usepackage{todonotes}

\newcounter{weekcounter}
\DeclareRobustCommand{\weektag}{
  \stepcounter{weekcounter}
  \todo[size=\tiny,color=red!10]{\hfil\textbf{week \theweekcounter}\hfil}
}

\begin{document}

\tableofcontents

\section{Section 1}

some text

\section[Section 2]{\weektag Section 2}

some text

\section{Section 3}

some text

\end{document}

producing

The table of contents there should now be either looking like

or like

Answer 1

I'd use a different command for the job.

\documentclass{article}

\usepackage{amsmath}
\usepackage{todonotes}

\newcounter{weekcounter}
% \weektag might print the tag in the right margin
\DeclareRobustCommand{\weektag}{%
  \todo[size=\tiny,color=red!10]{\hfil\textbf{week \theweekcounter}\hfil}%
}
% the main command wraps \section
\newcommand{\lecture}[1]{%
  \section[\protect\printweek #1]{#1\perhapschangeweek}%
}
% conditionally print the tag
\newcommand{\perhapschangeweek}{%
  % the current value of week
  \edef\thisweek{\theweekcounter}%
  % compare with the previously set value; if different, print the tag
  \ifx\thisweek\currentweek\else\weektag\fi
  % set the current week value
  \global\let\currentweek\thisweek
}
% change week: step the counter and do the same in the toc
\newcommand{\newweek}{%
  \stepcounter{weekcounter}%
  \addtocontents{toc}{\protect\stepcounter{weekcounter}}%
}
% a conditional to see whether we're in the toc
\newif\ifintoc
% \printweek does nothing outside of the tok
\newcommand{\printweek}{\ifintoc Week \theweekcounter: \fi}
% before starting \tableofcontents set the conditional to true
\AddToHook{cmd/tableofcontents/before}{\intoctrue}
% after \tableofcontents set the conditional to false and reset weekcounter
\AddToHook{cmd/tableofcontents/after}{\intocfalse\setcounter{weekcounter}{0}}

\begin{document}

\tableofcontents

\lecture{Section 1}

some text

\newweek

\lecture{Section 2}

some text

\lecture{Section 3}

some text

\newweek

\lecture{Section 4}

\end{document}

You might want to start weeks from 1: change

\AddToHook{cmd/tableofcontents/after}{\intocfalse\setcounter{weekcounter}{0}}

into

\AddToHook{cmd/tableofcontents/after}{\intocfalse\setcounter{weekcounter}{0}\newweek}

Answer 2

How can I determine inside the macro whether I am in the table of contents or in the body of the text to alter the macro's behavior depending on the situation?

Probably checking the definition of \protect is sufficient.

\texorpdfstring can be used for detecting whether TeX is in the situation of creating a pdf-string, e.g., a bookmark, which does not show up within a page of the document but is displayed separately.

How can I use the above counter to generally write something into all subsection table of content entries?

If you look at the .toc-file, you find entries \contentsline{subsection}....

Probably you can introduce an \if..-switch, which usually is false, and patch \contentsline so that to its 2nd argument, which denotes the text phrase of the entry of the table of contents, the value of the week-counter etc is prepended in case the switch is "true".

If you do this you still need a mechanism for transporting values of the week-counter and setting the \if..-switch into the toc-file. The following example does this via \addtocontents.

\weektagstepped is used for incrementing weekcounter and displaying the week-tag and adding the week to the table of contents and the bookmarks (if hyperref is loaded).

\weektag is used for displaying the week-tag (without incrementing the weektag-counter) adding the week to the table of contents and the bookmarks (if hyperref is loaded).

\weektoc is used for adding the week to the table of contents and the bookmarks (if hyperref is loaded). (No displaying of the week-tag and no incrementing the weektag-counter.)

\documentclass{article}

\usepackage{amsmath}
\usepackage{todonotes}
%\usepackage{hyperref}
%\usepackage{nameref}

\newcounter{weekcounter}

\makeatletter
\newcommand\weekcountervalue{}%
\newcommand\pdfweeknum{}%
%-------- Can't do \begin{NoHyper}...\end{NoHyper} as that
%         yields unknown-destination-errors with the 
%         `\todo`-command. It would also break the list of todo notes -------
\newcommand\saved@currentHref{}%
\newcommand\saved@currentlabelname{}%
\newcommand\saved@currentlabel{}%
\newcommand\savecurrentref{%
  \global\let\saved@currentHref\@currentHref
  \global\let\saved@currentlabelname\@currentlabelname
  \global\let\saved@currentlabel\@currentlabel
}%
\newcommand\restorecurrentref{%
  \global\let\@currentHref\saved@currentHref
  \global\let\@currentlabelname\saved@currentlabelname
  \global\let\@currentlabel\saved@currentlabel
}%
%----------------------------------------------------------------------------
% This is used to prepend "Week \theweekcounter: " to pdf-bookmarks:
%   Probably some of the things should not be done in terms of global
%   but only in the group-level where the sectioning-command occurs:
\newcommand\savedpdfstringdefPostHook{}%
\newcommand\patchpdfstringdefposthook{%
  \@ifundefined{pdfstringdef}{}{%
    \pdfstringdef\pdfweeknum{Week \theweekcounter: }%
    \global\let\savedpdfstringdefPostHook=\pdfstringdefPostHook
    \gdef\pdfstringdefPostHook##1{%
       \expandafter\expandafter\expandafter\gdef
       \expandafter\expandafter\expandafter##1%
       \expandafter\expandafter\expandafter{\expandafter\pdfweeknum##1}%
       \global\let\pdfstringdefPostHook=\savedpdfstringdefPostHook
       \gdef\pdfweeknum{}%
       \pdfstringdefPostHook##1%
    }%
  }%
}%
%----------------------------------------------------------------------------
\newcommand{\weektagstepped}{%
  \@ifundefined{texorpdfstring}{\@firstoftwo}{\texorpdfstring}%
  {%
    \ifx\protect\relax % Probably in main document, not toc or the like
       \ifx\label\@gobble\else % Probably not in \nameref
         \stepcounter{weekcounter}%
         \addtocontents{toc}{%
           \string\def\string\weekcountervalue{\theweekcounter}%
           \string\InsertWeekcountertrue
         }%
         \savecurrentref
         \todo[size=\tiny,color=red!10]{\hfil\textbf{week \theweekcounter}\hfil}%
         % Restore referencing-data. Otherwise referencing-labels
         % denote the place where \todo started drawing the line 
         % and pdf-bookmarks and cross-referencing-links won't lead
         % to scrolling to the left end of the sectioning heading -
         % wrapping \todo between \begin{NoHyper}..\end{NoHyper}
         % leads to unknown-destination-errors:
         \restorecurrentref
         \patchpdfstringdefposthook
      \fi
    \fi
  }{}%
}%
\newcommand{\weektag}{%
  \@ifundefined{texorpdfstring}{\@firstoftwo}{\texorpdfstring}%
  {%
    \ifx\protect\relax % Probably in main document, not toc or the like
       \ifx\label\@gobble\else % Probably not in \nameref
         \addtocontents{toc}{\string\InsertWeekcountertrue}%
         \savecurrentref
         \todo[size=\tiny,color=red!10]{\hfil\textbf{week \theweekcounter}\hfil}%
         % Restore referencing-data. Otherwise referencing-labels
         % denote the place where \todo started drawing the line 
         % and pdf-bookmarks and cross-referencing-links won't lead
         % to scrolling to the left end of the sectioning heading -
         % wrapping \todo between \begin{NoHyper}..\end{NoHyper}
         % leads to unknown-destination-errors:
         \restorecurrentref
         \patchpdfstringdefposthook
       \fi
    \fi
  }{}%
}%
\newcommand{\weektoc}{%
  \@ifundefined{texorpdfstring}{\@firstoftwo}{\texorpdfstring}%
  {%
    \ifx\protect\relax % Probably in main document, not toc or the like
      \ifx\label\@gobble\else % Probably not in \nameref
        \addtocontents{toc}{\string\InsertWeekcountertrue}%
        \patchpdfstringdefposthook
      \fi
    \fi
  }{}%
}%
\newif\ifInsertWeekcounter
\@ifdefinable\contentslinecopy{\let\contentslinecopy\contentsline}%
\newcommand\behindnumberline[3]{#2{#3}#1}%
\renewcommand\contentsline[2]{%
  \contentslinecopy{#1}{%
    \ifInsertWeekcounter\global\InsertWeekcounterfalse\expandafter\@firstofone\else\expandafter\@gobble\fi
    {%
      \@ifnextchar\numberline{\behindnumberline{Week \weekcountervalue: }}{Week \weekcountervalue: }%
    }%
    #2%
  }%
}%
\makeatother

\pagestyle{headings}

\begin{document}

\tableofcontents

\section{A section}

\verb|\ref{Firstlecturesecondweek}|: \ref{Firstlecturesecondweek}

% \noindent\verb|\nameref{Firstlecturesecondweek}|: \nameref{Firstlecturesecondweek}

\subsection{Only one lecture in the first week\weektagstepped}

some text \hfill some text  \hfill some text 

\subsection{First lecture in the second week\weektagstepped}
\label{Firstlecturesecondweek}%
\subsection{Second lecture in the 2nd week\weektag}
\subsection{Third lecture in the 2nd week\weektag}
\subsection{Fourth lecture in the 2nd week\weektoc}
\subsection{Something probably in the 2nd week}

some text

\end{document}

Bookmarks if hyperref is loaded: