How to write a scientific paper, in four simple steps

Accomplished scientific writers will all have their own tips on how to go about writing a scientific paper. However, when you are first getting started, sometimes it is easier to have a set of steps available. Certainly there are many options available, but I personally have been finding the following set of steps useful when advising students lately.

• Step 1: Write the Introduction (starting with second paragraph)
  The introduction lays out why you bothered to do the study you did. It provides a background from the existing literature, and it points out holes in that literature or opportunities to test answers to questions that have little coverage.
  
  However, the first paragraph of your introduction (in fact, the first few sentences of your paper) are often the hardest ones to write. A colleague points out to her students that a great way to get around this potential writer's block is to simply skip the first paragraph. If you start with the second paragraph, you can immediately start laying out the argument for why your study needs to be done. Once you finish the rest of the introduction, it may be easy to see what the first paragraph needs to be. In other words, once you have 75% of the argument completed, the shape of the puzzle piece that remains will often be clear.
  
• Step 2: Write the Discussion
  If someone is already convinced that your paper has something interesting to say, that person will likely jump straight to the discussion and start reading there. This is where you describe how your data support some story that you want to tell about an inference you have made about the natural world. As you write your discussion, it will become clear exactly which data you need to tell your story. And so that brings us to the next step.
  
• Step 3: Write the Results
  Now that you have crafted a convincing discussion, you know what results are needed to support your argument. Writing the discussion first tells you what to include and what you can exclude. A lot of students make the mistake of starting with all of the possible plots that can be generated and then trying to string together a discussion around them, even if some of those plots really aren't needed. Don't do it that way. Instead, let your discussion guide which results to include.
  
• Step 4: Write the Methods
  Putting this step here is controversial. In many cases where your study has a clear experimental design that tests for something very specific, then it is possible to write your methods first. However, if you are instead working with a very large dataset that might someday result in multiple papers, then your methods might need to wait for you to determine exactly which results you need to make your argument. So once you've written your results, you can then generate methods that explain how all of those results came about.

Those four steps can often soothe writer's block on a scientific paper. You may determine a different flow as you mature in your writing process, but this is just one suggestion of where you might think about starting.

Special Note: Title and Abstract

Of course, two things that are left out of the steps above are the title and abstract. Young writer's often leave these until the end, and they often view them as complementary to the rest of the article. However, with maturity, it should be possible to write them first and view them almost as alternatives (or marketing pieces) for the whole article. Writing them first can also provide structure (similar to an outline) for the rest of the article. So work toward being able to write these two things first, but it's OK if you start by writing them last.

Keep in mind that most readers will only read the title and abstract (and some will only read the title). Consequently, the title should not be clickbait; the title should be an executive summary of the article, giving the punchline as opposed to begging the reader to read further. Interested readers will move on to the abstract. Consequently, your abstract should really have everything an educated reader needs to reconstruct your article; it should have a little bit of all of the sections. Your abstract should concisely say why you did the things you did, how you did them, what the main results were, and why those results are interesting.

Take-away Message: It's About the Reader

People are busy, and they allocate their reading resources accordingly. If you tease them with half statements, they will only get frustrated and move on to the next thing that competes for their time. Instead, give them something interesting and complete in the title. If they want more details, they can read the abstract, which should itself be complete. If they want more details, they'll read the main body (possibly starting with the discussion section). For the reader, it's about sequentially choosing what to read next. When you write, you should always have this in mind as you design the delivery vehicle for the content you hope will be disseminated broadly.

LaTeX template for NSF-style Biographical Sketch

On large multi-university NSF grant proposals, NSF requires that senior personnel submit a 2-page biographical sketch ("biosketch") that is formatting according to certain rules in their Grant Proposal Guide (GPG). The format is pretty simple, and so there does not seem to be much demand for a solid LaTeX template for one. Nevertheless, I thought some people might find one helpful. I've posted a PDF of my NSF-style biosketch below along with the TeX source used to generate it.

• PDF: tpavlic_nsf_biosketch.pdf
• LaTeX template: tpavlic_nsf_biosketch.tex

On a related note, you can also find my curriculum vitae (CV) tailored for faculty searches (PDF, TeX) as well as for industry searches (PDF, TeX).

natbib-like frontend for chicago-style macros

For some reason, the ACM has baked in chicago-like citation macros into the ACM SIG proceedings LaTeX templates instead of using the far superior natbib that literally everyone else on the planet uses. I'm much more accustomed to typing \citet as opposed to \shortciteN, \citeauthor as opposed to \shortciteANP, etc. So I decided to add this little translation table to my preamble:

\def\citet{\shortciteN}
\def\Citet{\shortciteN}
\def\citeauthor{\shortciteANP}
\def\Citeauthor{\shortciteANP}

\let\chicagociteyear\citeyear
\def\citeyearpar{\chicagociteyear}
\def\citeyear{\citeyearNP}

\def\citep{\shortcite}

Unfortunately, that means I can't use any of the optional arguments to \citep or \citet. If you are just looking for a translation table so you can use the chicago-style macros directly, try this:

natbib	chicago
\citet or \Citet	\shortciteN
\citeauthor or \Citeauthor	\shortciteANP
\citeyear	\citeyearNP
\citeyearpar	\citeyear
\citep	\shortcite

It's crazy how chicago-style macros sometimes use "N" to mean "noun" and other times to be the first half of "NP" being "no parentheses."

natbib-compatible BibTeX style (BST) file for Springer LNCS publications

UPDATE: Additionally, if you prefer "References" instead of "Bibliography", you have to re-define the \bibname macro in your document (e.g., just after you include natbib). Just add a

\rewewcommand\bibname{\refname}

or a

\renewcommand\bibname{References}

and you should be up and running with your desired bibliography name.

For some reason, the folks over at Springer do not like to make their BibTeX style (BST) files natbib compatible. This omission seems egregious when considering the kind of authors that would submit to journals and conferences that use LNCS-style formatting. Springer does provide LaTeX support files for LNCS, but the included BST file is not natbib compatible (because it was not built with natbib and author–year extensions turned on, which are needed in natbib even when numbered references are used). What makes things more difficult is that it is produced by hacking another BST (titto.bst) that was originally generated properly using makebst, and many of the hacks were already implemented natively in merlin.mbs. So much more of the postfix BST language was hacked directly rather than would have been necessary if the correct docstrip driver options were picked in the first place. So that makes it more challenging to reproduce a refactored version with additional natbib functionality without worrying about introducing regressions.

Nevertheless, I've done my best, and I've made the the natbib-compatible result splncsnat.bst available for download. I was able to remove the need for some of the manual editing by a smarter choice of docstrip options, but I still ended up having to create a patch on top of a stock docstrip-generated BST (the docstrip driver splncsnat-unpatched.dbj and patch splncsnat.patch are also available). Hopefully that helps someone out there.

• splncsnat.bst: natbib-compatible BST file for Springer LNCS-type publications

  Download and place splncsnat.bst in same directory as document's TeX source code. In the TeX preamble of the document, use

  \usepackage[numbers]{natbib}
  \bibliographystyle{splncsnat}

  and then in the text use macros like

  \cite{smith77}       % to get a "[1]" in the text
  \citep{smith77}      % to get a "[1]" in the text
  \citet{smith77}      % to get a "Smith [1]" in the text
  \citeauthor{smith77} % to get a "Smith" in the text

  The normal \bibliography{FILENAME} can be used at the end of the text where the BBL will be inserted by BibTeX.

• splncsnat-unpatched.dbj: docstrip driver used to generate splncsnat-unpatched.bst
• splncsnat.patch: patch used to generate splncsnat.bst from splncsnat-unpatched.bst (assuming version 4.20 [2007/04/24 (PWD, AO, DPC)] of merlin.mbs)

Of course, you need only splncsnat.bst to get up and running.

Updated LaTeX document class for Ohio State University (OSU) graduate school dissertation and thesis documents

Back in 1996, The Ohio State University Electrical and Computer Engineering (ECE) department made available LaTeX2e support files including a document class that complied with the graduate school's format for dissertations (see samples pages, guidelines, templates, and other resources from the graduate school). The resulting osudissert96.cls and osudissert96-mods.sty from the ECE department was kept up to date through 1998, but it was left to lapse out of compliance after several format updates from the graduate school (including a recent one in 2009). Additionally, the graduate school only officially supports helping students with documents "typeset" in Microsoft Word (and even their Word templates may require a more recent version than they claim on the website).

So back when I put together my dissertation (which has source code available to review) in 2010, I updated those old ECE templates for the 2010 format. I tried to make them backward compatible with the old osudissert96 to make them nice drop-in replacements for anyone using the outdated versions. You can find them at:

• http://links.tedpavlic.com/zip/osudissert10.zip
• http://links.tedpavlic.com/zip/sample-osudissert10.zip

For the most part, the old osudissert96 documentation still applies. However, it might be better just browsing through the sample and/or using the sample as a template for your own document. To get the sample up and running,

1. Unzip sample-osudissert10.zip.
2. Unzip osudissert10.zip.
3. Put the CLS and STY files from osudissert10.zip into the same directory as the files from sample-osudissert10.zip
4. Build the sample dissertation with:
   1. pdflatex Thesis.tex
   2. bibtex Thesis.aux
   3. pdflatex Thesis.tex
   4. pdflatex Thesis.tex
5. Review the resulting Thesis.pdf file, which also includes documentation on how to get your own dissertation up and running.

There is also a README file in sample-osudissert10.zip that basically says the same as above. Experts may just need the files in osudissert10.zip, but it will still be useful to see the quick reference in Appendix B of the sample dissertation. Note that the documentclass is still called osudissert96.cls even though the zip file is called osudissert10.zip; this choice was made for compatibility with old dissertations using the old files.

I hope that helps someone out there. I probably won't be monitoring the graduate school format policies now that I am not in graduate school anymore, but I am usually happy to help with "how-to-modify" questions over e-mail (if I have time). Good luck!

How to put "1 of ..." page numbers on a LaTeX letter

Someone e-mailed me recently to ask how to add "1 of LAST_PAGE" page numbers to a LaTeX letter document. I generated the sample LaTeX document fancy_letter_numbering.tex to show how it's done using the fancyhdr and lastpage packages.

Here is my response, which gives more details:

I have attached a sample letter with "1 of ..." page numbering throughout. fancyhdr works with "letter" just as well as it works with "article." You just have to treat "\opening" just like you do "\maketitle."

In particular, put this up in your preamble:

\usepackage{lastpage}
\usepackage{fancyhdr}
\fancyhead{}
\fancyfoot{}
\cfoot{\thepage{}~of~\pageref{LastPage}}
\pagestyle{fancy}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}

Then, after each "\opening" (in the case of a single letter, there will only be one), put the line:

\thispagestyle{fancy}

Otherwise you will get page numbers on every page except for the first one.

Of course, you will have to run LaTeX (or PDFLaTeX) at least twice to place the "LastPage" label properly and generate the correct page refeference.

[ Additionally, you may further customize the headings and footers making use of all of the nice features that come with the fancyhdr package. ]

rspublic.cls fixed to get rid of nasty Incomplete \if errors

Depending on how updated your LaTeX distribution is, if you try to use the Royal Society's rspublic.cls to build your compuscript, you may get nasty incomprehensible errors like:

! Incomplete \if; all text was ignored after line 7.

                \fi

I didn't get these errors on my home system (which has TeX Live 2007 installed), but I got them on Manuscript Central for Proc. R. Soc. B, and that's a major problem.

After two days of binary searching through possible sources of the problem, I found it. Jonathan Wainwright (the author of the document class) used a \phantom in both the \@oddhead and \@evenhead without preceding it by a \protect. The \phantom macro is fragile, which means that it can cause major problems when put in contexts that move around (like headers). So it needs to be protected.

I added \protect in front of each of the two \phantom calls, and all was well in the world.

I've posted a fixed version of the document class at:

• http://links.tedpavlic.com/cls/rspublic.cls

Give it a shot. That version also allows for 11pt and 12pt fonts, and it defines \@ptsize, which setspace needs to exist in order to work (i.e., for double spacing).

natbib-compatible BST file for Royal Socety journals

I just whipped up rspublicnat.bst, which is a natbib-compatible BibTeX style file (BST) for the Royal Society journals (e.g., Proceedings of the Royal Society A and B and others).

FYI, the BST can be regenerated by applying LaTeX (i.e., docstrip) to rspublicnat.dbj and then applying rspublicnatbst.patch (with patch) to the resulting BST file. The patched result should closely match the Royal Society's bibliographic conventions for both in-line and listed references.

Removing hyperref's space inside \autoref

Many journals (e.g., any of the Royal Society journals) prefer sections to be identified with the section symbol (§) rather than the word "section" followed by a space. If you use \auotref, one of the wonderful macros provided by the hyperref package, then you'll want to do something like...

\renewcommand*\sectionautorefname{\S}

Unfortunately, \autoref will still insert a space between the section symbol (\S, which renders as §) and the section number. So, as discussed in a comp.text.tex posting, you'll need to be more clever and do something like (the ~ character is the "tilde", which is on the upper-left of most keyboards; it's a LaTeX "tie"—a non-breaking space)...

\def\Snospace~{\S{}}
\renewcommand*\sectionautorefname{\Snospace}

instead. That will eat the space that \autoref inserts after the section. Voila!

Perl script that generates CSV and BerkeleyDB versions of LTWA list

UPDATE: If you're wondering why I just didn't save the LTWA database and search it every time I needed to abbreviate a journal, it's because I wanted to optimize for speed downstream. That is, I did all the possible processing now to speed things up later. I've also augmented the script to do the opposite (and save the results in other smaller files) so that I can tell the downstream process to take longer (and possibly have better results with less spurious entries in the hash table). I've also updated the downstream script to save any successful lookups locally to speed up successive runs. Again, contact me if you want more details.

I'm sick of looking up ISO 4 standard journal abbreviations from the List of Title Word Abbreviations (LTWA) hosted at ISSN's LTWA online. The most annoying thing about LTWA online is that you can't get one big list unless you have them mail you a paper copy (for a price). So you have to resort to clicking each letter and waiting for the list for that letter to come up.

So I wrote a Perl script that automatically cURLs each LTWA online page down, processes it, and generates both CSV and BerkeleyDB (BDB) hash files containing a list of words and their associated official LTWA abbreviation. I use the BDB file in another script to automatically generate BibTeX database files for each of my journal papers (that script first checks a list of known-good journal abbreviations before trying to generate the abbreviation itself).

There were several challenges to such a task, and the list isn't perfect. I focused on one-word entries. For more complicated abbreviations, I figured I'd lean on my list of known-good journal abbreviations. That still left LTWA entries like "psycholog-" and "bulletin-" which use "-" to imply "and any other character." So I used a typical /usr/share/dict/words list to generate a list of English words that matched each pattern. Because such lists don't usually include plurals, I used Lingua::EN::Inflect to generate plurals and then took all of the plurals that included the singular (i.e., that would also match the LTWA pattern).

So that works well for me. Someday I might put the script and/or the files it produces on-line. For the moment, if you want any of these, contact me and let me know. I'll share.

Non-breaking Spaces in Word/OpenOffice Writer

I use LaTeX primarily for all of my printed document preparation, but I have to teach people how to write in Word/OpenOffice Writer, and so it still is interesting to me to find out how to do new things.

I've wondered how to make non-breaking spaces (NBSP) in Word for a long time, but I didn't force myself to actually look it up until recently. Evidently, if you type

Control+Shift+Space

in Word, you generate a NBSP. This same combination works in OpenOffice Writer, but I think only Control+Space is needed.

A non-breaking space tells the Word Processor to never break lines at that spot. That is, a non-breaking space can never end or begin an automatically wrapped line. You should use NBSP's to prevent

• periods at the end of lines that do not terminate sentences
• numbers or bullet-like symbols at the beginning of lines that do not initiate list items

For example,

• Replace "Mr. Jones" with "Mr.(NBSP)Jones"
• Replace "Figure 2" with "Figure(NBSP)2"
• Replace "Table 3.1" with "Table(NBSP)3.1"
• Replace "Equation (5)" with "Equation(NBSP)(5)"
• Replace "over there – in the hallway" with "over there(NBSP)– in the hallway"

That's how the big publishers do it. However, you never notice it because it's so subtle; when it's done right, you won't notice it at all.

Fixing natbib: Adding tie between author and citation

Something that bugs me about natbib is that \citet puts a formal SPACE between the authors and the citation list, and so LaTeX like...

. . . as discussed by \citet{SK86}.

that shows up near the end of a typeset line can turn into

as discussed by Stephens and Krebs
[1].

Not only does this put a number at the beginning of a line, which is a typography no-no when you aren't starting a numerical item in a list, but it separates the citation list from its neighbors. If natbib would just us a TIE (~ in TeX) instead, then the "Krebs" in the example above would never get separated from the "[1]."

The best solution is to fix natbib so that this character is configurable. That would really help when using superscript references because you could get rid of the character all together (right now superscripts get a space before them, and that looks a little silly (especially when superscripts show up on the next line!)). However, that could take a while to get fixed (CTAN isn't quite SourceForge)... So I put together the following fix, which should work OK for \citet, \citet*, \Citet, and \Citet* regardless of how many optional arguments (0, 1, or 2) are present.

(note: the \makeatletter and \makeatother commands are not needed if these lines are put into a .sty file or in a natbib.cfg file (in the same directory as your TeX document source).

% Unfortunately, natbib does not TIE textual 
% references to their citations. So authors 
% sometimes get separated from citations when 
% they come at the end of the line. The following 
% lines attempt to fix this problem.
%
% The lines below do the equivalent of . . .
%
%       \renewcommand\citet[1]%
%           {\citeauthor{#1}~\citep{#1}}
%
% but they handle the star and capitalization and 
% optional argument cases too.
%
% (the \makeatletter and \makeatother are not needed if 
%  these lines are put into a .sty file or in a natbib.cfg
%  file)
\makeatletter
%
%%% These lines test for star and number of arguments 
%%% and call the workhorses below
%
% Test for star (mid-sentence and start-sentence forms)
\def\citet{\@ifstar{\citetstar}{\citetnostar}}
\def\Citet{\@ifstar{\Citetstar}{\Citetnostar}}
%
% No star found. Now test for argument count.
\def\citetnostar%
    {\@ifnextchar[{\squarecitet}{\simplecitet}}
\def\squarecitet[#1]%
    {\@ifnextchar[{\twocitet[#1]}{\onecitet[#1]}}
\def\Citetnostar%
    {\@ifnextchar[{\squareCitet}{\simpleCitet}}
\def\squareCitet[#1]%
    {\@ifnextchar[{\twoCitet[#1]}{\oneCitet[#1]}}
%
% Star found. Now test for argument count.
\def\citetstar%
    {\@ifnextchar[{\squarecitetstar}{\simplecitetstar}}
\def\squarecitetstar[#1]%
    {\@ifnextchar[{\twocitetstar[#1]}{\onecitetstar[#1]}}
\def\Citetstar%
    {\@ifnextchar[{\squareCitetstar}{\simpleCitetstar}}
\def\squareCitetstar[#1]%
    {\@ifnextchar[{\twoCitetstar[#1]}{\oneCitetstar[#1]}}
%
\makeatother
%
%%% The following actually do the \cite work
%
% The \citet cases (no arg, one arg, and two args)
\def\simplecitet#1%
    {\citeauthor{#1}~\citep{#1}}
\def\onecitet[#1]#2%
    {\citeauthor{#2}~\citep[#1]{#2}}
\def\twocitet[#1][#2]#3%
    {\citeauthor{#3}~\citep[#1][#2]{#3}}
%
% The \citet* cases (no arg, one arg, and two args)
\def\simplecitetstar#1%
    {\citeauthor*{#1}~\citep{#1}}
\def\onecitetstar[#1]#2%
    {\citeauthor*{#2}~\citep[#1]{#2}}
\def\twocitetstar[#1][#2]#3%
    {\citeauthor*{#3}~\citep[#1][#2]{#3}}
%
% The \Citet cases (no arg, one arg, and two args)
\def\simpleCitet#1%
    {\Citeauthor{#1}~\citep{#1}}
\def\oneCitet[#1]#2%
    {\Citeauthor{#2}~\citep[#1]{#2}}
\def\twoCitet[#1][#2]#3%
    {\Citeauthor{#3}~\citep[#1][#2]{#3}}
%
% The \Citet* cases (no arg, one arg, and two args)
\def\simpleCitetstar#1%
    {\Citeauthor*{#1}~\citep{#1}}
\def\oneCitetstar[#1]#2%
    {\Citeauthor*{#2}~\citep[#1]{#2}}
\def\twoCitetstar[#1][#2]#3%
    {\Citeauthor*{#3}~\citep[#1][#2]{#3}}

Even if this problem gets fixed within natbib, it still might serve as a good example of how to deal with TWO or more optional arguments in macros...

UPDATE: For author-year citations (i.e., "Harvard style citations"), you must replace the \citep with \citeyearpar. That is, replace the final section of the code above with this section:

%%% The following actually do the \cite work
%
% The \citet cases (no arg, one arg, and two args)
\def\simplecitet#1%
    {\citeauthor{#1}~\citeyearpar{#1}}
\def\onecitet[#1]#2%
    {\citeauthor{#2}~\citeyearpar[#1]{#2}}
\def\twocitet[#1][#2]#3%
    {\citeauthor{#3}~\citeyearpar[#1][#2]{#3}}
%
% The \citet* cases (no arg, one arg, and two args)
\def\simplecitetstar#1%
    {\citeauthor*{#1}~\citeyearpar{#1}}
\def\onecitetstar[#1]#2%
    {\citeauthor*{#2}~\citeyearpar[#1]{#2}}
\def\twocitetstar[#1][#2]#3%
    {\citeauthor*{#3}~\citeyearpar[#1][#2]{#3}}
%
% The \Citet cases (no arg, one arg, and two args)
\def\simpleCitet#1%
    {\Citeauthor{#1}~\citeyearpar{#1}}
\def\oneCitet[#1]#2%
    {\Citeauthor{#2}~\citeyearpar[#1]{#2}}
\def\twoCitet[#1][#2]#3%
    {\Citeauthor{#3}~\citeyearpar[#1][#2]{#3}}
%
% The \Citet* cases (no arg, one arg, and two args)
\def\simpleCitetstar#1%
    {\Citeauthor*{#1}~\citeyearpar{#1}}
\def\oneCitetstar[#1]#2%
    {\Citeauthor*{#2}~\citeyearpar[#1]{#2}}
\def\twoCitetstar[#1][#2]#3%
    {\Citeauthor*{#3}~\citeyearpar[#1][#2]{#3}}

Those lines seem to work for me.

My attempt at a "public domain" license declaration

Many lawyers will tell you that it is impossible for an author to explicitly release a new work into the public domain, but many authors would like to do such a thing. Normally the advice is to acknowledge retaining the copyright and then explicitly grant permission for public use of the work for every possible use.

So here's my attempt (taken from something I had to put into the public domain today:

Copyright (c) YEARS by AUTHORS
No rights reserved. All rights granted.

This work is licensed to the public domain. All persons
are permitted to use, copy, modify, distribute, and 
publicly perform or display this work without restriction.

To view a copy of this license, visit
http://creativecommons.org/licenses/publicdomain/ 
or send a letter to Creative Commons, 171 Second Street, 
Suite 300, San Francisco, California, 94105, USA.

I think much of that is redundant. You probably don't need that second half linking to CC's explanation of public domain. You probably don't need the "No rights reserved" and "All rights granted" crap either. Anyway, for the moment, I don't think they're doing any harm.

Yes, I realize I could just ask the civil law attorney in my family who handles this type of thing daily, but I'm afraid he'd just think I was being silly.

Journal Reviewer Review

A recent paper of mine was rejected from Journal of Theoretical Biology. For fun, lets compare and contrast and selection from the reviewer comments ("MS" = "manuscript"):

From Reviewer #1:

Overall I really liked the work presented in this MS - by generalising the traditional models of the ecological economics underpinning solitary foraging behaviour the authors offer a very interesting (& in retrospect) intuitively appealing justification for accepting that the concorde fallacy may not always be fallacious.

From Reviewer #2:

This result seems to be of significance in biology, psychology, economics, and business, and I think that the paper is deserving of publication in JTB. The paper is also very well written, and the mathematical presentation is clear and precise.

Those two were pretty nice, and suggest that I should resubmit the paper with a couple tiny revisions and I'll be off and running. Great! Wait... What's this?

From Reviewer #3:

I regret to say I have no idea what this paper is about. The mathematical lingo is completely unfamiliar to me (after about 50 years of teaching and research in maths)...(details omitted)...(I recently had a grad student who wrote in this vein. When I asked him to explain in ordinary math, he gave up.) I didn't read any further. My advice is reject.

HUH?!

LaTeX for generating Behavioral Ecology manuscript

UPDATE: Check out a more complete math-oriented template/example, that I posted as behavecol_math_template.tex. This is ready to use out of the box. It has comments. It is setup for AMS math. It has table, figure, and autoreferencing examples too.

IMPORTANT NOTE: If using amsmath environments, be sure to check out my information on making lineno compatible with amsmath environments.

UPDATE: I have put behavecol_template.tex and behavecol.bst on-line so that you don't have to do any of the following to get them.

The Oxford Journal Behavioral Ecology is not setup for LaTeX manuscript submissions. This baffles me.

So, I spent some time putting together some macros and a BibTeX style file to get up and running with this journal.

First, a template (that uses the article document class), which fixes incompatibilities between figcaps, caption, and anything that uses \ref (see behavecol_template.tex for what is below, or see behavecol_math_template.tex for a more complete example):

\documentclass[12pt]{article}

\usepackage[paper=letterpaper,margin=1.5in]{geometry}
\usepackage{setspace}\doublespacing

\usepackage{graphicx}

\usepackage[%
            labelsep=newline,
            justification=RaggedRight,
            singlelinecheck=false,
            labelfont=bf,
            tableposition=top,
           ]{caption}
\captionsetup[table]{textfont=bf,position=above}
\makeatletter
\let\oldmakecaption\@makecaption
\makeatother

\usepackage[figon,printfigures]{figcaps}
\def\figurecapname{Figure legends}
\def\tablepagename{Tables}
\def\figurepagename{Figures}
 
\makeatletter
% This lets figcaps work with \ref
% However, forces \label outside of \caption
\def\phantomsection{\relax}
\let\oldfigurepage\@figurepage
\def\@figurepage{%
        \@ifundefined{tf@pof}{}{%
        \let\oldlabel\label%
        \let\oldinput\@input%
        \def\@input{\def\label{\oldlabel}\oldinput}%
        \phantomsection%
        \addcontentsline{toc}{section}{\figurepagename}}%
        \oldfigurepage%
        }
\let\@makefcaption\@makecaption
\let\oldtablepage\@tablepage
\def\@tablepage{%
        \@ifundefined{tf@pot}{}{%
        \clearpage%
        \phantomsection%
        \addcontentsline{toc}{section}{\tablepagename}}%
        \oldtablepage%
        }
\makeatother
\usepackage[subrefformat=subparens,labelformat=parens]{subfig}
\captionsetup[subfloat]{position=top}

\setcounter{secnumdepth}{0}

% Lines are numbered, starting at 1 
% (add pagewise to reset at each page)
%\usepackage[modulo,pagewise,mathlines]{lineno}
\usepackage[modulo,mathlines]{lineno}
\modulolinenumbers[1]
\firstlinenumber{1}
\linenumbers

\usepackage{natbib}
\bibliographystyle{behavecol}
\setcitestyle{%
        authoryear,round,semicolon,%
        aysep={},%
        yysep={,},%
        notesep={, }%
        }

\usepackage{tocbibind}
\def\tocbibname{\refname}

\usepackage{varioref}
\labelformat{equation}{\textup{(#1)}}
\labelformat{enumi}{\textup{(#1)}}

\usepackage[%
            pdftitle={},
            pdfsubject={},
            pdfauthor={},
            pdfkeywords={},
            pdfstartview=FitH,
            bookmarks=true,bookmarksopen=true,
            breaklinks=true,
            colorlinks=false,
            pdfpagelabels=true,hypertexnames=true,
            plainpages=false,naturalnames=false,
            %draft,
            ]{hyperref}

% \Autoref is for the beginning of the sentence
\let\orgautoref\autoref
\providecommand{\Autoref}
    {\def\equationautorefname{Equation}%
     \def\figureautorefname{Figure}%
     \def\subfigureautorefname{Figure}%
     \def\Itemautorefname{Item}%
     \def\tableautorefname{Table}%
     \orgautoref}
 
% \Autorefs is plural for the beginning of the sentence
\providecommand{\Autorefs}
    {\def\equationautorefname{Equations}%
     \def\figureautorefname{Figures}%
     \def\subfigureautorefname{Figures}%
     \def\Itemautorefname{Items}%
     \def\tableautorefname{Tables}%
     \orgautoref}
 
% \autoref is used inside a sentence 
% (renew of the standard autoref)
\renewcommand{\autoref}{\Autoref}
 
% \autorefs is plural for inside a sentence
\providecommand{\autorefs}{\Autorefs}

\let\oldsection\section
\newcommand{\uppercasesection}[2][]{%
    \oldsection[#1]{\MakeUppercase{#2}}}
\newcommand{\uppercasesectionstar}[1]{%
    \oldsection*{\MakeUppercase{#1}}}
\makeatletter
\def\section{%
    \@ifstar{\uppercasesectionstar}%
            {\@dblarg{\uppercasesection}}}
\makeatother

\hypersetup{%
        pdftitle=
        {The title},
}
\title{The title}
\author{}
\date{}
     
\begin{document}
    
\maketitle
     
\begin{abstract}
% ...The abstract...
        \textit{Key words:} Keywords separated with comma+space, 
                            List ends with period.
        \hypersetup{%
        pdfkeywords=
        {Keywords separated with comma+space, 
         List ends with period},
        }
\end{abstract}
\newpage
     
% ...The document...
     
% The following line loads the references
\bibliography{the_bib_database_name}
     
\end{document}

Of course, remember to put table captions before the actual table insertion. In fact, it is important that the inside of a table environment has caption first, then label OUTSIDE of the caption, then the actual table content. Additionally, subfigures should be inserted (within a figure environment) with something like:

\subfloat[]{
% ... something like an \includegraphics ...
\label{fig:a}
}

Also, when you're ready to submit, get rid of the % on the %draft, line of the hyperref options. This will turn off all hyper linking, which will prevent strange little unlinked boxes from being drawn in your autogenerated proof.

Next, the bibliography style file, which I may end up posting later separately. As of right now, it has to be constructed from pieces. First, save the following as behavecol.dbj (see behavecol_full.dbj for more details):

%% Driver file to produce behavecol.bst from merlin.mbs
%% Generated with makebst, version 4.1 (2003/09/08)
%% Produced on 2007/08/23 at 12:02
%% 
\input docstrip
 
\preamble
----------------------------------------
*** Bibliography style for _Behavioral Ecology_. ***
 
\endpreamble
 
\postamble
End of customized bst file
\endpostamble
 
\keepsilent
 
\askforoverwritefalse
\def\MBopts{\from{merlin.mbs}{%
  ay,nat,nm-rvx,ed-rev,jnrlst,keyxyr,dt-beg,yr-per,note-yr,jxper,%
  jttl-rm,thtit-a,vnum-x,pp-last,num-xser,btit-rm,bt-rm,add-pub,%
  pre-edn,in-col,pp,abr,ednx,ord,jabr,xand,etal-xc,nfss,}}
\generate{\file{behavecol.bst}{\MBopts}}
\endbatchfile

and then run latex behavecol.dbj. Next, save the following to behavecol.patch:

--- behavecol.bst 2007-08-29 12:07:40.000000000 -0400
+++ behavecol_new.bst 2007-08-29 12:08:01.000000000 -0400
@@ -89,7 +89,7 @@
 FUNCTION {output.nonnull}
 { 's :=
   output.state mid.sentence =
-    { ", " * write$ }
+    { ". " * write$ }
     { output.state after.block =
         { add.period$ write$
           newline$
@@ -144,6 +144,9 @@
 FUNCTION {add.blank}
 {  " " * before.all 'output.state :=
 }
+FUNCTION {add.semicolon}
+{  ";" * before.all 'output.state :=
+}
 
 FUNCTION {date.block}
 {
@@ -248,7 +251,7 @@
 { "in" }
 
 FUNCTION {bbl.pages}
-{ "pp." }
+{ "p." }
 
 FUNCTION {bbl.page}
 { "p." }
@@ -260,10 +263,10 @@
 { "Tech. Rep." }
 
 FUNCTION {bbl.mthesis}
-{ "Master's thesis" }
+{ "[Master's thesis]" }
 
 FUNCTION {bbl.phdthesis}
-{ "Ph.D. thesis" }
+{ "[PhD thesis]" }
 
 FUNCTION {bbl.first}
 { "1st" }
@@ -488,6 +491,16 @@
     }
   if$
 }
+FUNCTION {format.book.pages}
+{ pages "pages" bibinfo.check
+  %duplicate$ empty$ 'skip$
+  empty$ 'skip$
+    { add.semicolon 
+      add.blank 
+      pages "pages" bibinfo.check 
+      " " * bbl.pages * }
+  if$
+}
 FUNCTION {format.note}
 {
  note empty$
@@ -950,6 +963,10 @@
     }
   if$
 }
+FUNCTION {format.university.address}
+{ school "school" bibinfo.warn format.org.or.pub
+}
+
 FUNCTION {format.publisher.address}
 { publisher "publisher" bibinfo.warn format.org.or.pub
 }
@@ -1148,12 +1165,11 @@
   author format.key output
   format.date "year" output.check
   date.block
-  format.title
-  "title" output.check
-  new.block
+  format.title "title" output.check
+  add.blank
   bbl.mthesis format.thesis.type output.nonnull
-  school "school" bibinfo.warn output
-  address "address" bibinfo.check output
+  format.university.address output
+  format.book.pages output
   new.block
   format.note output
   fin.entry
@@ -1178,12 +1194,11 @@
   author format.key output
   format.date "year" output.check
   date.block
-  format.title
-  "title" output.check
-  new.block
+  format.title "title" output.check
+  add.blank
   bbl.phdthesis format.thesis.type output.nonnull
-  school "school" bibinfo.warn output
-  address "address" bibinfo.check output
+  format.university.address output
+  format.book.pages output
   new.block
   format.note output
   fin.entry

Then run

patch < behavecol.patch

from the same directory that you ran the DBJ command in. That should generate the behavecol.bst file that is needed for the above template to work.

Broken sections in Elsevier elsart1p, elsart3p, and elsart5p

UPDATE: You should probably add

\def\@seccntformat#1{{\@secnumfont{}\csname the#1\endcsname.}\quad}

around line 128 (i.e., after the \@secnumfont definition) as well. Alternatively, you could add something similar (surrounded by \makeatletter and \makeatother) to your preamble.

Ever notice how section* is broken in elsart1p.cls, elsart3p.cls, and elsart5p.cls from Elsevier? Because of this, the section titles for the acknowledgments (i.e., from \ack) and the references look like normal text. Plus, the references do not show up in the PDF bookmarks. This "feature" is annoying; working with journals generally is.

How to fix this? You have to hack the document class files. In particular, you need to remove (or comment by placing a % on the beginning of the line) a chunk of lines from the document class of interest to you. In particular, remove

• elsart1p.cls - lines 144--196
• elsart3p.cls - lines 147--199
• elsart5p.cls - lines 144--196

These lines redefine the LaTeX internals \@startsection, \@sect, and \@ssect. However, it does not appear there is any good reason why Elsevier has done this, so just stick with the standard ones. This will make your document look much better too.

Until Elsevier does this for you, you should upload your modified document class with your article OR use the elsart document class in the version you send to Elsevier.

Copyright Explained

"Copyright Explained: I May Copy It, Right?" from Smashing Magazine

With blogging comes great responsibilty. You define the content of your weblog and you carry the full responsibility for every word you’ve published online. More than that, you are responsible for comments in your posts. To make sure you fulfill your legal obligations, it’s important to know, what you, as blogger, may or should do; and you have to know, how to achieve this. After all, the ignorance of the law does not make one exempt from compliance thereof.

This article explains copyright and how it applies to electronic material. Sure, it's focussed at bloggers, but anyone who is starting a career that involves publishing might be interested in this.

A reflection on (Springer) bibliographies (junior-part commas)...

In my previous post about Springer journal typesetting, I present the BiBTeX bibliography style files spmpsci.bst and spmpscinat.bst that were mostly generated by the docstrip driver files spmpsci.dbj and spmpscinat.dbj, respectively. I say mostly because I discovered that the original bibliography style files distributed by Springer were generated by docstrip but then manually hacked to remove the comma before the junior part (e.g., "Joe Public, Jr.") of the author and editor names.

You see, there is no way to use docstrip drivers based on merlin.mbs (from custom-bib) to have commas between author names and yet no commas before junior parts. Springer actually used the merlin.mbs option nm-rvv to get rid of commas and then hacked in between-author commas. I used the nm-rvvc option to include between-author commas and then hacked out the junior-part commas. The result is the same.

I have no problem listing author names without junior parts. As I mention in a Google groups thread, on page 3 of The Elements of Style by William Strunk Jr. and E.B. White, it is stated that the "Jr." after a last name should not have a comma before it (e.g., William Strunk Jr.). A number of journals agree with this, including The Journal of Mathematical Biology (i.e., a Springer journal using the Springer spmpscinat BiBTeX bibliography style).

At first I completely agreed with Springer and thought that merlin.mbs needed to be updated so that it had a junior part comma option. However, I gave it more thought and now I think that Springer should cease and desist. For one, this makes it difficult to regenerate the BST file from the DBJ driver options. The BST file distributed by Springer doesn't even mention that some manual editing has gone on, so anyone trying to generate their BST file will probably miss this hack. Second, while I think that authors who insert commas in their names need to stop this practice, if an author chooses to make his or her professional name comma-delimited, then journals should respect that author's wishes. Finally, if the BST junior-part comma is left in, commas can still be omitted by surrounding the junior (e.g., "Jr.") and the last name (e.g., "Smith") with curly braces (e.g., "{Smith Jr.}") in the BIB file. I haven't tested this, but I think that if this is done the Jr. becomes part of the BiBTeX last name (e.g., "{ll}") and thus there will be no comma before the junior in the resulting bibliography.

I'm sure Springer would tell me that they just want the bibliography entries to be consistent. However, names are messy things to mess with. Plus, modern-day BST files really should be specified entirely by a set of standard docstrip options (i.e., docstrip options and an MBS file). If non-standard options are really needed, a new MBS file should be distributed and the BST file should be spcified by options for that new MBS file. Would that be so hard to do for a publisher?

So that's my thought... Hey, publishers! Leave them BST files alone!

Reflections on Senility

A few things occurred to me after producing the latest poetic post.

At the moment, I am sitting next to two people who I haven't seen much in the last 12 years. As far as I know, they work together in putting together theatrical productions in Columbus. Whereas theatre is not part of my life anymore, it still remains strong in theirs. This is not uncommon. The potential for success in theatre is certainly not negatively correlated with age until a very old age. In fact, it may be positively correlated for most people, especially those who do not seek fame and fortune.

Similarly, I enjoyed writing that little poem. I also enjoyed writing my thesis and tracing the improvements I have made in my writing and presentation over the past few years. However, I have not enjoyed the pressure on me to be extremely productive before I turn 30 (or even 28). In many technical fields, real progress is expected at young ages. For whatever reason, progress at "old" ages is not possible or simply not favored.

This brings me to think about one of the older professors in my department. I have never had a class with this professor, so I know nothing about his methods of technical discourse. However, I do know that he paints, writes poetry, and is working on a fictional novel at the moment. I imagine that he has been working on that novel for a long time, and may never finish; however, he seems to me to be the proudest of that work compared to the other things he does now or even has done. He's not an emeritus professor, but he certainly is the age of some of the emeritus professors in the department.

I also think about the May 26 show of A Prairie Home Companion, which featured Billy Collins [1, 2], the two-term US poet laureate. The show also touched on age and writing professionally.

As I get older, either through experience or neurological development, my ability to understand things, retain them, and write matures. Because of this, I'm becoming more interested in the art of writing than I am my technical field of expertise. I think this is the reason why researchers in technical fields enjoy the idea of becoming a writer respected simply for the ability to write. For, while their ability to make technical progress might be impaired by their age, if they can become great writers, their ability to do that can only increase with age.

So that's a great thing. I'm excited about it. But in the meanwhile, I really must get back to work.

HyperRef Options for Proper BackReferencing with Figures Numbered Within Sections and Partial Roman Page Numbering

That's a really long title, I know.

I have a long document that has roman page numbering for its first four pages (i.e., its title page, table of contents, and list of figures). After that, the rest of the document has arabic page numbering starting at page 1 (so the first four pages of the document are i-iv, and the fifth page is page 1).

I have the option (via package amsmath)

\numberwithin{figure}{section}

turned on. This lets my figures be numbered by section (e.g., Figure 2.1).

I have backreferencing turned on (via hyperref) in my bibliography.

It turns out that hyperref won't get all of the links correct unless you massage it quite a bit. For example, page i and page 1 can get the same label (page.1) and so back references to page 1 end up getting sent to page i, which is clearly not correct. A similar thing can happen with Figure 2.1 and figure B.1; they both get labeled as figure.1 and so links to them get confused. There are lots of other pitfalls you run into as you turn on and off options to try to fix things.

Anyway, I had to dig through the hyperref and backref sources to figure out which options to set. These were the ones that I ended up needing. Things work as expected now.

\usepackage[pdfpagelabels,pagebackref,
            hypertexnames=true,plainpages=false,
            naturalnames]{hyperref}

NOTE: If you are producing a DVI rather than a PDF, if you want the links to work, you should probably use:

\usepackage[dvipdfm,
            pdfpagelabels,pagebackref,
            hypertexnames=true,plainpages=false,
            naturalnames]{hyperref}

That's the same line, but the "dvipdfm" option was added in front.

You should also use pdflatex to build your document. You can pass pdflatex an -output-format dvi option to get it to produce a DVI. (note: you can also symlink pdflatex to latex to get it to produce a DVI) (ALSO: you can add -src-specials to the pdflatex line if you're into source specials)

Phew. That took a long time to figure out. I need a beer.