18

I'm trying to read source2e.pdf (texdoc source2e on the command line), but I'm stumped. It seems a rather mysterious tome to me. As I understand from this answer about what arguments a command expects, a source file is somehow the de facto "complete reference" for LaTeX macros that a particular package provides. source2e.pdf doesn't provide clues as to where to start reading. The beginning chapters ltdirchk.dtx, ltplain.dtx, etc. don't seem to help.

Are there guidelines on how to read source files? Or is there prerequisite knowledge that I might have missed? I'm familiar with the syntax, and I would like to know what options and arguments are available for a particular command.

In response to TH's answer:
I come from a programming background. I see that LaTeX has many elements of programming such as macros, commands, arguments, etc. So I'm approaching it the way I would learn a new programming language.

To put it simply:
If, in the course of tutorial, I read about italicizing text using \textit. For some odd reason, the tutorial didn't mention how to make bold text. Instinctively as a programmer, I would want to look up a reference library, go to the Text Formatting section, then, "Aha! Here are all the macros for formatting text!". There, I'll find things like italicize, bold, underline, strikethrough, superscript, subscript, etc., as well as syntax guidelines and some live examples.

Another example:
When I learn that a particular package has an \author macro, I'll say, "Aha! This package has capabilities to make writing front matter easier." So I would want to look up the reference library, then see all the other capabilities, like the date, or even specifying a separate title page.

About tutorials and reference libraries:
For me, tutorials are what I call a "linear" mode of learning, e.g. step-by-step or ouido. They make a good launch pad from which I learn what a particular tool is able to do. In my example above, I learned that LaTeX can italicize text. I think to myself "Oh, LaTeX can do some fancy text formatting, therefore it must be able to do other related things."

At this point, I switch to "hierarchical" mode of learning. I begin to classify the capabilities as Text Formatting, or Front Matter, then I'll know how to look for it in the reference library.

What I'm trying to get from reading commented sources:
I want to see how LaTeX macros are related to each other, then I'll be able to effectively use my "hierarchical" learning approach. Also have a look here (same link as at the beginning of the question). I want to be able to read through all the @'s and {#1}%'s and {#2}%'s. So I'm also looking for guidelines on what all those symbols mean.

Improve this question
5
  • 2
    If what you're after is figuring out the options for a particular command, you're better off looking for the documentation of that command (e.g. in the TeX/LaTeX books), or asking a new question here about how that particular command works.
    – Juan A. Navarro
    Sep 13, 2010 at 17:12
  • It’s usually more effective to look for commands and and concepts of LaTeX in reference books.
    – Caramdir
    Sep 14, 2010 at 0:44
  • For your specific question: @ is treated like a letter (so it has no specific meaning), #1 is the value of the first parameter of a command that is being defined and % starts a comment (which has the side effect of preventing TeX to see the newline and any whitespace at the beginning of the following line).
    – Caramdir
    Sep 14, 2010 at 0:52
  • 1
    As I've explained elsewhere, TeX (almost) always ignores spaces at the beginning of the line. Briefly, TeX has three states, N, M, and S. In states N and S, it ignores spaces. Each line starts in state N. The first nonspace character encountered puts TeX into state M. After reading a space, it goes into mode S. If it reaches an end of line character (which TeX inserts at the end of each line of input) in state S, it produces a \par token; in state M, it produces a space token; in state S, it is ignored. % at the end of the line inhibits the end of line character from taking effect.
    – TH.
    Sep 14, 2010 at 1:36
  • 2
    Yikes! Rereading my comment, I made a huge mistake there. If TeX reaches the end of line character in state N, it produces a \par token. Not state S.
    – TH.
    Dec 19, 2010 at 13:55

1 Answer 1

Reset to default
12

What is it you're hoping to get out of reading the source to LaTeX? One piece of information that might be important to reading the source is how doc/docstrip works. That accounts for all of the lines like <initex> that appear. Beyond that, source2e.pdf is just a combination of documentation and the source code to LaTeX2e. It's readable, but more importantly, it's searchable.

I frequently just search it for the macro I'm interested in to see how it works.

Edit: In response to your updated question, I'd say that reading the LaTeX source is akin to reading the source code to GCC (or the C library) to learn how to program C, a frustrating and probably fruitless endeavor.

You have the right idea regarding your linear and hierarchal learning and general approach to learning how to program in TeX, but I think you're looking in the wrong place for answers. For individual packages (e.g., geometry) you should read the package documentation. If you use TeX Live, this documentation is already installed. Run texdoc packagename in a terminal to see the documentation. For the standard LaTeX macros and environments, I'm not really sure what the best source of information is. There is Lamport's book which I find lacking. The LaTeX Companion is good but a lot of that information is contained in the individual package documentation. See the answers to this question for a list of good references.

If you're looking to program TeX, I think there is no better book than the TeXbook by Knuth. It describes everything there is to know about TeX, in more or less detail. People also typically recommend TeX by Topic, but I haven't gotten around to reading it.

Improve this answer
6
  • Thanks :) see my response at the question section about what I want to get out of reading the commented source file.
    – Kit
    Sep 13, 2010 at 23:48
  • 1
    By contrast, reading the source to Plain Tex is a useful thing to do. It weighs in at 1200 lines of adequately commented primitive Tex, vs. the, well, I don't know, wc -l $TEXLIVEROOT/texmf-dist/source/latex/base/*.dtx gives 67205 lines.
    – Charles Stewart
    Sep 14, 2010 at 12:14
  • @Charles: Neat -- I had no idea Plain Tex was so short!
    – SamB
    Sep 16, 2010 at 18:17
  • 1
    @Charles Stewart: Of course all of the .dtx files contain the standard docstrip boilerplate as well as, in many cases, extensive LaTeX code for pseudocode and other documentation. This is always the problem with literate programming, I've found: the "woven" documentation might be readable, but the file that produced it is much more complicated than a normal commented source file.
    – TH.
    Sep 16, 2010 at 23:30
  • @TH.: Which sounds like you are saying, you have not much more idea than I about how to fairly compare the two. I tend to read the .dtx files directly, rather than navigate between the various files output by docstrip: it's readable enough, but it's much harder to get an overall sense of what's going on. But now we have tex.sx with people like Joseph, Will & Ulrike to help us with that.
    – Charles Stewart
    Sep 17, 2010 at 8:05

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .