18

Does there exist some concise documentation showing, for things commonly done in plain TeX, the recommended/idiomatic “LaTeX way” of doing something equivalent? Or if not, what are the most common such things to know?

Background/context: Recently, while answering a question about an unusual page layout, I first wrote an answer in plain TeX, then started trying to make it work with LaTeX. In doing this, I discovered a few things, like:

  1. In LaTeX (and with typical document classes I guess), to change the dimensions of the main text area, don't directly change \hsize and \vsize. Instead, it is simplest to change \textwidth and \textheight.
  2. To control the page output, don't redefine what \output does with \box255, but what \@outputpage does with \box\@outputbox.
  3. To affect the offset of the main text area on the page, change not just \hoffset and \voffset, but also \oddsidemargin, \evensidemargin, \topmargin, \headheight, and \headsep.
  4. The page numbering counter is stored not in a TeX count register called \pageno but in a LaTeX counter called page.

These are just examples (and some may be wrong); I'm asking about the general case where someone has written some (relatively straightforward) plain TeX document (understanding what it does), and wants to change it to work with LaTeX. What would be some useful things to know, in this case?

I'm aware that this may not be a question with a perfect answer, so I'd be perfectly happy with any of the following kinds of answers:

  • There is such a document, at [location]. Or: there are only a few main things to know, namely [list].

  • There is no such document: you simply have to learn the whole of LaTeX by reading [Book1], [Book2], and/or by reading through the LaTeX sources (texdoc source2e).

  • There are a few kinds of things, and each of them is covered in a different kind of documentation: [X] for topic [T1], [Y] for topic [T2], …

  • If you're using simple plain TeX, the main thing to know is the LaTeX equivalents of facilities provided by the ~1000-line plain.tex. A translation of those into LaTeX is: […].

Edit: It has been pointed out to me that in a LaTeX document one should simply not do any of the above things. And I completely agree!

I should have made this clear earlier, but I was not thinking clearly myself:

  • In a LaTeX document, as a “user” of LaTeX, one should not resort to such “raw” typesetting. (So the answer to the above question, if it's being asked as a LaTeX user, is “just don't do that”.) Instead, one expresses one's intentions as some combination of invocations of package-provided commands.

  • In a LaTeX package or class, as the author of the package/class, is the only place to fiddle with typesetting. My question is about this part: where can you learn the LaTeX equivalents of such plain TeX commands, to accomplish common typesetting solutions in LaTeX? (I do understand that you should then also provide good commands so that users of your package can express themselves logically/semantically.)

For example, from plain-TeX version in revision 1 of the linked answer, to get something that compiles in LaTeX (let's say I wanted to make it a package), I cobbled together something through a combination of reading source2e.pdf, reading other packages' implementations (poorly commented) of similar solutions, randomly searching the internet and this site, using \show and \message to debug what's going on, and sometimes pure guesswork. My question is: if you want to write a package to accomplish certain kind of typesetting, where would one learn this instead?

ShreevatsaR
  • 45,428
  • 10
  • 117
  • 149
  • Tidied up a bit ;). – cfr May 11 '17 at 01:32
  • 1
    Mostly the LaTeX way is to use packages, like setting the page size using geometry. There is also the beamer way and the KOMA way. BTW, the counter page or count \c@page still use register \count0. Also, you can use the plain package to ease your transition. – John Kormylo May 11 '17 at 04:53
  • My biggest gripe was replacing \over with \frac (which I was convinced was introduced by a Battlestar Galactica fan just to use the word frac). – John Kormylo May 11 '17 at 04:58
  • @JohnKormylo Yes that's a good point—in fact that's what the conversation with @-cfr earlier was about. I've edited the question to clarify that that's not what I'm looking for. – ShreevatsaR May 11 '17 at 04:58
  • 1
    I don't think there is much existing documentation taking this point of view as (unlike in 1985) there are to a first approximation no readers for such a document. The vast majority of people learn latex first and only learn plain to construct simpler debugging examples and test cases or to understand the examples in the texbook. So at that level they need plain (or tex primitive) descriptions of latex constructs from an implementation level, not a simple user guide for plain tex authors. – David Carlisle May 11 '17 at 06:59
  • you might want to look at the latex package plain which defines plain tex constructs (\pageno etc) for latex) – David Carlisle May 11 '17 at 07:07
  • @DavidCarlisle What about package authors? Where do they learn how to do things like changing where headers and footers go on a page (or output routines)? And basically an idea of what all the program is doing, so that they know which parts to modify if necessary? (And thanks, your plain package aka plain-ltx seems relevant…) – ShreevatsaR May 11 '17 at 07:13
  • @ShreevatsaR I think you need to decide which question you want to ask:-) A document aimed at package authors describing how to customise the page headers does not need to mention plain tex at all so I think would not answer this question – David Carlisle May 11 '17 at 08:43
  • @DavidCarlisle Yes I know I sound confused :-) I think the confusion arises because TeX itself is both: (1) as plain, a format for authors to write documents in, and (2) as a program (often confusingly called "plain TeX" to distinguish from LaTeX), a tool for typesetting. (Even kinds of documents not considered before.) My question is about the latter: “using LaTeX as a tool for typesetting”: where does one learn LaTeX ways to accomplish near-arbitrary (within the limits of TeX) typesetting tasks using LaTeX as a tool (apart from "just find and use existing packages"). – ShreevatsaR May 11 '17 at 09:14
  • @DavidCarlisle So “a document aimed at package authors describing how to ” is what I was looking for. Maybe it doesn't have to mention plain TeX necessarily, you're right…. but every book I've seen on TeX suggests how to achieve typesetting results by putting together building blocks in ad-hoc ways, but LaTeX books/documentation generally doesn't. So I imagine more plain TeX users are thinking along "how can I put together boxes to get this" than LaTeX users are. So something aimed at such readers would help (and answer). – ShreevatsaR May 11 '17 at 09:26
  • @DavidCarlisle Figured out the right question :-) Tying everything together (and what I had in mind from the start): Is there documentation on becoming a LaTeX package author (of all sorts of packages), aimed at someone who is a plain TeX package author? (Aka simply a plain TeX user: they are the same in plain TeX, but different in LaTeX.) If not, then well… documentation aimed at the general person would be the closest thing I suppose. – ShreevatsaR May 11 '17 at 10:00
  • Two PDF documents you can and should download from CTAN are source2e and symbols. – John Kormylo May 12 '17 at 12:36
  • @JohnKormylo - "My biggest gripe was replacing \over with \frac" -- for a different view, take a look at the posting What is the difference between \over and \frac? :-) – Mico May 14 '17 at 07:10
  • Correct me if I'm wrong, but source2e may be assumed to document the API for LaTeX2e, right? – jarnosc May 16 '17 at 22:47
  • @erreka That's my assumption too, and one of the possible answers that I suggested (search for texdoc source2e in the question)… I was hoping someone would confirm it though :-) But I think the answer is more subtle than that. I should post an answer with what I understand, and see if anyone downvotes it. – ShreevatsaR May 16 '17 at 23:05

2 Answers2

19

First some personal experience: for one of the conference proceedings I was in charge of for the TeXnical aspects, I got several papers to put into shape. One of them was in Word: I asked for a printout and then converted the “saved as text” version line by line following the printout.

Another one was in plain TeX. The conversion was quite easy: I changed the initial macro definitions to use \newcommand or \newtheorem; then I went through the document and the translation to LaTeX was a rather short and easy job.

Much more painful was translating most papers from their authors' concept of LaTeX to the real one.

About your specific points in the list, here's my two cent.

  1. You never use \hsize in a LaTeX document, not even in the preamble (sole exceptions, some tricks with tabularx). Using \textwidth is not “simpler”: would you say that driving on the left side in the UK is simpler? Well, it's the same: setting the text width with \hsize is like driving on the right side in the UK.

  2. You never (with no exception) change \@outputpage, unless your name is Frank and you're German (plus some other strict conditions).

  3. While it's possible to specify page parameters by explicitly changing \oddsidemargin and friends, it's much better done with geometry. By the way, \hoffset and \voffset should always be zero.

  4. The current value of the page number is accessible as \thepage (which changes according to the chosen numbering style). Using \value{page} (or \c@page) should be a very rare need. Besides, one should not use \pageno in plain TeX document, but \folio, that's analogous to \thepage.

Probably your point 2 is about adding structure the the header and footer; this is done with packages such as fancyhdr, scrlayer-scrpage or titleps.

If you use \beginsection and \proclaim, it's not difficult to switch to LaTeX; of course, you'll remove all manually assigned numbers.

Most common plain TeX constructions work also in LaTeX; the manual mentions \line among those having different meaning. Of course, no font selection command will work.

However, the mere fact that a plain TeX macro also works in LaTeX should not mean we can keep it. A typical example is \centerline, that has essentially no place in a LaTeX document (it's not color safe, for instance), but also \root 3\of{2017} should not be used.

Yes, I know that \centerline can in some cases get me simply out of a problem, but such usages should always be buried in macros defined in the preamble.

The well structured plain TeX document I mentioned before, was written in a logical fashion, with consistent markup. The markup was not the same as in LaTeX, but this was not a problem: I just had to make a translation table and apply some search-and-replace.

A badly written document, using plain TeX, AMS-TeX, ConTeXt, LaTeX, Lollipop or whatever format, is just badly written and sometimes it's a pain also making it a valid document for the original format.

egreg
  • 1,121,712
  • Thanks for an answer! I understand your answer as recommending what good LaTeX style is. (And I agree.) But the question I intended was rather: TeX itself is IMO simple to understand, at least in the way that assembly/machine language is simple to understand: it may be hard to get things done in it, but it is revealing of what's going on underneath: you know all that it is: a paragraph builder, a page builder, a “mouth” for macros… boxes and glue, this and that. It's just a tool that is transparent (though could be better). LaTeX is much more (structure etc.) and that's of course its strength… – ShreevatsaR May 11 '17 at 07:49
  • … Concretely: in the linked Q, I looked at a page, saw all that should go on the page, thought about how to use the tool (TeX) to achieve that output, and simply used the tool. (Of course, lacking experience, I may not have done things well, but at least I was able to understand the tool enough to accomplish something.) What would be the equivalent in LaTeX? First step would be: study the package ecosystem… but suppose I realized I had to write a package myself, now what? How does one know how to accomplish such things using the tool (LaTeX)? – ShreevatsaR May 11 '17 at 07:53
  • @ShreevatsaR The main defect of plain TeX is indeed it doesn't provide enough high level structures and users tend to use ad hoc solutions. I was looking at the source of the TeXbook and saw something like \raise.5ex\vbox{\hrule width 1em} which should instead be a macro defined once and for all. LaTeX is meant to relieve the user from going too deep in the “assembler code”. – egreg May 11 '17 at 08:19
  • To restate my question concisely: how should I have learned how to get from the plain TeX code at the bottom of revision 1 to LaTeX code? (A partial attempt is at the bottom of that answer.) The way I did it was by a combination of reading source2e.pdf, reading other packages' implementations of similar problems, using \show, and pure guesswork. What would a better way have been? Where could one learn it? – ShreevatsaR May 11 '17 at 08:22
  • @ShreevatsaR Starting from a LaTeX document, not trying to convert to it. I'll have a closer look later at your attempt. – egreg May 11 '17 at 08:23
  • I fully agree with @ShreevatsaR comments. LaTeX brings only more complications over simple tool named TeX. And the recommendation about: "go and study source2e or package sources" cannot be accepted by me, because there is many occurrences of bad programming style or bad concepts. – wipet May 11 '17 at 08:28
  • 5
    my name isn't Frank:( – David Carlisle May 11 '17 at 08:45
  • @DavidCarlisle Then you're not allowed changing it (the all mighty egreg has spoken!) :) – Skillmon May 11 '17 at 08:46
  • @ShreevatsaR I don't think you need to plunge into source2e for that task; using the standard header and footer is sufficient: just suitably define some boxes. – egreg May 11 '17 at 10:39
  • @ShreevatsaR I added some code for the linked question. – egreg May 11 '17 at 11:34
  • @egreg Thank you! But I think it sidesteps the main question: if the package fancyhdr didn't already exist, where would one learn how to write it? (I'm not exactly asking where Piet van Oostrum learned what he needed to write that package, but in general… how does one learn what's the LaTeX way of accomplishing new things that aren't in any package?) – ShreevatsaR May 12 '17 at 04:46
  • 2
    @ShreevatsaR That's the main difference between Plain TeX and LaTeX: you usually don't have to reinvent the wheel, because somebody already has. – egreg May 12 '17 at 08:05
  • @egreg I agree with that too. Usually somebody already has, but I'm trying to learn about the remaining case :-) To ask the same thing in different ways: (1) What if nobody already has done exactly the same thing: how would one learn how to write a new package? (2) What about say 5 years ago, when the packages written in the last 5 years didn't exist? What was the right way for those packages' authors to learn whatever they did? (3) What if I want to modify/extend/rewrite/refactor an existing package? How does one learn what is the proper way it must be written, etc. – ShreevatsaR May 12 '17 at 18:25
  • @egreg -- minority report here. just because there is already a package, doesn't mean it can be used. lots of packages are incompatible with various classes and with each other. i find that a reasonable way to address a problem is to find something that is sort of what i'm looking for, determine whether it's well written (off the potential list if it's not), and steal the ideas. (but i can't claim to be a novice, so the method might not work for someone who is.) – barbara beeton May 26 '17 at 20:04
3

Perhaps my suggestion won't satisfy the "concise" requirement of your question, and still it's not at all clear to me what exactly do you want; but fwiw, I doubt there is an easy way to transition from Plain to LaTeX hacker as you mean to do. Afaik there is no LaTeX Programming Manual for LaTeX2e, and the one planned for LaTeX3 is still fairly elementary. So, in the meanwhile, I recommend to you to find a copy of Winter Snow's TeX for the Beginner, where the author occasionally compares some Plain hacks with their LaTeX counterparts.

jarnosc
  • 4,266