Re: Using Org for a dissertation

[Eric Schulte <eric.schulte@gmx.com>]

Hi Richard,

Richard Lawrence <richard.lawrence@berkeley.edu> writes:

> Hi all,
>
> I am a graduate student in philosophy, and I am about to begin writing
> my dissertation.  I am wondering about whether I should write it in Org,
> or stick to plain LaTeX.
>
> This question has been asked before:
> http://article.gmane.org/gmane.emacs.orgmode/22756
>
> But that was two years ago; Org has changed a fair bit, and I'm
> wondering if there are any updates to the advice given there.  Moreover,
> I'm wondering if anyone has written a dissertation or other long
> documents in Org in the meantime, and what their experiences have been.
> (Henri-Paul, do you still read this list?)
>

I am currently writing my dissertation (proposal) in Org-mode.  So far
it is working very well for me, I can export to both PDF for more formal
submissions to my adviser and to HTML for less formal posting to a web
page.  I keep *all* of my reading notes as Org-bibtex headlines in a
single large reading.org file.  I have a (somewhat complex) system
whereby I am able to reference these bibtex entries from the
dissertation and automatically generate the required .bib file as part
of my document export process.  One nice side effect of this setup has
been the ability to do a fun graphical export of my references [1].

My entire dissertation directory is in a public git repository [2], you
may find my Makefile [3] useful (although again I should warn you that
my particular setup may be needlessly complex).

>
> I have used Org to write most of the shorter papers I have so far
> written as a graduate student, and been very happy with the results.  I
> prefer most of Org's editing features and conventions to bare LaTeX.  I
> haven't previously had much of a need to mix TODO items and writing, but
> imagine I will with a dissertation.  I *have* been relying on Org's
> to-do list features for my reading: I enter new readings as TODO items
> via capture, and include the bibliographic fields that make them
> suitable to export via org-bibtex when it comes time to reference them.
> None of the writing I've done so far has had strict formatting
> requirements, however, and I have run into enough small formatting
> issues in the past that I want to avoid having them grow into large
> issues in the context of a dissertation.
>
> Since I am not in the sciences, I doubt that I will have many figures or
> complex tables, which I know can lead to headaches.  Here are a few of
> the things I *am* worried about.  I'm sure most of them can be dealt
> with; I am guessing that most of these issues reflect my ignorance or
> outdated knowledge of Org features.  I'd be grateful for pointers or
> workarounds for them:
>
> 1) Section labels and other in-document references.  It's nice that Org
> generates these on export, but I need to be able to assign and use
> labels that will not change if the document is reordered.  I know I can
> simply add such labels via a \label command, but I am worried that using
> them in addition to Org's autogenerated labels might cause numbering
> problems in LaTeX.
>

I've not run into any such problems.  I tend to construct all of my
labels through Org-mode (which works well for export to both HTML and
LaTeX).

>
> 2) Escaping/unrecognized commands.  I have occassionally run into
> annoyances where Org escapes characters or commands that I intend to be
> exported literally ("~" and "$" are perennial offenders).  Export also
> tends to break when fill-paragraph breaks a LaTeX command across a line,
> like:
>
> some preceding text up to the end of the line \cite{SomeAuthorReference,
> AnotherReference}.
>

I deal with the above by not placing spaces in such commands, so the
above becomes

\cite{SomeAuthorReference,AnotherReference}

>
> 3) Indentation around #+BEGIN_*/#+END_* environments. (I most often
> use QUOTE.)  I usually have to explicitly control indentation in a way
> that I wouldn't have to in LaTeX, because Org inserts blank lines
> around them during export.
>
> 4) Inline footnotes.  I usually prefer to use inline footnotes, but I
> think I have found in the past that Org's syntax for inline footnotes
> ([fn:: ...]) interacts badly with LaTeX commands, especially anything
> requiring a "]" in the footnote text.
>

again, I haven't run into either of the above, but working in Philosophy
you likely have more stringent footnotes needs than I do in CS.

>
> 5) Bibtex and bibliographies.  I love keeping my reading list as Org
> TODO entries, but would like a more automated way to export (just) the
> entries I need for a particular document to a .bib file.

My setup is to keep a tasks.org file with reading related tasks which
holds Org-mode links to all of my references.  As part of my document
export process I scan through that file, jumping to each link and
running `org-bibtex-export-to-kill-ring' at each reference.  I then dump
all of these bibtex entries into a .bib file.  By using a Makefile rule
the .bib file is only regenerated when I've changed my tasks.org file.

> I would also like to have more control over the bibliography as a
> section of my document.  The \bibliography command must live under
> some Org heading or other, and as far I as know it can't live under
> its own without generating an extraneous heading, so I have to be
> careful that it ends up at the end of the last section.
>

This always feels hacky, but I just place this command at the end of the
document in whatever section (usually "conclusion") that may be.

>
> Are there other issues that people have run into when using Org to write
> a longer document with strict formatting requirements?  Again, any and
> all advice is greatly appreciated!
>

When preparing a JSS paper for publication [4] we found that to satisfy
some of the Journal's specific formatting rules we had to add a new
document class, add a new link type, and post-process the generated
LaTeX.  The entirety of this customization may be found here [5] -- the
Makefile in that directory may also be helpful.

In summary, I have very much enjoyed writing longer documents in
Org-mode (on those few occasions when all authors are Org-mode users).
With the ability to write in-line latex it is possible to meet any
stringent output requirements.

I hope this helps,

>
> Thanks,
> Richard
>
>


Footnotes: 
[1]  http://cs.unm.edu/~eschulte/dissertation/refs/force.html

[2]  http://gitweb.adaptive.cs.unm.edu/dissertation.git/tree

[3]  http://gitweb.adaptive.cs.unm.edu/dissertation.git/blob_plain/HEAD:/Makefile

[4]  http://www.jstatsoft.org/v46/i03

[5]  https://github.com/eschulte/org-mode-jss/blob/master/init.el

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/