34

Just yesterday I had to patch a package file (changing the description to indicate that the file had changed) to replace some \par to \endgraf because the code had bad interactions with non-\long macros.

When writing a package, are there cases where it is better to use \par than \endgraf?

Martin Schröder
  • 15,156
Bruno Le Floch
  • 44,937
  • 7
    maybe it would be better to phrase this question the other way around -- "when is it better (or necessary) to use \endgraf rather than \par? – barbara beeton Feb 05 '13 at 13:41
  • @barbarabeeton That is a slightly different question. It is for instance better to use \endgraf than \par when the code might be used within the argument of a non-\long macro. My question is to know why anyone would use \par rather than \endgraf, since I thought that the definition of the latter is \def\endgraf{\par} and as such most often behaves identically. David provides a case where \par is correct but not \endgraf. – Bruno Le Floch Feb 05 '13 at 18:53
  • 2
    The definition of \endgraf is, of course, \let\endgraf\par. For some of us, \endgraf comes to the mind from the old days of Plain TeX; it has to be the "primitive \par" or \let\par\endgraf would pose some small problems. ;-) And LaTeX uses it all the time in the form \let\par\@@par. You use \@@par (or \endgraf, the same) when you are sure you want the primitive meaning of \par. – egreg Feb 05 '13 at 21:08

3 Answers3

35

I would approach the answer to the question a bit differently (though it is essentially equiv to what David said):

  • \par in LaTeX is equivalent to an empty line in the user document! Whatever the LaTeX gives as meaning to the "empty line" in a certain context is what \par would result to. Example given by David: in a tabular empty lines are ignored. But other usages are possible too.
  • \endgraf in contrast is the primitive that "ends horizontal mode and breaks the material into lines given current parameters (or generates an error in places or does nothing if already in vertical mode ... add remaining subclasses of he primitive behavior here ...)".

In most cases \par runs the primitive behind \endgraf but not in all; sometimes it does additional things or other things.

So use \endgraf when you want to run the primitive and \par whenever you want the action that the user get (in current context) that is documented as the behavior of an empty line.

Frank Mittelbach
  • 77,146
  • How do you see this in a LaTeX3 context (where we really don't want anyone executing \tex_par:D outside of l3galley)? – Joseph Wright Feb 06 '13 at 15:34
  • @JosephWright in exactly the same way: abstractly speaking \par implements an abstract user/document level interface and \endgraf a specific technical operation. Now with LaTeX2e or plain TeX this operation is directly the primitive from the engine. With LaTeX3 this may be a more granular set of tools instead and the direct engine primitive is unavailable. But the principle is the same. l3galley in its final form will not be a "possible" optional thing but a core platform foundation on which other packages use the interfaces (i.e., there will be no outside or if, then only a controlled one) – Frank Mittelbach Feb 06 '13 at 16:06
  • @FrankMittelbach why does LaTeX even define \endgraf when it has \@@par? Is a (document level) user ever supposed to be using \@@par/\endgraf at all? – cgnieder May 23 '14 at 16:33
  • @cgnieder part of this is historical: \endgraf is a plain TeX command and LaTeX retained it. On the other hand LaTeX used @@... for storing away anything that it wants to keep an internally frozen for code usage. So no: @@par is not intended for user level while \endgraf was (by Don) and although it is not explicitly documented in LaTeX for this purpose one can argue that \endgraf is a user level command in LaTeX. Personally I think it is a but dangerous as you need to really understand the above difference (and partly how LaTeX does \par redefs) to make good use of \endgraf. – Frank Mittelbach May 24 '14 at 07:59
  • @FrankMittelbach Thanks. The fact that I have never used \endgraf (or \@@par) in my 10+ years of using LaTeX makes me think that use cases would be rare, anyway. (Besides smuggling \par in a short macro maybe which I've always done with sth like \newcommand*\parwrapper{\par}...) – cgnieder May 24 '14 at 12:33
23

It depends whether the commands you are defining are ever going to be executed at a place where \par doesn't mean \endgraf. For example latex.ltx has

  \let\tabularnewline\\%
    \let\par\@empty

so if you might want to be evaluated in the scope of those definitions you have to decide whether you want the current definition of \par or of \endgraf.

David Carlisle
  • 757,742
  • Should I ask a follow up question on why \endgraf is \let to the \par primitive, and not defined to expand to \par? – Bruno Le Floch Feb 05 '13 at 18:54
  • 4
    That would be dangerous. Lots of code assumes it os not expandable, although etex protected def would probably fix that, but if you have \vbox{...\color@endgroup} then if your don't get out of vertical mode before the } things would go wrong. You are allowed to assume \endgraf is the primitive, you can't assume anything about \par. – David Carlisle Feb 05 '13 at 19:45
  • @BrunoLeFloch actually \endgraf is a historic leftover from plain TeX and you should not use it at all in LaTeX code, you should use @@par to indicate that it is the primitive you are after. – Frank Mittelbach Feb 06 '13 at 16:29
  • @FrankMittelbach In my situation I was not after the primitive \@@par, but I wanted to use \par within a short macro's argument. This means that I needed something defined as \def\foobar{\par}, or I needed \csname par\endcsname. – Bruno Le Floch Feb 06 '13 at 17:29
17

in many places, latex defines \par (usually via \everypar) to do a lot of non-obvious things, things which most ordinary users (and even some "experts") haven't investigated and aren't aware of. using \endgraf in these situations can lead to unexpected results.

some places where \par is much safer are

  • for multiple paragraphs within one \item in a list

  • at the end of a paragraph delimited (grouped) in braces

note that a blank line in these contexts is equivalent to \par, not \endgraf.

in certain situations, such as within a footnote in plain tex, \par isn't accepted, and \endgraf must be used instead. however, latex.ltx contains the line \let\endgraf=\par so i'm not really sure where \endgraf would be required in latex. (i've been corrupted sufficiently by long years of using plain tex that i sometimes get these things confused.)

barbara beeton
  • 88,848