# What is a good format or package for writing a commentary about a paper?

I often find myself writing commentaries on scientific papers. By this I mean an informal document written to collect all my comments regarding a peer reviewed publication (which is often about 10 pages, but can easily be from 5 to 20).

These commentaries usually:

• Are short - 1-3 pages. Short sentences, short paragraphs, concise language where possible. Often use bullet point lists.
• Have simple, minimalistic but well defined formatting - the idea is to spend minimal time on fancy layouts (and avoid distracting the reader) to produce a short text which is as effortless as possible for the reader (usually a colleague) to consume. However, things like specific formatting for eg. species names or code are still useful (and used).
• May include figures, but often do not (there is no need).
• May include citations, but often do not (and since the document is informal, strictly formatted citations aren't really necessary).
• Make heavy use of sectioning with deep hierarchy to collect comments based on what part or aspect of the paper they pertain to.

The function of such a commentary is to allow in-depth discussion of a paper when meeting at a set time is difficult, and to facilitate such discussion by enabling the participants to organize and flesh out their own comments before sharing them.

I find that such commentaries are often necessary to write when discussing publications particularly relevant to one's research group, when collaborating on formal commentary (peer reviews) and for various course work revolving around discussing papers.

My question is, is there already a LaTeX package out there meant precisely for writing such commentaries? If not, how do I iron out the details (margins, columns, heading styles) to create my own style? What advice is there for formatting and organizing such commentaries?

Previously I have used the default style of Word 2010+. It doesn't look too pretty, but it is quite functional - there are many different heading and subheading styles, which are sufficiently distinct and don't get in the way too much, the default margins, paragraph spacings and bullet point list formats do a decent job of keeping separate units of text appropriately delimited with space.

I have tried to cobble together a few lines my own LaTeX, using actual scientific publications as a vague basis. Unfortunately, scientific papers tend to be formatted with a much different document in mind (many figures, proper citations, dense text, limited subsectioning) which runs counter to what I would expect from a commentary. Also, if using columns, sometimes the commentary is so short that the last column looks too short and ugly. Still, it looks nicer than Word, but I haven't used it long enough to comment on functionality (ie. ease of reading).

I know about the Tufte books package, and at first the "handout" seemed to be close, but it looks very different from what I was expecting. I don't need such a large margin for figures and footnotes, because I rarely have any. Also, to me the heading font doesn't stand out enough at a glance - it looks too similar to body text (maybe a boldface would work better).

-
I would consider using org-mode (if you are willing to use Emacs) or markdown, which are light-weight markup languages, ideally suited to note-taking. From there, it is a simple matter to convert to LaTeX or even straight to PDF. And it is a simple matter to create a custom preamble that gets applied each time so the PDF ends up looking the way you want it. Although I would use neither to write a book, I use both for shorter and simpler documents all the time. – jon Jan 28 '14 at 5:40
@jon Unfortunately, while I point out that fancy formatting should be used sparingly (for this sort of document) that doesn't mean it should be abandoned entirely. There are frequent cases when the very occasional formatting can be very helpful. Also, I am also looking for advice on how such a document should look when formatted (eg. after "converting to LaTeX"). – Superbest Jan 28 '14 at 5:47
Formatting is not abandoned entirely. Far from it: org-mode and markdown only simplify how the text is input, which, for me, is important when doing note-taking-like tasks: I want quick and easy lists, easy section-division markup; and I don't need/want footnotes, marginal comments, complex headers, fancy colours (etc.). As for the translation to PDF, it is easy to apply almost any formatting you might need. As for how it should look, I think that is fairly subjective since they are informal, personal notes, not something to be read by others. My tastes run to 'clear, simple, and plain'... – jon Jan 28 '14 at 6:34
In other words, I think you have two questions: (1) how to do it, and (2) how should it look in the end? I only suggested a possibility regarding (1). No doubt others will weigh in on both. – jon Jan 28 '14 at 6:39

It would be, as @jon pointed out, a good idea to use a light-weight markup language for note taking. My favorite is `pandoc`, which provides a nice front-end to LaTeX. How should a document like this look? Structured, clean and uncluttered, which can be achieved with either `article`, `memoir` or `KOMA-Script` and a nice font.

So, let's try this with the standard document class `article` and the New PX font:

``````---
title: Commentary on XY
date: Date
documentclass: article
papersize: a4paper
geometry:
- right=2cm
- left=2cm
- top=1cm
- bottom=1cm
- \usepackage{newpxtext}
- \usepackage{newpxmath}
numbersections: true
---

# Level 1

Lorem ipsum Non ullamco dolor.

#. Item
#. Item
#. Item
#. Item
#. Item
#. Item
#. Item
#. Item

## Level 2

Lorem ipsum *Mollit* quis **nostrud** nulla exercitation consectetur sit in in et in.

### Level 3

Lorem ipsum Et labore nulla aliqua mollit ex magna sit in dolore proident ut laboris.

- This
- Is
- A
- Bullet
- list

#### Level 4

Lorem ipsum Et irure esse mollit.

##### Level 5

Lorem ipsum Excepteur.

###### Level 6

Lorem ipsum Do adipisicing occaecat ut.
``````

The resulting (simply: ```pandoc in.md -o out.pdf ``` in the terminal) PDF looks like this:

Update 1

Pandoc can convert between several formats on the in- and output side, including .pdf, .docx, .odt, .html, and .tex. The native pandoc markup is a superset of markdown: That means, that pandoc is on the one hand fully compatible to markdown and adds on the other hand some very powerful commands, e.g. for footnotes, tables and citations. (Some are even writing their whole thesis in pandoc.) It is worthwhile reading the user's guide.

Update 2

Pandoc can produce .tex files directly. In order to do so, just set the file extension accordingly: `pandoc -s in.md -o out.tex`

This produces a standalone tex file, using the default latex template. Omitting `-s` (standalone) will give a fragment containing only the written text in LaTeX markup without header, footer, etc. This is rather convenient if you want to `\include` the file in another document.

It is, of course, possible to write custom templates, which quite easy, as a template is just a LaTeX document with some `\$variables\$`. `pandoc -D latex` prints the default LaTeX template.

-
Can pandoc output .tex? Or does it just produce pdf directly? – cfr Jan 29 '14 at 3:30
@cfr pandoc uses LaTeX to generate PDFs and can output .tex (with or without preamble) – DG' Jan 29 '14 at 7:14
Thanks. That's interesting. I usually take notes directly in .tex but this sounds as though it might be better. (I doubt I would use it for writing more generally, even handouts, but notes are rather different.) – cfr Jan 29 '14 at 21:51
Well, some are even writing papers and books that way. – DG' Jan 29 '14 at 22:18
I know. It was just an expression of what I'd expect myself to do. – cfr Jan 30 '14 at 4:40