first-latex-doc update (7jul09)

git-svn-id: svn://tug.org/texlive/trunk@14346 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 146 insertions, 77 deletions

diff --git a/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.pdf b/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.pdf
index 82893c78da7..c8660106659 100644
--- a/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.pdf
+++ b/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.pdf
diff --git a/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.tex b/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.tex
index 4162980678e..b7354ed514a 100644
--- a/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.tex
+++ b/Master/texmf-dist/doc/latex/first-latex-doc/first-latex-doc.tex
@@ -24,12 +24,26 @@
 \usepackage{url}
 \usepackage[pdftex, 
             bookmarks, 
-            colorlinks=true, 
+            colorlinks=true,
+            linkcolor=black, 
             plainpages = false,
             pdfpagemode = UseNone,
             pdfstartview = FitH, 
             citecolor = ac, urlcolor = ac, filecolor = ac]{hyperref}
 
+\usepackage[para]{footmisc}
+% Change horiz room between fn mark and fn hskip from .5em 
+% Suggested to RF making this settable
+\makeatletter
+\long\def\@makefntext#1{\leavevmode
+\@makefnmark\nobreak
+\hskip.05em\relax#1%
+}
+\makeatother
+%\newcommand{\texdoc}[1]{\/\footnote{\protect\texttt{#1}}}
+\newcommand{\citelink}[3]{\href{#1}{#2}~\cite{#3}}
+\newcommand{\bibliolink}[2]{\href{#1}{\nolinkurl{#1}}, \href{#1}{#2}}
+
 \setlength{\parskip}{0.75ex}
 \makeatletter % from emma pease at csli.stanford.edu
 % \@startsection {NAME}{LEVEL}{INDENT}{BEFORESKIP}{AFTERSKIP}{STYLE} 
@@ -50,10 +64,10 @@
 %  If '*' missing, then increments the counter.  If it is present, then
 %  there should be no [ALTHEADING] argument.  A sectioning command
 %  is normally defined to \@startsection + its first six arguments.
-\def\section{\@startsection {section}{1}{\z@}{-2.5ex plus -.6ex minus 
-    -.2ex}{1.0ex plus .15ex}{\hspace*{-3em}\Large\bf\color{ac}}}
-\def\subsection{\@startsection{subsection}{2}{\z@}{-1.5ex plus -.3ex minus 
-   -.1ex}{.3ex plus .1ex}{\hspace*{-2.5em}\bf\large\color{ac}}}
+\def\section{\@startsection {section}{1}{\z@}{2.5ex plus .6ex minus 
+    .2ex}{1.0ex plus .15ex}{\hspace*{-3em}\Large\bf\color{ac}}}
+\def\subsection{\@startsection{subsection}{2}{\z@}{1.5ex plus .3ex minus 
+   .1ex}{.2ex plus .1ex}{\hspace*{-3em}\bf\large\color{ac}}}
 \makeatother
 \setcounter{secnumdepth}{0}
 
@@ -63,7 +77,7 @@
 \title{Getting something out of \LaTeX{}}
 \author{Jim Hef{}feron}
 
-\pagestyle{empty}
+\pagestyle{plain}
 \begin{document}
 \thispagestyle{empty}
 % \maketitle
@@ -89,13 +103,14 @@ If this quick taste leaves you wanting more
 then you are ready to go through a tutorial.
 
 Because this is a just a taste, we will skip many things.
-And for those things that we discuss, we will see only one way to do them.
+And, for those things that we will discuss, 
+we will see only one way to do them.
 For instance, in the first section there are a number of ways to get 
 the software but we will just name one.
-This approach has the disadvantage of leaving you without a full idea
-of what the system entails, 
+This approach has the disadvantage of leaving you without a full understanding
+of the system 
 but has the advantage that in a couple of hours 
-you should finish with some idea of whether
+you will know whether
 \LaTeX{} is a tool that can help you.
 
   
@@ -104,26 +119,23 @@ you should finish with some idea of whether
 
 \section{Get the software}
 
-\LaTeX{} is the way that we will use the \TeX{} suite of 
+\LaTeX{} is how we will use the \TeX{} suite of 
 programs.
-So you must download those programs (if you don't already have them).
-Here we will stick with downloads that are free.
-
-If your computer system is Windows then go to the  
-\href{http://www.miktex.org}{MiK\TeX} site.
-Click on the link under ``Download'' and follow the directions.
-If you have a Unix-like system, such as Linux, then go to the
-\href{http://www.tug.org/texlive/}{\TeX{} Live}
-site and click on the ``Downloads'' link.
-If you have a Macintosh then use the 
-\href{http://www.tug.org/mactex/}{Mac\TeX} site
-(this is a version of \TeX{}~Live, with some Mac-specific add-ons).
-
-All three downloads are large, but all three install easily (of course,
-you must follow the on-screen directions; in particular on 
+So you must download that suite, if you don't already have it.
+We will describe only options that are free.
+
+If your computer system is Windows then download 
+\citelink{http://www.miktex.org}{MiK\TeX}{miktex}.\footnote{For people with a printed version of this document we list links at the end.}
+If you have a Unix-like system such as GNU/Linux then get
+\citelink{http://www.tug.org/texlive/}{\TeX{} Live}{texlive}.
+For a Macintosh get
+\citelink{http://www.tug.org/mactex/}{Mac\TeX}{mactex},
+a version of \TeX{}~Live with some Mac-specific add-ons.
+
+All three downloads are big but all three install easily (of course,
+you must carefully follow the directions; in particular on 
 a Unix-like system you will need to alter your \texttt{PATH}).
-They come with an immense amount of stuff.
-But here we are just trying \LaTeX{} out so we will skip past lots of things.
+Here we are only giving \LaTeX{} a try so we will skip most things.
 
 
 
@@ -139,9 +151,9 @@ In a \TeX{}-based system those jobs are done separately.
 Instead, we write \LaTeX{} with an editor, 
 a program that is specialized at moving text around in a computer file.
 There are many editors,
-including some specifically for writing \LaTeX{}, but
-our documents are small so almost any editor will do. 
-Just to give a couple of names:
+including some specifically for writing \LaTeX{}, but below
+our documents are small so any editor will do. 
+Just to name a couple of names:
 on a Windows system you can use Notepad,
 while on a Unix-like system or a Mac you can use Emacs.
 
@@ -151,14 +163,14 @@ while on a Unix-like system or a Mac you can use Emacs.
 
 \section{Get it to work}
 
-With an editor, you can write a first document.
+Having picked an editor, you can write a first document.
 Make a new directory
 named \nolinkurl{latex-first}  
 (your system might use the term ``folder'').
 Open a terminal window and in that window, change into that directory
 (possibly you would use the command \verb!cd latex-first!).
 
-Move back to your editor window.
+Next start your editor.
 Open the new file
 \nolinkurl{latex-first.tex}
 in the \nolinkurl{latex-first} directory. 
@@ -177,15 +189,15 @@ Hello world!
 \end{document}
 \end{lstlisting}
 Many of those things are boilerplate~--- lines that I put into every
-\LaTeX{} file that I open.
+\LaTeX{} file.
 We'll ignore what they mean for a while to focus on getting
-output.
+out a first document.
 
 Save that file.
 Go back to your terminal window and enter this command.
-\begin{center}
-\verb!pdflatex latex-first!
-\end{center}
+\begin{lstlisting}
+pdflatex latex-first
+\end{lstlisting}
 If that worked then you should see perhaps forty lines of text, 
 starting with something like 
 \begin{lstlisting}
@@ -200,24 +212,24 @@ Transcript written on latex-first.log.
 \end{lstlisting}
 If you had errors, see the subsection below.
 
-You can view the output \nolinkurl{latex-first.pdf} with
-whatever program your system uses to view PDF files.
+You can view the output file \nolinkurl{latex-first.pdf} with
+whatever program your system uses to view PDF.
 \begin{center}
   \includegraphics[scale=.35]{latex-first.png}
 \end{center}
 
 \subsection{Handle errors}
 
-You have to be careful to type the lines as written.
+Check that you have typed the lines exactly.
 Some seemingly small typing changes give large changes in the
-result, including causing a document to not be processable.
+result, including causing a document to not work.
 So that you can be sure there isn't a typing discrepancy, 
-this document comes bundled with a source of
-\nolinkurl{latex-first.tex} that you can run.
+you can get a known-good copy of
+\nolinkurl{latex-first.tex}; see 
+\protect\citelink{http://www.ctan.org/tex-archive/info/first-latex-doc/}{this document's source}{firstdoc}.
 
 If your run ends with a question mark, then you can type `\verb!x!' and
-then hit `Enter' to get out.
-You will still be able to see any error message that the system prints.
+hit the `Enter' key to get out.
 
 \LaTeX's error messages can be hard to understand.
 If you know someone with some experience, of course that's great.
@@ -245,18 +257,17 @@ We've modified the behavior in small ways by bringing in some
 packages such as \verb!graphicx!, which will allow us to include
 graphic files.
  
-For the next step,
+Next
 we'll make a longer and more complex document.
 Start the same way:
 make a new directory
 named \nolinkurl{latex-second},
 open a terminal window, and change into the new directory.
-
-Move back to your editor window.
-Open a new file
-\nolinkurl{latex_second.tex}
+Then move back to your editor window and
+open a new file
+\nolinkurl{latex-second.tex}
 in the \nolinkurl{latex-second} directory. 
-Enter the text below.
+Enter this.
 \begin{lstlisting}[style=latex]
 \documentclass{article}
 \usepackage{geometry}
@@ -275,20 +286,20 @@ of text that is commonly used for examples in this field.
 \lipsum[1-7]
 \end{document}
 \end{lstlisting}
-Save that file and run
-\verb!pdflatex latex_second!.
-Your system's PDF reader should show something like this.
+Save that file and in the terminal window run
+\verb!pdflatex latex-second!.
+Your system's PDF reader should show this.
 \begin{center}
   \includegraphics[scale=.35]{latex-second-a.png}
 \end{center}
 
 If you have used a word processor then you will have noticed the 
-difference between that tool and running \LaTeX{}.
-Here the program  does not move the text around as we type it,
-rather we tell \LaTeX{} what we want and then it does that.
-This applies to the commands that we see below.
-For instance,
-we tell \LaTeX{} to make a section and the system 
+difference between that tool and \LaTeX{}.
+A word processor moves the text around as you type it.
+With \LaTeX{}, you describe what you want and then it goes off and 
+figures out how best to do that.
+For instance, below we will
+tell \LaTeX{} to make a section and the system 
 handles the font changes, vertical space, etc.
 
 In your editor, change the file \nolinkurl{latex-second.tex} to say this.
@@ -361,15 +372,15 @@ and look at the PDF file.
 Notice that the references that we just entered didn't work~--- they appear
 as question marks.
 As \LaTeX{} runs it saves labels to a file.
-So, when you run a file with a first-time label it has not yet been saved.
-The solution is to run \verb!pdflatex latex-second! again.
-The result looks like this.
+When you run a file with a first-time label it has not yet been saved.
+The question marks go away when you run \verb!pdflatex latex-second! 
+a second time.
 \begin{center}
   \includegraphics[scale=.35]{latex-second-c.png}
 \end{center}
 (When you are writing a real document, because you are fixing typos, etc.,
-you end up running \LaTeX{} a number of times anyway, so having to
-rerun the command isn't an issue in practice.)
+you will run \LaTeX{} a number of times, so in practice having to
+rerun the command isn't an issue.)
 
 We'll finish by adding footnotes, a
 table of contents, and a bibliography.
@@ -417,7 +428,7 @@ Note also the discussion on page \pageref{labeltwo}
 \begin{thebibliography}{9}
 \bibitem{ConcreteMath}
 Ronald L. Graham, Donald E. Knuth, and Oren Patashnik, 
-\textit{Concrete mathematics}, 
+\textit{Concrete Mathematics}, 
 Addison-Wesley, Reading, MA, 1995.
 \end{thebibliography}
 \end{document}
@@ -447,7 +458,7 @@ line to this.
 
 Many people interested in \LaTeX{} 
 want to include mathematics.
-The examples below are from \cite{ConcreteMath}.
+The examples below are from \textit{Concrete Mathematics}~\cite{ConcreteMath}.
 (We'll stop giving the complete listings of the input files,
 and we'll stop showing screenshots to instead just give the output directly.)
 
@@ -540,7 +551,7 @@ if the prime factorization of $m$ is $\prod_p p^{m_p}$.
 \end{minipage}
 \end{center}
 (The
-\href{http://mirror.ctan.org/info/symbols/comprehensive/symbols-letter.pdf}{\textit{Comprehensive \LaTeX{} Symbols List}} 
+\citelink{http://mirror.ctan.org/info/symbols/comprehensive/symbols-letter.pdf}{\textit{Comprehensive \LaTeX{} Symbols List}}{comprehensive} 
 shows the widely-available symbols.)
 
 The \verb!amsthm! package gives us access to theorem environments,
@@ -552,14 +563,16 @@ but those go beyond the scope of this document.
 You now have a feel for \LaTeX.
 To go on, 
 see the tutorial
-\href{http://mirrors.ctan.org/info/lshort}{\textit{The Not-So-Short Guide to \LaTeX  2e}}
+\citelink{http://mirror.ctan.org/info/lshort}{\textit{The Not-So-Short Guide to \LaTeX  2e}}{notsoshort}
 or the 
-\href{http://www.tug.org.in/tutorials.html}{Indian \TeX{} Users Group's tutorial}.
+\citelink{http://www.tug.org.in/tutorials.html}{Indian \TeX{} Users Group's tutorial}{indian}.
+More references are in the
+\citelink{http://mirror.ctan.org/tex-archive/info/latex-doc-ptr/}{\LaTeX{} Document Pointer}{latexdocptr}.
 
 If what you've seen seems very different from what you are used to,
 and you'd like an overview of the advantages of \LaTeX{},
 see
-\href{http://www.tug.org/TUGboat/Articles/tb22-1-2/tb70heff.pdf}{Why \TeX?}.
+\citelink{http://www.tug.org/TUGboat/Articles/tb22-1-2/tb70heff.pdf}{Why \TeX?}{whytex}.
 
 When you take up \LaTeX{} for real-life documents, you need
 to choose a good editing program. 
@@ -568,20 +581,76 @@ other components such as an output view, a spell checker that works
 with \LaTeX{}, etc.
 For advice, ask \LaTeX{} users that you know or click around on the Internet, 
 for instance on
-\href{http://groups.google.com/group/comp.text.tex/topics?gvc=2}{\url{comp.text.tex}}.
+\citelink{http://groups.google.com/group/comp.text.tex/topics?gvc=2}{\url{comp.text.tex}}{ctt}.
 (For what it is worth, I use \verb!emacs! with the AUC\TeX{} add-on.  
 On the Macintosh, many people use
-\href{http://www.uoregon.edu/~koch/texshop/}{\TeX Shop}.
+\citelink{http://www.uoregon.edu/~koch/texshop/}{\TeX{} Shop}{texshop}.
 A cross-platform editor, developed for the \TeX{} Users Group
 with the goal of simplicity, is 
-\href{http://www.tug.org/texworks/}{\TeX{}works}.)
+\citelink{http://www.tug.org/texworks/}{\TeX{}works}{texworks}.)
 
+% \raggedright
+\begin{thebibliography}{99}
+\bibitem{comprehensive}
+\bibliolink{http://mirror.ctan.org/info/symbols/comprehensive/symbols-letter.pdf}{\textit{Comprehensive \LaTeX{} Symbols List}}, 
+Scott Pakin, 
+2008.
 
-\begin{thebibliography}{9}
 \bibitem{ConcreteMath}
+\textit{Concrete Mathematics}, 
 Ronald L. Graham, Donald E. Knuth, and Oren Patashnik, 
-\textit{Concrete mathematics}, 
 Addison-Wesley, Reading, MA, 1995.
+
+\bibitem{ctt}
+\bibliolink{http://groups.google.com/group/comp.text.tex/topics?gvc=2}{\url{comp.text.tex} usenet group},
+group authorship, 
+2009.
+
+\bibitem{firstdoc}
+\bibliolink{http://www.ctan.org/tex-archive/info/first-latex-doc/}{\textit{Getting something out of \LaTeX}} (source for this document), 
+Jim Hefferon, 
+2009.
+
+\bibitem{indian}
+\bibliolink{http://www.tug.org.in/tutorials.html}{Indian \TeX{} Users Group's tutorial}, 
+Indian \TeX{} Users Group,
+2003.
+
+\bibitem{latexdocptr}
+\bibliolink{http://mirror.ctan.org/tex-archive/info/latex-doc-ptr/}{\LaTeX{} Document Pointer}, 
+Jim Hef{}feron, others,
+2009.
+
+\bibitem{mactex}
+\bibliolink{http://www.tug.org/mactex/}{Mac\TeX}, 
+Gerben Wierda, Jerome Laurens, Richard Koch, Herb Schulz, Karl Berry, others.  
+
+\bibitem{miktex}
+\bibliolink{http://www.miktex.org}{MiK\TeX}, 
+Christian Schenk, 2009.
+
+\bibitem{notsoshort}
+\bibliolink{http://mirror.ctan.org/info/lshort}{\textit{The Not-So-Short Guide to \LaTeX  2e}}, 
+Scott Pakin, 
+2008.
+
+\bibitem{texlive}
+\bibliolink{http://www.tug.org/texlive/}{\TeX{} Live}, 
+Sebastian Rahtz, Karl Berry, others.
+
+\bibitem{texshop}
+\bibliolink{http://www.uoregon.edu/~koch/texshop/}{\TeX{} Shop}, 
+Richard Koch, 2009.
+
+\bibitem{texworks}
+\bibliolink{http://www.tug.org/texworks/}{\TeX{}works}, 
+Jonathan Kew, 2009.
+
+\bibitem{whytex}
+\bibliolink{http://www.tug.org/TUGboat/Articles/tb22-1-2/tb70heff.pdf}{Why \TeX?}, 
+Jim Hef{}feron, 
+\textit{TUGBoat},
+vol~22 no~1/2, 2001.
 \end{thebibliography}