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
  https://robrutten.nl/Manuals.html  
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