[HN Gopher] LaTeX Style Guide for EE 364B [pdf] (2014)
___________________________________________________________________
LaTeX Style Guide for EE 364B [pdf] (2014)
Author : walterbell
Score : 92 points
Date : 2024-10-06 11:03 UTC (11 hours ago)
(HTM) web link (web.stanford.edu)
(TXT) w3m dump (web.stanford.edu)
| vitorsr wrote:
| This 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
|
| [2] https://epubs.siam.org/doi/book/10.1137/1.9781611976106
|
| [3] https://bookstore.ams.org/mmbk-7/
|
| [4] https://link.springer.com/book/10.1007/978-1-4471-6527-9
| antegamisou wrote:
| May 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
| vitorsr wrote:
| Nice! 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/writin.
| ..
| sumnole wrote:
| Does anyone have suggestions for math textbooks that follow
| these writing rules?
| dawnofdusk wrote:
| Bertsekas' textbooks of course, which I think are very
| well-written and a pleasure to read.
| hookahboy wrote:
| With 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 wrote:
| You're right, thanks. English is not my mother tongue so I
| still fall for some language traps.
| zmgsabst wrote:
| I 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 wrote:
| Why 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 wrote:
| Well, 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 wrote:
| I vote for 'and'. Strunk & White and the CMS serve different
| purposes; the latter is more of a reference work but both are
| valuable.
| nanna wrote:
| Also 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 wrote:
| I'm surprised at how applicable this is to writing in general.
| Very good guide.
| ants_everywhere wrote:
| My 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 wrote:
| Good 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 wrote:
| "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.
| ivan_ah wrote:
| From 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/ma...
| maven29 wrote:
| Alternatively, you could just navigate to the URL for the
| directory path containing the pdf. I'm amazed that directory
| traversal wasn't disabled.
| JadeNB wrote:
| > I'm amazed that directory traversal wasn't disabled.
|
| Why would it have been? It seems intended to be navigated by
| visitors.
| krick wrote:
| I 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.
| Ar-Curunir wrote:
| You are not the audience for an academic research paper. The
| audience is other researchers who understand the norms of the
| field, and are used to the notation and idiosyncrasies.
|
| Re: code. I don't think any research paper in any field of CS
| includes source code verbatim in the paper, it's usually
| snippets like you want. Sometimes source code is not linked
| from the paper, but that's a different issue, and common in
| industry too (eg closed source code).
|
| Re: references, it's not about explaining a topic (though that
| happens sometimes), it's about providing a pointer to a
| resource that a researcher who already knows the research
| landscape can go look at and confirm that yes, the claimed fact
| is indeed in a previously vetted resource. That is, it's more
| about provenance than explanation.
|
| Re: optimizing for PDF output as opposed to optimizing for,
| say, HTML output/web reading, I only have this to say: I can
| easily read papers produced 30 years ago in PDF form. I cannot
| say the same for some websites even 5 years old.
| krick wrote:
| Then 99% who read academic research papers are not the
| audience for academic research paper. And that's a problem.
| JadeNB wrote:
| > 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 say that this is less applicable to math than other topics,
| which is funny--as a mathematician, I'd think that it's _more_
| applicable! In the strictest sense of the word, the purpose of
| a math paper is _not_ to allow others to get information from
| it, though of course a good math paper will do that. The
| purpose is to _show definitively_ (in the very strong
| mathematician 's sense of the word, stronger even than the
| physical scientist's sense) that something is true*. Especially
| for the first proof of an 'obvious' fact like, say, the four-
| color theorem, filling in all the necessary rigor can be at
| odds with clarity--that is, it is exactly when one is tempted
| to skip over some point with an appeal to the reader's
| intuition that one must most carefully fill in those details.
| (Lots of wrong proofs of the four-color theorem came from
| explicit or implicit appeals to mistaken intuition.)
| sfpotter wrote:
| The main reason academic papers exist right now is simply
| because academics need to publish papers, in ever larger
| quantities. It's publish or perish, and it gets a little bit
| worse every year. The peer review system is a bit of a farce.
| Sometimes it works out, but there are loads of papers that get
| published simply because the author is well known.
|
| Papers used to be better. At least in my field, the quality
| really dropped off in the mid to late 00's. Most of the very
| best papers that I've read---at least, in terms of writing---
| were written in the 90's or earlier. I think the increased
| pressure to publish coupled with people being constantly
| distracted by computers and other forms of media are to blame.
|
| Depending on what your interest is, you may be better served by
| a textbook. Or if it's something very specific, just contacting
| someone by email and trying to have a chat with them.
|
| That said, most of the techno-improvements you suggest
| (clickable links, interactive plots, etc) are basically
| worthless. Good writing and good presentation can be
| accomplished on a typewriter with hand-drawn plots.
| Communicating technical ideas well requires the author to think
| carefully about how they'll present their thoughts, which gets
| skipped over in most cases.
| susam wrote:
| > 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 wrote:
| Although 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 wrote:
| Seems 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....
|
| 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.
___________________________________________________________________
(page generated 2024-10-06 23:01 UTC)