Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

LaTeX Style Guide for EE 364B [pdf] (2014)

web.stanford.edu

Post reply on HN
Print view View original

21–30 of 32 posts

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#21

Post by nanna »

vitorsr wrote: post #2

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 d…

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.

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#22

Post by maven29 »

ivansavz wrote: post #14

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...

Alternatively, you could just navigate to the URL for the directory path containing the pdf. I'm amazed that directory traversal wasn't disabled.

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#23

Post by quuxplusone »

hookahboy wrote: post #5
vitorsr wrote: post #2

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 d…

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.

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."

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#24

Post by JadeNB »

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!).

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#25

Post by JadeNB »

maven29 wrote: post #22
ivansavz wrote: post #14

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...

Alternatively, you could just navigate to the URL for the directory path containing the pdf. I'm amazed that directory traversal wasn't disabled.

> I'm amazed that directory traversal wasn't disabled.

Why would it have been? It seems intended to be navigated by visitors.

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#26

Post by JadeNB »

krick wrote: post #16

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 s…

> 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.)

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#27

Post by kjellsbells »

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.

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#28

Post by sfpotter »

krick wrote: post #16

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 s…

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.

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#29

Post by krick »

JadeNB wrote: post #26
krick wrote: post #16

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 s…

> 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 fro…

I don't see where we disagree. That's pretty much exactly why my points are less relevant for math papers: they are supposed to be self-contained. And while the result is sometimes interesting and can be put into TL;DR, I'd say in the most cases the entire point is reading the proof. No, I mean there definitely were cases when I was just wanted to see the final formula and skip the derivation, and I'd absolutely want it to be in the abstract as often, as possible, and I suspect that many math papers could be improved by using a better media than a LaTeX pdf file, but, as you said yourself, for math, it mostly isn't about informing me about the result.

It is for most other fields. Basically, in the majority of cases the entire paper should be reducible to a couple of sentences that are useful on their own, which I'd like to read in (or rather instead of) the abstract, and the rest 50 pages of the paper should be a detailed report of why is it reasonable to believe you didn't lie (intentionally or not) to me in the abstract, by explaining the exact way to reproduce it, with providing as much data as legally possible. But the insufficiency of the content in your typical research paper is another topic, and much more complicated, so I wasn't going to start about that again, I only raised the points about the format, since that's what the thread is about.

Re: LaTeX Style Guide for EE 364B [pdf] (2014)

#30

Post by aragilar »

krick wrote: post #20
Ar-Curunir wrote: post #18

Earlier quoted context omitted.

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 in…

Then 99% who read academic research papers are not the audience for academic research paper. And that's a problem.

Why would you assume there's a disconnect?
Post reply on HN