6

I have read the documentation of sockets and I was wondering how sockets can be used for practical use-cases. While surfing SE, I found this discussion around the topic and this mesmerizing picture-mode-illustrated answer 😛, but still didn't find a straight forward example. I asked AI to give a sample code and got the following (some manual cleanup done and some deprecated commands removed from the original AI-response):

\DocumentMetadata{tagging=on}
\documentclass{article}

\begin{document}
\NewSocket{greeting-socket}{0}

\NewSocketPlug{greeting-socket}{formal}{Dear ma’am/sir,}
\NewSocketPlug{greeting-socket}{informal}{Hi there,}
\NewSocketPlug{greeting-socket}{friendly}{Hello, friend!}

\NewSocket{closing-socket}{0}

\NewSocketPlug{closing-socket}{formal}{Sincerely,}
\NewSocketPlug{closing-socket}{informal}{Cheers,}

\section*{Formal Letter}
\AssignSocketPlug{greeting-socket}{formal}
\AssignSocketPlug{closing-socket}{formal}
\UseSocket{greeting-socket}

This is a formal letter content.

\UseSocket{closing-socket}

John Doe

\section*{Informal Note}
\AssignSocketPlug{greeting-socket}{informal}
\AssignSocketPlug{closing-socket}{informal}
\UseSocket{greeting-socket}

This is an informal note.

\UseSocket{closing-socket}
Jane

\section*{Friendly Message}
\AssignSocketPlug{greeting-socket}{friendly}
\AssignSocketPlug{closing-socket}{informal}
\UseSocket{greeting-socket}

Just a quick message to say hi.

\UseSocket{closing-socket}

Your pal
\end{document}

Now the question is if this type of usage can be called "standard"? Imagine I have some code instead of the un-expandable text in the given example. Here are some questions:

  1. Are the names used here recommendable? What names do the kernel use-cases of sockets use? What should package authors use? (The documentation says:

    Best practice naming conventions are . . . to be documented

    but it is dated 2024-12-27 which is quite old now, so I assume some recommendations can be given?)

  2. Usually it is said that sockets are to be used only once unlike hooks. Does that mean multiple usages of \AssignSocketPlug wrong? The documentation does say:

    If the programming logic should change, then all that is necessary is to make a new assignment with \AssignSocketPlug to a different {⟨socket-plug-name⟩}.

    but it also says:

    A socket is typically only used in one place in code, but this is not a requirement, i.e., if the same operation with the same inputs need to be carried out in several places the same named socket can be used.

    So I am confused. In the given example, what exactly is wrong (or atypical)? The multiple uses of \AssignSocketPlug or \UseSocket? Theoretically both seem to be fine, but not sure what is expected.

  3. Is there any general consensus on what should not be used in sockets?

  4. Anything else regarding sockets based on the example or beyond it?

24
  • 1
    where does it say they should only be used once? what would be the point? unlike hooks, a socket can have only one plug in it at a time. a hook can have a bunch of code chunks. a socket can't. Commented 20 hours ago
  • 1
    socket names should include a module prefix, I think, to avoid name conflicts. so I used e.g. tableaux/tagsupport/tableau/init. I don't know that format is documented, but I copied what I found in kernel code. so that might have e.g. tagsupport/tikz/init. I named mine tableaux/tagsupport/tableau/init. tableaux is intended as a module identifier/prefix. tagsupport/tableau/init is intended as a hierarchy of descriptors. Commented 20 hours ago
  • 1
    ulrike (i.e. the kernel) uses things like tagsupport/tikz/picture/end, where tagsupport indicates the module and tikz/picture/end is a hierarchy of descriptors. Commented 20 hours ago
  • 1
    well, you would not normally use \UseSocket{} in a document. probably you'd have a class or package for letters which would use the <module>/letter/closing socket once, because each letter only gets one closing. so it would be used in one place in the template for letters. but you might have several letters in a document. Commented 20 hours ago
  • 2
    @cfr tagsupport is the prefix for tagging sockets and should be at the begin. Commented 16 hours ago

2 Answers 2

9

It does not say you should only use the socket once, it says that (normally) a given socket only appears in one place.

Looking down latex.ltx a perhaps typical example is

\def\@outputbox@appendfootnotes {%
   \ifvoid\footins \else
     \@makecol@handlesplitfootnotes
     \UseSocket{build/column/footnotes}%
     \@outputbox@append{%
       \UseSocket{build/column/baselineattach}%
       \vskip \skip\footins
       \UseTaggingSocket{build/column/footins}%
       \color@begingroup
         \normalcolor
         \footnoterule
         \csname pdfcolfoot@current\endcsname
         \unvbox \footins
       \color@endgroup
      }%
  \fi
}

The original format code for adding footnotes to the bottom of a column implemented one fixed layout, which meant that packages such as footmisc had to over-write or patch that code, and then the latex tagging had to patch in code to add footnote tagging code, the paches having do vary depending on how the code had already been patched by earlier packages.

The new code has defined extension points (sockets) at the places that may be reasonably extended, and so footnotes can be styledand tagging enabled by plugging suitable code in at those points without interfering with each other.

The "just in one place" comment that you quoted means that (for example) the socket build/column/footnotes just appears here so that you may plug different code in for different footnote styles (ie use that socket multiple times) but doing so only affects this code not another 1001 places that have a socket of the same name.

In order to ensure that your socket names are unique to your package it is good practice to structure the names with / eg the above column sockets all have names starting build/column so you could for example use a prefix of yourpackage/ These prefixes are not actually used (there is no provided interface for splitting up the names) but form a useful convention to avoid tripping over other packages.

2
  • Thanks. Can you also address the specific questions regarding the names and other things? It can be of great help to package authors for following good practices. Commented 15 hours ago
  • 1
    @Niranjan I added a not on names Commented 15 hours ago
7

We have two different type of sockets: "tagging" sockets and "normal" sockets.

David explained "normal" sockets, so here some remarks about tagging sockets.

Tagging sockets are meant to contain tagging commands. As it should be possible to activate and deactivate tagging globally, they have some special features.

  • The name of tagging sockets all starts with the prefix tagsupport/.

  • They are used with a special command \UseTaggingSocket which automatically adds the prefix and whose behaviour can be adapted globally. So \UseTaggingSocket{build/column/footins} in David's example calls the socket tagsupport/build/column/footins.

  • They typically have only two plugs: one for deactivated tagging and one for activated tagging.

    • For sockets with zero or one argument the deactivated state is noop and the activated the one assigned to the socket.
    • For sockets with two arguments the deactivated state is transparent which means that the second argument is literally passed through. The activated state is again the one assigned to the socket.

The naming of tagging sockets should be similar to normal sockets: we suggest to use slashes and a module prefix.

You can use either \NewTaggingSocket{mymodule/mysocket} or \NewSocket{tagsupport/mymodule/mysocket} to create such a socket. Both will create the socket tagsupport/mymodule/mysocket will be created.

You must log in to answer this question.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.