# Defining custom commands is bad style?

I recently received this in a e-mail from my professor

Good LaTeX style would preclude creating any of your own commands, counters, etc. (Most journals would reject submissions with user-defined commands.)

I have two questions:

1. Is this in fact true (both parts)?
2. Given that I am required to conform to a specific format and there is a lot of repetition (for example, I often have to use \qquad\textnormal) is there a way to define a command, and then when I run it produce a file that expands all of those macros?

Note: My understanding is that the standard way of doing this is to have the journal (or professor in this case) create a package that includes all of the things that are required to conform to the style that they want, but he does not seem to want to do that.

-
I’d say that defining own commands is the power of LaTeX, and it’s stupid not to use it, but I can’t speak for journals etc, it’s only my own opinion … –  Tobi Jan 30 at 22:09
Good LaTeX style would preclude creating any of your own commands, counters, etc. If this were true, then should we not use any of the wonderful packages that exist today? Should every document be 'vanilla'? –  cmhughes Jan 30 at 22:20
your professor is probably using LyX and you don't know it. –  percusse Jan 30 at 22:50
You could always create the style file yourself. Publish it on ctan and then it will be a standard package. (At least, if you use a suitable licence, it will probably be a standard package and end up in TeX Live etc.) –  cfr Jan 31 at 0:18
@cfr That's not quite true. Something being on CTAN itself is very far from being in both MikTeX and TeXlive. CTAN doesn't quite care about usefulness, the distros do a bit, and they review what gets in and what does not. –  tohecz Jan 31 at 1:16

Sorry, no, that is not true. Most journals do accept reasonable shortcuts:

\newcommand*\NN{\mathbb{N}} % natural numbers
\newcommand*\AA{\mathcal{A}} % automaton
\newcommand*\WWW{\mathring{W}^2_1} % Sobolev space 2,1,o
\newcommand*\defined[1]{\emph{#1}} % used for defining new terms
\DeclarePairedDelimiter\abs{\lvert}{\rvert} % proper absolute value
...


However, the will likely not accept stupid definitions, such as:

\newcommand\pf{\begin{proof}} % don't hide a structure behind some ridiculous macros
\newcommand\pfe{\end{proof}}
\newcommand\eqa{\begin{eqnarray}} % twice bad, once for the shorthand ...
\newcommand\eqae{\end{eqnarray}} % ... and second time for using eqnarray
\renewcommand\em{\sc} % not speaking about the fact that the ...
\renewcommand\bf{\it} % ... two-letter font macros are depricated
\newcommand\SPACE{\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ }
\newcommand\Hs{Hilbert space\xspace} % no text replacement shorthands like this please!
\def\A{{\cal A}} % this is bad in 3 ways -- can you guess what are they?
...


1. Define everything only once (no \NN and \Naturals doing the same stuff).
2. Define only things you really use (no 100 lines of definitions with only 5 of them being used).
3. Do not re-define stuff that already exists.
4. Use proper LaTeX's \newcommand instead of just \def.
5. Place everything in the preamble.
6. Include short comments to each \newcommand, like I did above. Especially if you do any dirty stuff. However:
7. Do not do any dirty stuff.

(Speaking as a typesetting editor of a journal, and as an author of numerous publications where I use definitions like the good ones above.)

-
Is there any way to get all of my macros (those not in any packages say) to be expanded in the source file (or even a second source file)? –  soandos Jan 30 at 22:31
I have to remark here that sometimes journal is the stupid one that doesn't understand proper TeX code though. Yes IEEE I'm looking at you. –  percusse Jan 30 at 22:54
@soandos You are looking for this I think: Is there a script that reads a TeX file and replaces every instance of a \newcommand? –  tohecz Jan 30 at 23:40
@Canageek For your document, it's quite fine. For a document you sumbit, it is less. Really depends on the journal. My point of view: I basically never refuse an article because of "bad LaTeX style", but the more crappy stuff I get, the less good output I make; the time I can spend on each article is somehow limited, so the easier you make the work for me, the better the article is typeset in the end. –  tohecz Jan 30 at 23:42
@percusse Yes, I'm aware of this. In all honesty, it's not the only problem the IEEE journals have, in my opinion. –  tohecz Jan 30 at 23:44

This is only partly true, and only in certain circumstances. Good LaTeX style depends on several things, but normally one tries for three things: 1. portability, 2. logical mark-up and 3. readability/editability.

Package use can affect portability, so one should normaly eliminate any that are not absolutely needed. A journal may send back a submission that fails because they don't have a particular package or because they have a different version. Often they will not debug to find out which package is at fault and ask you to omit them all!

Logical mark-up almosts requires making ones own commands. It is much better to define a macro with a name that reflects the reason for the \qquad\textnormal{...} than to have to repeat such a sequence often.

Readability is also improved with a well-chosen macro name, but editability is not. An editor may want to change that \qquad of space, but has to constantly go back to the preamble and read through the definitions to know which macro to edit. And if the author's mark-up is inconsistent (same command for spaces in different contexts), the editor may have to find every occurrence and change them to different size spaces.

Logical mark-up sometimes has to be balanced with editability. While it is easy to edit \qquad down to \quad, it may be harder to read your special command and deduce that that is what needs to be to changed. After many years of trying to get my papers to look as nice as possible, I now keep new commands to a minimum. Mostly only \newtheorems (because none are defined by default) and the few \DeclareMathOperators that LaTeX and amsmath neglected to supply. I use \documentclass{article} and load just a few packages, sometimes only amsmath. (Of course, if I self-publish a document for my own use, I go wild.)

I have seen many papers with hundreds of macros, most of then simply indecipherable shortcuts for some much more readable combination of commands, many never even used. Such things are a nightmare to edit. One appreciates why an editor or professor would not want to see that, and why a journal might include instructions (as many do) to write the paper "without any user-defined commands".

Your professor has probably seen many such instructions and jumped to the conclusion that it is "good style". Still, you should try to keep him happy. You might start by asking whether you need to have so many \qquad\textnormal and if some other approach might be better. In the event that you must have them, it should be trivial to turn all your single commands into this expanded version with global search-and-replace in your text editor.

-
Is there a way to automate that find and replace bit? (i.e. produce a different .tex file that has all macros defined in the file i give it expanded, but no others) –  soandos Jan 30 at 22:49
@soandos Well, there are scripting languages (e.g., sed) that do such things almost instantaneously. But what I would do is make a copy of the file, open it in the editor, and run a find/replace (under the Edit menu in most editors). Would take me about 30 seconds. –  Dan Jan 30 at 23:20
I agree with you in principle, but if possible, I would like to automate this –  soandos Jan 30 at 23:27
sed 's/\\mycommand{/\\qquad\\textnormal{/g' <workingfile.tex> > publicfile.tex. Put it in a script if you prefer so that you can just run myscript <workingfile.tex> <publicfile.tex> or whatever. You can also probably get your editor to do this conversion for you on demand. –  cfr Jan 31 at 0:27
–  tohecz Jan 31 at 1:15

I agree that some reasonable shortcuts should not pose a problem. However an editor needs to make sure that the layout is consistent throughout the issue. Avoid any constructs that break the layout / text flow / … Your code should be short and easy to understand. The command names should clearly indicate what the command does. Also consider that LaTeX has no namespace concept. It might be that the editor defined some commands with the same names himself. In this case you break his workflow.

-
Though you are officially a member for about one a half year: Welcome to TeX.SX! You can have a look at our starter guide to familiarize yourself further with our format. –  Speravir Jan 31 at 0:20

Journals in my field (oceanography and geophysics) tend not to permit using new macros. This is true of the popular suite of journals from the American Geophysical Union. I think the issue is that they use conversion software to change the latex into another markup language, from which they then generate html, latex and whatever might make sense in the future.

Most people find this annoying at first, but soon realize that a lot of their macros are not truly needed. For example, aesthetic tweaks will get deleted by the journal anyway, because they want to decide on such things, to maintain uniformity. As for macros that save typing, this is something that is probably better handled by a good text editor, e.g. Emacs and Vim both have macro handling facilities that will expand abbreviations into their full form.

I've used Tex almost since it was first written, and latex for as long as it's been available, and I find that macros are wonderful for content I intent to publish by myself (e.g. in-house course notes), but journal publishing is really quite another thing ... there, the focus should be entirely on the material being communicated, and not at all on how it looks on the page because someone else will be at the helm.

-