5

When I'm working on a document for which I need special layout, I tend initially to accumulate a very long preamble. At some point, if I need to reuse similar layout regularly, I decide that I really ought to tidy things up and create a custom class or package. If a class, it is typically a parasitic one i.e. it loads another class so I don't have to worry about missing important stuff out.

In some cases, I am now in a situation where I have custom commands which are operating not unlike standard commands. For example, I might be using something like this rather than using \section for the article class:

% Note that this is definitely not an MWE! 
% My question is specially about code which makes little sense outside
% a very specific context. If the code did make sense on its own, I would
% not need to ask the question. 
% BEGIN defn \ns
  \NewDocumentCommand\ns{sO{}}{%
        \gdef\thiss{#2}%
        \setcounter{ssn}{0}%
        \IfBooleanTF #1
          {%
                \addcontentsline{toc}{section}{#2}%
                #2}%
          {%
                \stepcounter{sn}%
                \addcontentsline{toc}{section}{\S\thesn\hspace*{1.5em}#2}%
                \S\thesn\hspace*{1.5em}#2}%
          }
% END defn \ns
% BEGIN defn \nst
  \NewDocumentCommand\nst{sd()O{}md<>O{}O{}sd<>}{% \nst*(frame width)[graphics options]{image file}<caption>{section title}{subsection or other subheading}<additional source/copyright/attribution>
        \clearpage
        \pagestyle{empty}\cleardoublepage
        \begin{titlingpage}
          \AddThispageHook{\usebox{\mysecsglas}}%\input{../../secs/secs-glas}%
          \noindent\sffamily\bfseries\color{bcol1}%
          \begin{center}
                \vspace*{\fill}
                \IfNoValueTF{#2}%
                  {%
                        \includegraphics[#3]{#4}}%
                  {%
                        \efbox[#2]{\includegraphics[#3]{#4}}}%
                \IfNoValueTF{#5}{\relax}{\medskip\\\normalfont #5}%
                \bigskip
                \vspace*{\fill}\vspace*{\fill}\\
          \end{center}
                \hspace*{\fill}%
                \IfBooleanTF{#1}{%
                  \nsfont\ns*[#6]}{%
                  \nsfont\ns[#6]}%
                  \vskip -.5em
                  \stepcounter{ssn}%
                  \hspace*{\fill}{\nssfont #7}
        \end{titlingpage}
        \clearpage\thispagestyle{empty}
          \setcounter{ssn}{0}
          \vspace*{\fill}\vspace*{\fill}\begin{center}
                  Sealing wax\IfBooleanTF{#8}{, cabbages}{} and kings courtesy Lewis Carroll.\smallskip\\
                  \IfNoValueTF{#9}{\relax}{#9\smallskip\\}
                  Typeset using pdf\LaTeX, {B{\sc \uppercasesc i\kern-.025em \uppercasesc b}\kern-.08em\LaTeX} and Biber in Latin Modern and URW ChanceryL.
          \end{center}
          \cleardoublepage}
% END defn \nst

On the one hand, these commands are used in my document as replacements for \section. (Probably it would be closer to use book or report and say it is being used like \chapter. But actually, I'm using article because that's how it started.) They set the title, add stuff to the ToC and so on.

On the other hand, these kinds of commands are also radically unlike the standard commands as they do a whole bunch of other things and are designed for a much more specific purpose.

I'm wondering whether best practice would involve redefining the standard commands and using \chapter or \section or whatever. Or whether best practice would involve leaving those commands alone.

Note that I'm aware that either will work. Also, this is much too tailored to ever be of interest to anybody else so I am not asking about the wisdom or otherwise of inflicting any version of this on anybody else ever. (Doing so would clearly be idiotic.) I'm more thinking of what will be best from the point of view of maintaining and updating the code for my own use in the future.

  • @Manuel Thanks. I'm also not sure the question is entirely clear. Could you say more about what isn't clear? I found it rather difficult to put together. (But maybe that means that I'm not clear what I want to ask.) – cfr Sep 17 '14 at 0:07
  • It's parasitic. Nothing really matters :) – Manuel Sep 17 '14 at 0:13
  • 1
    +1 for the description "parasitic". (i've been calling these things "derivative", but i may switch.) would you ever want to use both the conventional \section and your alternative structure in the same document? if yes, then definitely define a new command/environment. if no, and they are functionally equivalent, then i'd see justification for using the same name. are you certain you'll never see any reason to inflict them on anyone else? then it really doesn't matter. (but if i were doing it, i'd most likely use new names.) – barbara beeton Sep 17 '14 at 0:30
  • @barbarabeeton Thanks. It would actually be convenient to have \section as well. However, I'd probably have to redefine \section to make it work. Right now it is an uncomfortable mixture of my own commands at the top level and then \subsubsection{} on from the standard ones. I can use \section* but using \section messes things up (especially the ToC) so I have to remember not to use \section/\subsection. I can't imagine I would ever inflict them on anybody else, no. Nor can I imagine anybody allowing me to! – cfr Sep 17 '14 at 1:06
  • 1
    Well, in truth, I'm not the right person to ask. I've fiddled with keyval, pgfkeys, yax, and l3keys, but I've only really ever used the last two. (And note that while yax is neat, it is sort of taking you out of the LaTeX world, which is not necessarily a bad thing, but it is a thing worth noting.) However, if you want some key-value abilities without as much of the programming, there's also the keycommand package. Obviously, if you like xparse -- and who doesn't? -- then there's something to be said for sticking with l3keys. – jon Sep 18 '14 at 2:37
3

As you seem to be concerned with \section, I'll make a couple of examples.

The memoir class allows for two optional arguments to \section, one for the TOC entry and the other one for the header. In the KOMA-script classes \section has just one optional argument which should contain a list of key=value pairs (it also allows just the short version of the title as in the standard classes for back compatibility).

For both the standard call is \section{...}.

Lamport's dream was to design his system so that simply changing the document class would typeset a document in a wide variety of formats. Alas, this proved to be impossible. For instance, the AMS classes want that the abstract is typed before \maketitle, for very good reasons. In the standard classes this would lead to a disaster. Other classes require specific commands for their various purposes.

The same AMS classes have a very interesting feature like \only (not very well documented, though) for deciding what parts of a section title are to go in the TOC and what are to go in the header, solving the problem in a different way from memoir.

Every time one uses additional features, the document will not be processable by the standard classes any more. So it's not generally possible to transfer a document from memoir to book, so the slight change in the syntax of \section is the least of the problems.

In my opinion, a class or package writer should be concerned with the user. If the syntax of \section is not really different from the “standard” one, call the command \section and don't think twice. On the other hand, if you'd like to change \section to have, even for some good reasons, two mandatory arguments, don't do it: users will almost surely forget one. Call the command \sectionx or whatever you deem sufficiently distinctive so that users will know they should do something different than usual.

Another example. Suppose your publisher wants that quotations are in italics: this is a case where redefining the quotation environment to change font is good. Providing a differently named environment would confuse users for another reason: they will continue to use quotation and the copy editor will live some nightmares.

Note that among the users you are included, especially if the class is for your personal use. You'll experience double personality problems when you need to use \section with the two mandatory arguments when the class is your own and the plain old \section when submitting a document to someone else.

A final example. In memoir when you say \listoffigures, the list will automatically be included in the table of contents and one can use \listoffigures* for not doing this inclusion. The AMS classes do the same but don't have a way to avoid the inclusion. Good: this is something the standard classes should have been endowed with in the first place, but unfortunately the idea wasn't considered. The problem with memoir is that \tableofcontents also adds itself in the TOC and one must remember typing \tableofcontents*. This is, in my opinion, a very bad error: it's like adding the inventory to the inventory. Nobody wants to be told, when reading the table of contents what page the TOC starts in: it's like instructions that say "for pushing button A, start pushing button A”.

Always remember the users of your class or package: don't force them to do bizarre mind twisting exercises.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.