file: latex-bibtex-simple-manual.txt = introduction to latex and bibtex init: sometime 1991 Rob Rutten Deil last: Dec 20 2021 Rob Rutten Deil site: /rr/edu/manuals/latex-bibtex-simple/ note: renew there with renewandputonweb SIMPLE LATEX AND BIBTEX INSTRUCTION FOR ASTRONOMY STUDENTS Robert J. Rutten Lingezicht Astrophysics Deil Institutt for Teoretisk Astrofysikk Oslo This simple latex and bibtex tutorial tells you how to write a report that will be closely similar in appearance to A&A and ApJ publications, and is easily modified into an A&A or ApJ manuscript. There are parallel txt, pdf, and html versions of this manual at <> 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 <> Startup ======= - begin by getting and unzipping file <> 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 <> - 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 <> 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 <> 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 <> - 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{....} 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 delivers many good to excellent manuals. - Google leads you to the A&A website with extensive writing instructions for A&A publications. - Google leads you to an ApJ website which directs you to the AASTeX instructions and macros for ApJ manuscript preparation. - Natbib reference sheet: <> - the tex comunity of stackexchange offers many answers: <>