5 ms·
LaTeX Style Guide for EE 364B [pdf] (2014)
- vitorsr 2y agoThis is great advice. I only contend on two things. First is recommending Strunk and White - in general a style guide should not stifle writers' voices and instead equip them with tools to express their own. Here I would rather recommend the far more authoritative and comprehensive The Chicago Manual of Style [1]. Second is excess punctuation - easily incurs in too much line noise. You should generally avoid adding distracting elements seldom added pro forma. The best source for me has been the Handbook of Writing for the Mathematical Sciences by Nicholas J. Higham [1]. His I can fully get behind. Another is Writing Mathematics Well by Leonard Gillman [3]. Still another is Mathematical Writing by Franco Vivaldi [4]. [1] https://www.chicagomanualofstyle.org/home.html https://www.chicagomanualofstyle.org/home.html [2] https://epubs.siam.org/doi/book/10.1137/1.9781611976106 https://epubs.siam.org/doi/book/10.1137/1.9781611976106 [3] https://bookstore.ams.org/mmbk-7/ https://bookstore.ams.org/mmbk-7/ [4] https://link.springer.com/book/10.1007/978-1-4471-6527-9 https://link.springer.com/book/10.1007/978-1-4471-6527-9
- antegamisou 2y agoMay I add a more concise yet helpful presentation of Prof. Bertsekas Ten Simple Rules for Mathematical Writing https://www.mit.edu/~dimitrib/Ten_Rules.pdf https://www.mit.edu/~dimitrib/Ten_Rules.pdf
- sumnole 2y agoDoes anyone have suggestions for math textbooks that follow these writing rules?
- dawnofdusk 2y agoBertsekas' textbooks of course, which I think are very well-written and a pleasure to read.
- vitorsr 2y agoNice! I haven't seen this one yet. I submitted a link here earlier in the same spirit that you might appreciate: https://hn.algolia.com/?query=%22https://mathcomm.org/writing/teaching-writing%22 https://hn.algolia.com/?query=%22https://mathcomm.org/writin...
- hookahboy 2y agoWith regard to your comment, and since we are on the subject of style, I would rephrase "... only contend on two things" as "... only differ on two things". While it is grammatically correct, it feels awkward.
- vitorsr 2y agoYou're right, thanks. English is not my mother tongue so I still fall for some language traps.
- zmgsabst 2y agoI would comment to drop the preposition: “…only contend two things” I think the trouble in the phrase is that “contend” has an active sense to it whereas “on” creates a more passive tone. Your solution is to swap to a more passive phrasing, but the alternative is also available.
- marhee 2y agoWhy does “I contend” feel awkward to you? It is more specific than “I differ” because that could also mean that the author physically differs, which is awkward, while “contend” is specifically used for disagreement on some topic? Does “I contend” maybe has a ring to it of being scholastic/pretentious? (Also non-native English, just curious)
- quuxplusone 2y agoWell, particularly in a subthread on Strunk & White, one should write "...differ on only two points" or "...contest only two points." It's not that we ONLY contest these points (we may also, e.g., state them or rephrase them). It's that we contest ONLY these two (and no others). See the antepenultimate example of Rule II.16, "Keep related words together."
- quercusa 2y agoI vote for 'and'. Strunk & White and the CMS serve different purposes; the latter is more of a reference work but both are valuable.
- nanna 2y agoAlso bear in mind that Strunk and White's Elements of Style is tailored for American English. Should you be writing for a British publication, the differences are numerous. Not quite as numerous as the commas and quotation marks that you shall omit, but still worth having within your ken.
- asimpletune 2y agoI'm surprised at how applicable this is to writing in general. Very good guide.
- ants_everywhere 2y agoMy personal pet peeve is point 3 under "Use the right commands" There are quite a few math textbooks that don't use \left and \right, even with tall notation like integral signs. The resulting expressions are much harder to parse visually.
- codethief 2y agoGood guide, but IMO it is missing one crucial recommendation: Use prose only to provide motivation, connect ideas, and guide the first-time reader. Any definitions, lemmas, theorems, corollaries, and proofs belong in typographically clearly separated sections and, most importantly, they should be fully self-contained and mention all assumptions! There should be no implicit context, no implicit assumptions from 5 pages before, no "drive-by" definitions and proofs in the prose. Math papers written like contiguous novels are absolute hell to read & understand & use as reference. (Is the author assuming the same properties here as in the other argument on the previous page? What is that symbol again? Am I looking at an example here or is this already the proof of the the general theorem from the previous page? Etc.)
- mferrari 2y ago"Write to allow skipping over formulas" is great advice beyond just mathematics. Many a technical blog contains something like "I opened the file and look what I found!" followed by line after line of someone else's code or, even worse, a log file. Paraphrase your displayed matter so I can read your text fluidly. If I want to dig deeper, I'll go back and parse the details carefully.
- ivansavz 2y agoFrom the abstract "The guidelines here cover both the LaTeX source as well as the output, so this PDF is intended to be read alongside its own source code," which I found here: https://github.com/michaelchanwahyan/latex_templates/blob/master/template_notes.tex https://github.com/michaelchanwahyan/latex_templates/blob/ma...
- krick 2y agoI am less delighted, than some in the comments. I mean, most of the advice is genuinely good general writing advice, so general in fact, that it borders on advices like "be good". Typography advices are good. But if we keep in mind that this is not really a recommendation, but pretty much an obligatory guide to follow for the intended audience, the more specific writing advice doesn't amuse me. Why cannot I start a sentence with a symbol, and must insert filler-words, why do ∀ and ∃ only belong to formal logic? The author of the guide may prefer it like that, but why enforce it? But that's not why I wanted to comment. The whole document makes me think, that the whole generic structure of how one writes papers, should it still be done like that? Does enforcing it do more good than harm? Can it be changed? I do not belong to academia, so where I'm coming from is having to read this stuff when researching anything. And the general sentiment I want to express here is that I really don't like to have to read these things. To be fair, it is less applicable to math papers, than other topics, but academic papers are not easy to get information from, the main thing they are supposedly exist for. You can sometimes find a blogpost which essentially contains the same information, but is much shorter, clearer and niced than the accompanied paper. And it just comes down to format. I mean, it probably does play on paper reasonably well, when you have it printed out and intend to read it fully, repeatedly, using a highliner. But it is not how most of the people read them most of the time, right? Most of the people read it on a screen, first when trying to understand how is it related to what they are researching now, then as a reference. And pretty much everything about these papers is awful for that. First off, abstracts. Absolutely essential thing in theory, woefully misused most of the time. I don't want an abstract, I want a TL;DR. I don't want to read empty words about what it "explores" and such, I want to read as full and as condensed final result, as possible. If there is a concrete finding, I want it as the first sentence. References. I don't want neither [BV04] nor blah-blah Somebody et al [BV04]. I want clickable links to resources whenever possible. They don't have to be academic papers, it can be anything that helps me to learn more about the topic in the shortest amount of time. Code. Code is close to useless on paper, I want it to be on GitHub, with a clickable link. All excerpts that you have in your paper, I want them to be highlighted, because that's how it's supposed to be read, there is a reason why everybody but 90 years old professors use highlighting. Instead of ugly hard to read plots in these papers there are dozens of JS libraries to make interactive plots that can help you show anything you want to show. Even the mere fact I have to read a PDF off my screen, which I cannot resize to my liking, is annoying. Why must it be paper-first in 2024, when everything is screen-first? Surely there can be rules in these guidelines to make these documents easy to print as well, given how much time one is supposed to spend on correct typographics in LaTeX.
- susam 2y ago> The sentence “Let x⋆ be the solution to the optimization problem” implicitly asserts that the solution is unique. If the solution is not unique or need not be unique, write, “Let x⋆ be a solution to the optimization problem.” I know this point is meant to be about precision in writing but this reminded me of Perron's Paradox, which highlights the danger of assuming the existence of a solution without proper justification. The problem can be demonstrated through the following argument: Let n be the largest positive integer. Then either n = 1 or n > 1. If n > 1, then n^2 > n contradicting the definition of n. Hence n = 1. This fallacy arises from the mistaken assumption that a largest integer exists in the first place. The original post is a great submission, by the way. Thank you for sharing it on HN. Bookmarked already!
- JadeNB 2y agoAlthough this is about LaTeX (not AMS-LaTeX) and is from 2014 (and I don't remember when this AMS-LaTeXism was introduced), nowadays instead of having to decide when to use `\ldots` and when to use `\cdots` one can use things like `\dotsb` for dots between binary operators and `\dotsc` for dots between commas. There are others that I don't remember, because those fulfill most of my needs. There's even `\dots`, which tries to determine what kind of dots are appropriate from context (and usually does a good job!).
- kjellsbells 2y agoSeems that what is needed is something more automated, beyond a "simple" linter like ChkTeX and more towards what Word has in its readability scores, combined with the local rules of Stanford's house style. State of the art here seems still in its infancy. Example: https://www.cs.umd.edu/~nspring/software/style-check-readme.html https://www.cs.umd.edu/~nspring/software/style-check-readme.... For example, seeing a lot of double-backslashes (\\) in a LaTeX source file would be a code smell to me if not actually illegal LaTeX.
- drzzhan 2y agoA very good and solid guide.