The html and pdf versions have active weblinks.
This manual was initially written for second-year astronomy students
at former Utrecht University doing the "Stellar Spectra" exercises at
https://robrutten.nl/Exercises.html Startup
=======
- begin by getting and unzipping file
https://robrutten.nl/rrweb/rjr-edu/manuals/student-report/studentreportfiles.zip to obtain the example latex input file
example.tex
the associated bibtex database file
example.bib
and the associated figure
waterfalls.ps waterfalls.pdf
plus some specific style files.
- you may use latex etc commands in a terminal (Unix/Linux/macOS)
or use a more elaborate interface as Texmaker, TeXworks, WinEdt,
TeXShop, Latexian, Texpad, etc.
Process the example file example.tex to see what it does:
latex - bibtex - latex - latex - inspection
using e.g., xdvi or Adobe Acrobat Reader for the latter.
- under Unix/Linux/macOS in a terminal or with auctex from emacs:
latex example # warns about undefined citations and references
latex example # only undefined citations; figure references OK
bibtex example # uses example.aux to make example.bbl from example.bib
latex example # puts refs from example.bbl into the .aux file
latex example # no complaints anymore: done
inspection and output per .dvi:
xdvi example & # .dvi preview; click to refresh after text changes
and when you are done
dvips -z example -o example.ps # produce PostScript output
gv example.ps # inspect PostScript output
lpr -Pprintername example.ps # print PostScript output
ps2pdf -dPDFSETTINGS=/printer example.ps # make pdf
inspection and output per .pdf:
pdflatex example # also makes a pdf but needs .pdf figures
acroread example.pdf & # inspect pdf output; print from menu
- inspect and modify my input file example.tex and its output;
experiment how the former generates the latter.
Make your template
==================
- a template for your own report is easily made by removing my content
from example.tex while keeping all latex commands.
- a template for Astronomy and Astrophysics (A&A) publications is easily
made by replacing my header stuff by the pertinent A&A commands
(\title, \author, \titlerunning, \institute, \date, \offprints,
\abstract, \keywords and \maketitle). The rest remains the same.
- a template for Astrophysical Journal (ApJ) publications is easily made by
replacing the aa.cls and aa.bst files by the ApJ styles and the
header stuff by the ApJ commands. The rest remains the same.
Unfortunately, ApJ's editing does not retain ADS-clicker citations.
Latex text typing (check this most careful and make it habits)
==============================================================
- use WinEdt or such, or a Unix/Linux/macOS editor to type the latex
input text (Emacs has special features for latex and bibtex).
Type pure ASCII: generate accents etc with latex \ commands.
Good typing habits:
- indent equations and environments as in programming
- add comments to clarify what you are doing to yourself and coauthors
(latex skips the remainder of a line after %, type \% to get %)
- consider starting each new sentence on a new line (in Emacs this
can be automated with the .emacs settings at
https://robrutten.nl/Recipes_linux_unix.html
- new paragraph = 1 or more blank lines, not ....\\[1ex]
- spaces:
multiple spaces is the same as a single space
no-line-break-space: ~ R.J.~Rutten, 1083.0~nm line
(otherwise you may get the unit nm on the next line)
code space after period after small character: Prof.\ Dr.\ C.~Zwaan
(otherwise latex adds more space taking it to be end of a sentence)
code space after latex command: 4554~\AA\ line, but \AA. Nordlund
(otherwise latex eats the space as command delimiter)
- dashes: hyphen = - magneto-acoustic
longer dash = -- 5--min oscillation
longest dash = --- he wrote---but I think (ApJ habit)
she wrote -- but I think (A&A habit)
- quotation marks: use “......”, never "...."
- mathematics:
$...$ for in-text math
never use \frac in in-text math (too small), use $a/b$ instead
\begin{equation}
........ for displayed & numbered equation (indent!)
\label{eq:whatever}
\end{equation}
Use \sin, \cos, \exp etc ($sin$ means product s i n)
Use roman alphabet for non-mathematical indices
(code only math variables in math notation ($x$), cf. A&A manual):
$T_{\rm eff}$
($T_{eff}$ makes eff = product e, f and f)
\begin{equation}
B_\nu(T) = \frac{2\pi m_{\rm e} c^2}{h^3}
%% e = electron
\frac{1}{\exp{-h\nu/kT}-1}
\label{eq:Planck}
\end{equation}
Use {\rm d} or \partial for differential d
Add thin space with \, before differential d, {\rm e}^{..} etc
Shrink space: for the $n\!=\!2$ level
Add punctuation after equations, just as in normal text
- numbers and units:
$B_\nu = 5\,10^{12}$~erg\,cm$^{-2}$\,s$^{-1}$\,sterad$^{-1}$
$v=50$~km\,s$^{-1}$ velocity
180~s 10~mHz
a $40 \times 30$~arcsec$^2$ field
alternative is to use smaller blank space with \,:
50\,km\,s$^{-1}$ velocity
the Ba\,II\,4554\,\AA\ line (NB: the \ after \AA to get a normal space)
10\,mHz frequency
at $\lambda \approx 160$\,nm one observes
- crossreferences:
make all references to figures, tables, equations, sections
dynamic by adding labels to them:
\label{fig:power images}
\label{tab:lines}
\label{eq:mass conservation}
\label{sec:discuss}
and refering to these as:
in Section~\ref{sec:discuss} we discuss
Figure~\ref{fig:power images} shows power spectra
(see Figs.~\ref{fig:xx}, \ref{fig:xx}---\ref{fig:xx})
inserting this result into eq.~(\ref{eq:mass conservation})
NB: latex needs to be run twice to get all crossreferences right.
- literature citations and references:
Most astronomers and astronomy journals use the name-year system:
.... by Rutten and Schrijver (1994)
(see Schrijver, 1993e; Rutten, 1993).
.... (cf.\ Rutten \& Schrijver 1994)
but Nature and some others use numbered references.
See example.tex and below for automatic reference generation with bibtex.
Latex processing
================
When your XXXX.tex file is done or partly done, process it as the
example file above (latex - latex - bibtex - output) and inspect the
output.
Latex errors are usually due to unmatched pairs of $$, {}, \begin and
\end. I often mistakenly type $ for & in tables.
If you don't like the layout do not try local solutions such as
ad-hoc white space but adapt the formats by more general commands at
the start of your file. You may feel that latex confines you to
overly restrictive straightjackets. Then switch to TeX ("the
sportscar engine under the hood of the latex sedan") - but first ask
yourself whether you want to be a professional typesetter or a
professional astronomer. For astronomical publications you need to adhere
strictly to the style of the publisher. They have chosen latex in
order to fix the layout their way without bothering you or being
bothered by you. So don't try to re-invent the wheel!
When you are happy with what the previewer shows:
aspell -t --dont-tex-check-comments check XXXX.tex # check for typos
aspell -t -d british --dont-tex-check-comments check XXXX.tex # brexit
latex XXXX # final version
To clean your working directory from all the latex auxiliary files,
you might in Unix/Linux/macOS define a command like:
alias rmtex 'rm *.aux *.dvi *.lis *.log *.blg *.bbl *.toc'.
You need to keep only your .tex file, the .ps or .eps or .pdf figure
files, the .bib file and the style files. Latex and bibtex regenerate
all others.
References
==========
- my example.tex file closely copies A&A habits. The references are
formatted in the style used by A&A and ApJ, as defined in Bibtex
style file aa.bst (or my aa-note.bst modification). For other
journals hunt the web for an appropriate XXX.bst bibstyle file.
- the corresponding bibtex input file example.bib has the necessary
bibtex "items" exported directly from ADS
https://ui.adsabs.harvard.edu Sometimes, especially for proceedings publications, you need to
improve the ADS entry.
- the example file uses my \citeads citation commands. These turn
the in-text citation into a clicker that opens the corresponding
ADS abstract page in the browser if the pdf reader permits internet
access. (In Adobe Acrobat/Reader this is an option under Edit >
Preferences > Trust Manager > Change Settings that Adobe defaulted
off on the advice of the infamous NSA). Such opening is convenient
in on-screen reading because it shows the cited publication in
parallel to one's reading, without jump to the reference list.
These commands require that you use separate \citeads commands per
cited publication using its ADS label (which is useful anyhow for
not confusing you coauthors). This trick survives the A&A
production process and A&A recommends it. It also survives in
the pdf generation by arXiv (Astroph). It does not survive the
re-latexxing by the ApJ office before that sends the resulting pdf
to IoP (which handles hyperlinks correctly but receives molested
ApJ input). Reversely, in Springer journals it survives editorial
text editing but not the Springer production. The macros in
example.tex have been updated from "classic ADS" to "modern ADS".
- My aa-note.bst modification of aa.bst also permits adding ADS
clickers and notes as (Pub I) to the references, as in example.tex.
- the example file also contains \linkadspage which produces direct
clickers to open specific pages containing cited figures, tables,
equations, etc. For example clicking on Fig.~1 in "(See Fig.~1 of
Rutten et al. 1991)" then opens the particular page with that
figure in your browser, much as Wikipedia opens links directly.
This nice option also survives pdf production by arXiv and by A&A
and even at Springer, but probably not for ApJ. It works only for
publications with the pdf directly accessible at ADS; otherwise use
the arXiv link given at ADS. This macro works properly in Adobe
Acrobat/Reader, the Gnome and Firefox pdf viewers, evince, xpdf and
others, but not in macOS Preview which instead opens the first
page.
- in my own writing I use automated scripts to regularly download all
the abstracts and corresponding bibtex items for all publications
by all my colleagues. I so maintain my own abstract collection.
While writing I simply copy the ADS bibcode found in these
abstracts into a \citeads command in my manuscript latex file,
and let bibtex find the corresponding reference info by searching
the whole database. See
https://robrutten.nl/Recipes_publications.html Figures
=======
- figure location: I keep my figure files in a subdir /figs per publication.
- layout: keep your figures small but make their labeling large. Aim
at vertical panel stacking for A&A manuscripts or other
column-style publications. Often you should remove the axis
annotation between adjacent same-scale panels to gain space.
- resolution: since many people read publications on-screen per pdf
viewer you can suggest to zoom in on detail, but then be sure to
maintain the original image resolution. The template file below
shows how.
- multipanel figures: I do not make multipanel figures in IDL (a
hassle) but prepare standalone figures with full axis annotation
for each panel in IDL and then do the multi-panel assembly in
latex, stripping off the axis annotation where desired. The
advantage of this approach is that I can choose between page-wide
horizontal or column-high vertical panel assembly depending on
how the publication layout comes along, while I am writing it and
without bothering co-authors that have contributed figures. I do
such assembly using my self-explanatory template file at
https://robrutten.nl/Multipanel_figure.html - color: usually too expensive for oldfashioned publication on paper
but fine for modern pdf production with web distribution.
Remember that red-green color blindness is common and that poorer
institutes do not have color printers.
- figure location: you have to find by trial where to stick a
particular {figure} environment in your latex input file to get
it to a suitable location in the output. It comes at or after
the insert location in your text, not before. The same holds for
other "floats" such as tables. Always have figures and tables
surrounded by blank lines in your input xxx.tex file to let them
float.
- figure clipping:
\includegraphics[bb = 11 278 408 544,width=88mm,clip]
where the four numbers are the x and y of the lower-left
and upper-right corners of the cutting box in bp units. You can
measure these manually with Ghostview, in Unix/Linux/macOS with
gv figure.ps
which displays the cursor position in bp units at the upper left.
- figure stealing in Adobe Reader:
- open the pdf file
- click on Tools > Select Zoom > Snapshot Tool
- draw cutout rectangle
- right mouse button: print
- print menu: Auto Rotate off; Portrait; Print to file = myfig.ps
- cut bounding box: see below
- figure stealing in macOS:
- open the pdf file with open -a Preview file.pdf
- click on the "graphic select tool" button
- draw cutout rectangle
- Apple C, Apple N
- file menu: save to file figure.pdf
- figure conversion ps, eps, pdf in Unix/Linux/macOS:
ps2eps file.ps # cut the bounding box, but it can misfire
ps2epsi file.ps # idem, sometimes better
ps2pdf # convert ps to pdf
epstopdf file.ps # convert ps or eps into pdf
pdfcrop file.pdf # cut figure to its actual bonding box
pdfcrop --margins 5 file.pdf # idem adding small white margins
- figure conversion to .png for presentation displays in Unix/Linux/macOS:
I use (per script) command:
pdftoppm -png -r 500 -singelefile file.pdf file
where increasing the resolution parameter produces png figures
that can be blown up, should be up to showing telescope pixels.
I may annotate the png product with the reference through
a script with entries:
pdfcrop --margins "5 20 5 5" $2:gr.pdf
convert -density 400 -geometry 1024x768 -background white -flatten -font "-misc-fixed-medium-r-normal-*-20-*-*-*-*-*-*-*" -fill black -draw "text 10,15 '${1}'" $2:gr-crop.pdf ann-$2:gr.png
- eps figure conversion to smaller file size (when too much detail,
for example scatter plots) with Unix/Linux/macOS script:
#!/bin/csh
epstopdf $1
pdfcrop $1:gr.pdf
convert -density 500 -geometry x1000 -background white -flatten
$1:gr-crop.pdf $1:gr.jpg
jpeg2ps -h $1:gr.jpg > small-$1:gr.eps
rm -f $1:gr.pdf $1:gr-crop.pdf $1:gr.jpg
Mark texfile changes
====================
When you co-write with others and want to mark changes or when an
editor wants coloring of all text changes between an older and a new
submission, you may use the latexdiff tool:
latexdiff --flatten --append-textcmd="abstract" --encoding="ascii" ms_old.tex ms_new.tex > ms_diff.tex
and then run "pdflatex diff.tex" 2 or 3 times. The resulting
ms_diff.pdf has all deleted text colored red with strike-through, all
new text colored blue with wavy underling. If you use some private
\mycommand{..<text>..} you should add that also into the append
option (="abstract,mycommand") to color changes in its text body.
Latexdiff already does this default for the caption environment.
Other manuals
=============
- Leslie Lamport's original LaTeX book remains one of the best
manuals ever written. It is the only printed manual which I still
use (I Google any other software question). Usually I look up a
final Part-C entry in the index to check the complete definition.
- the "LaTeX Companion" book offers many tricks but none or few are
needed by astrophysicists.
- Google <latex manual> <simple latex manual> delivers many good
to excellent manuals.
- Google <A&A> leads you to the A&A website with extensive writing
instructions for A&A publications.
- Google <ApJ> leads you to an ApJ website which directs you to the
AASTeX instructions and macros for ApJ manuscript preparation.
- Natbib reference sheet:
http://merkel.zoneo.net/Latex/natbib.php - the tex comunity of stackexchange offers many answers:
https://tex.stackexchange.com