Talk:LaTeX text formatting guidelines 2006

From DPWiki
Jump to navigation Jump to search

Holy cow

Holy cow. That's all. Just "Holy cow." Vaguery 10:51, 22 May 2006 (PDT)

I'm wondering whether we might consider breaking this into smaller pieces, once the formatting is more complete? It does seem to fall into nicely-separated sections. But as it stands, it's well over 100k, with the images.... Vaguery 13:56, 23 May 2006 (PDT)

Yeah, it's big--even though I already spun off the math section. What's a logical way to split in thirds or fourths? Or just spin off a couple of big sections, e.g. the special characters? Wwoods 14:11, 23 May 2006 (PDT)
Good question. The editors would say, "Let the document speak to you." I might say, "Give it a poke, and let somebody else clean it up if you get tired." :) Vaguery 14:15, 23 May 2006 (PDT)

Article structure

We could start by getting rid of the stuff that's unchanged from the normal DP guidelines (a lot of the stuff at the bottom about not silently correcting errors; the stuff about punctuation inside or outside italics....) Possibly there's a need to distinguish between (1) what's needed for normal foofers to do a normal page, and (2) what's needed on special pages like frontmatter. Possibly also (3) what really belongs in the realm of post-processing and (4) some things that are really more "tips 'n tricks". As a random example: what to do if there's a footnote inside a section heading. I don't know, just thinking out loud. Laurawisewell (?) <-- yes it was me. I've learnt how to sign my name now! Laura 13:27, 26 May 2006 (PDT)

I think what I was trying to say here was that we should maybe separate out the things one really has to know in order to format a LaTeX page OR would never think of looking up; and the things one would look up as and when needed. Things like blank lines, italics, smallcaps, and definitely the special things like full-stops that are or aren't ends of sentences should be in the first category; while poetry, tables and the like are in the second. Opinions? Laura 30 May 2006
We sure don't need a full tutorial on LaTeX. We do need the particular DP things, like what to do with ToCs, indexes, chapters, sections, comments, etc. And common errors like blank lines missing or added around displayed math, and spacing after periods. Table formatting could stand a page of its own.
Wwoods 13:44, 30 May 2006 (PDT)
(Oops forgot to sign my name again, duh!) Yeah the blank lines thing is definitely important, and the comments. But I feel that ToC and index should be separated out. Someone dipping into a LaTeX book is unlikely to get one of those, and if they do, they can either return the page or come and look up what to do. Basically my concern is to make this page as short and non-frightening as possible. There are some frightened people out there --see forumpost:207302. Laura 14:16, 30 May 2006 (PDT)

gen'l discuss

In my browser the Accented Characters for the Mac table is down at the bottom of the page, instead of where it belongs. Some quirk of HTML code running on a wiki page, I suppose. Anybody know what's wrong, or am I going to have to dissect that impressive piece of code? Wwoods 23:40, 22 May 2006 (PDT)

DCWilson fixed it. Wwoods 14:11, 23 May 2006 (PDT)

The section on Test-compiling pages might benefit from mentioning the soul package or \let\so\textbf for handling \so if spaced out text is used. Nicola K 06:22, 18 June 2007 (PDT)

I don't think the soul package would be used by sufficiently many projects to warrant its inclusion in a generic preamble. The section already mentions that project-specific packages etc need to be included: I've added the soul package there as an example. Dcwilson 22:26, 20 June 2007 (PDT)

I think it would be helpful to mention putting \ after a mid-sentence period to reduce the amount of space after it. It's used in the examples, eg \textit{Phil.\ Trans.} but not explained anywhere. I think people are more likely to remember to do it if this is pointed out specifically (and I'd forgotten about that issue, off to check my thesis...). Nicola K 06:22, 18 June 2007 (PDT)

The guidelines are supposed to be about how we use LaTeX at DP, not about how to use LaTeX properly. (If we start including guidance on general LaTeX style, the difficulty will be deciding where to stop…!) LaCheck—one of the tools that PPers are supposed to use—will detect unclothed periods, so it's not something that's crucial to get right in the formatting rounds. Dcwilson 22:26, 20 June 2007 (PDT)

Lists

In the part about lists of items: should we hard-code the item labels

\item[\textit{i}]

etc, in the same way as we hard-code theorems? Saves PP having to later find which were arabic numerals, which were roman, which were lower-case letters.... Laurawisewell (?)

Sounds good to me. Why don't you edit the guideline and see if anyone changes it back again :-) Dcwilson 05:02, 26 May 2006 (PDT)
The one above was indeed me as well. Hmm ok might try to edit the guideline. Laura 13:29, 26 May 2006 (PDT)
If we're going this way--which is fine with me--do we need to distinguish among itemize, enumerate, and [the other one]? Maybe we could just pick one for all lists? Wwoods 14:28, 26 May 2006 (PDT)
I think itemize should serve most purposes (and its name makes more sense for a generic list structure). The fewer ways we have to do the same thing the better! Dcwilson 03:42, 30 May 2006 (PDT)

Degree symbol

Is there a good reason we are recommended to use \circ instead of \degree? I see that's provided by the mathabx package, which seems not to be part of the standard distribution (because I don't have it). Would that be the good reason?

For example, if I'm trying to get "180°" and I use 180\circ, I get a medium-ish circle vertically centered, not a small circle up by the top of the zero. I've found that ^{\circ} looks pretty much like what I'd expect to see.

I'm hesitant, however, to just pop off and change something like these guidelines. rassilon 10:10, 6 July 2006 (PDT)

Yes, we don't want to load more packages than are needed, because the packages might get altered or discontinued. You're meant to superscript the \circ. But you don't need the curly brackets, just ^\circ will do. (FYI the ^ superscripts the next complete object after it, which may be a single letter, a group in braces, or a single command. Lots of things work like that, e.g. \frac12 is the same as \frac{1}{2}. ) Laurawisewell 10:07, 6 July 2006 (PDT)
Naturally, now that I look at what I thought was an example (it's really just part of an example in the section on dashes), they do use a superscripted \circ. [sighs heavily] I think, deep down, I knew somewhere that \frac12 is equivalent to \frac{1}{2}, but the latter is very much more intuitive; looking at it, I know instantly what's going to happen, while with the former I have to think about it! Well, I've been learning lots of things today, so that's another one! :) rassilon 10:22, 6 July 2006 (PDT)
The reason for ^\circ is (as Laura indicated) it works with a stock standard TeX distribution and the default Computer Modern fonts. To get a "proper" degree symbol you have to use a font which has one: this means other than CM and encodings other than OT1. There are many ways to do this depending on the available fonts, including packages like textcomp and mathcomp and output encodings like texnansi. If you simply leave the latin1 ° in the source, then inputenc[latin1] will provide a default mapping of this to ^\circ behind the scenes; if an output encoding package is loaded it can then redirect this to the actual degree symbol in the actual output font (and if no output encoding package is used we still get something resembling a degree symbol). Having written all this, I think it might be better for the guidelines to recommend using the latin1 degree symbol in the source, since then all the PPer has to do is play with output encoding packages rather than changing all the hardcoded ^\circs into explicit \textdegrees or whatever. Dcwilson 00:20, 7 July 2006 (PDT)
But, on my system, 1$^\circ$ and aren't identical, and the symbol in $1°$ just disappears.
— WWoods 10:26, 7 July 2006 (PDT)
Well, I wouldn't be using those anyway. I'd always go with $1^\circ$. Math 1 and text 1 may well be completely different fonts, and the Latin-1 degree symbol must only be a text character not at math one. Laurawisewell 10:34, 7 July 2006 (PDT)
I think the point is that ^\circ is wrong both semantically and typographically: a degree symbol is not a superscript composition operator. The right approach is for whatever is in the document body to encode the meaning of the text. You might use \textdegree explicitly, or just °, but definitely not ^\circ. Then you have the second problem of the visual presentation (which of course you do in the preamble). In the absence of a font containing a real degree symbol, you use ^\circ as an approximation, but by having the right code in the document body you allow a user with access to a different set of fonts to get superior output. By default you get ^\circ from either \textdegree or ° (with inputenc so TeX can read it). Try
\documentclass{book}
\usepackage[latin1]{inputenc} % [applemac]
\begin{document}
On my machine $1^\circ$ and 1° look the same and $1°$ works too but gives a warning.
\end{document}
Here ° is being mapped to \textdegree, which in turn is mapped to ^\circ (with a math switch if necessary), so all three should look the same but a typographically astute person (the sort who can spot the difference between a degree symbol and a masculine ordinal at twenty paces) would be aghast. (Bill, you must have had some additional packages in your preamble to lose ° in math mode.) To get a "real" degree symbol the preamble can be jazzed up a little to draw the glyph from any convenient font (although best practice would be to use a matching font!):
\documentclass{book}
\usepackage[latin1]{inputenc} % [applemac]
\makeatletter
  \input{ts1enc.def}
  \DeclareSymbolFont{TC}{TS1}{ptm}{m}{n} % or lmr or phv or... 
  \DeclareMathSymbol{\tcdegree}{\mathord}{TC}{176}
  \def\textdegree{\ensuremath{\tcdegree}}
\makeatother
\begin{document}
On my machine $1^\circ$ and 1° look different and $1°$ works too (because I killed the warning machinery with my \verb+\def+).
\end{document}
Here ° is still being mapped to \textdegree by inputenc, but now I am explicitly defining \textdegree to use a latin1 glyph (here stolen from Times Roman) instead of ^\circ. Note that the latin1 degree symbol can be used in both text and math. Dcwilson 06:07, 12 July 2006 (PDT)

Endnotes?

Since the section labeled "Footnotes/Endnotes" makes no mention of how to actually handle endnotes, I have to ask: Is there any consensus about those things? If not, perhaps a note could be added saying, in effect, "If you're working on a project with endnotes, ask how the PM/PP wants them done."

The suggestion in How to Draw a Straight Line was to do them as \Note{x}, with a line in the preamble like \newcommand\Note[1]{(#1)} so that won't produce an error on our ends when we test our single pages. Apparently that's easy for the PP because they just have to put a better definition in the preamble and then every \Note becomes a hyperlink. rassilon 00:26, 7 July 2006 (PDT)

Initials and honorifics

The guidelines currently say "Proofread G. B. Shaw as G.~B. Shaw." If I remember correctly (I will try to check tomorrow), the TeXbook recommends formatting this as G.~B.~Shaw. Also, the guidelines do not mention it, but generally honorifics should be similarly tied, as in Dr.~Nguyen. Dfeuer 01:38, 5 December 2006 (PST)

A tie/non-breaking space should only be used where a linebreak is to be avoided at all costs. Generally it's a bad idea to split someone's initials (although I have seen old books where three initials are broken after the second) so a tie is used. However, although desirable, it's not absolutely necessary to keep the initials with the surname, especially if the alternative is having to hyphenate the surname. The guidelines tend to err on the side of less markup. Likewise, honorifics generally do look better attached to their owner's name, but I'd rather allow a break between the honorific and the name than be forced to hyphenate the surname. So Prof.\ Frankenfurter is what I'd probably use.
The exception is when there is only one initial (or the honorific has only one letter). Typesetting convention is that very short "words" should be either avoided (which is why numbers less than ten are written as words not digits) or kept away from the ends of lines and paragraphs. So E.~Nesbit would be the appropriate markup. Dcwilson 18:13, 5 December 2006 (PST)
Sorry to respond so very late. Would it be reasonable to insert an enhanced line break penalty here without using a tie? Dfeuer 13:10, 27 December 2006 (PST)
This kind of refinement is best left for PPing. The distributed model of one-page-at-a-time formatting only works if the code is kept as simple as possible. The TeXpertise of formatters (and PPers) varies enormously, so it's best to keep scary plain TeX concepts out of sight. By all means leave suggestions for the PPer in %[**notes] but don't expect sophisticated formatting from the F rounds. Dcwilson 18:13, 27 December 2006 (PST)

Long dashes

Is there a reason that some of the examples of long dashes show them formatted as 7 hyphens rather than 6? Dfeuer 01:53, 5 December 2006 (PST)

Someone can't count ;-) Seven hyphens produce 2 emdashes and a hyphen, which looks a bit weird and not much like a long dash. Feel free to edit the examples! Dcwilson 18:22, 5 December 2006 (PST)
Fixed! Dfeuer 02:03, 16 December 2006 (PST)

Italics

The guidelines currently say

Punctuation goes outside the italics, unless it is an entire sentence or section that is italicized, or the punctuation is itself part of a phrase, title or abbreviation that is italicized.

This may be okay for HTML texts, but I don't think it's so great for LaTeX. There's a reason Knuth said you should italicize punctuation following italics: the spacing works out that way. -- Dfeuer 00:20, 15 December 2006 (PST)

I don't understand your point: can you give an example of how following the current guideline leads to typographic gaucherie? Dcwilson 17:34, 17 December 2006 (PST)
I got confused. Should've reviewed before posting. Apparently, some style books suggest punctuation should be italicized if the preceding text is in italics, but this is not universal. I was probably thinking about the italic correction that should not be applied when italicized text is followed by roman text. Apparently, LaTeX's \textit handles this automatically, whereas with the Plain TeX \it, it needs to be done manually. Sorry for the confusion. Dfeuer 16:35, 19 December 2006 (PST)