summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/amscls-doc/ams-author-handbook-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/amscls-doc/ams-author-handbook-doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/amscls-doc/ams-author-handbook-doc.tex366
1 files changed, 366 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/amscls-doc/ams-author-handbook-doc.tex b/Master/texmf-dist/doc/latex/amscls-doc/ams-author-handbook-doc.tex
new file mode 100644
index 00000000000..9beb9206628
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/amscls-doc/ams-author-handbook-doc.tex
@@ -0,0 +1,366 @@
+%%
+%% This is file `ams-author-handbook-doc.tex'
+%%
+%% Copyright 2017 American Mathematical Society.
+%%
+%% American Mathematical Society
+%% Technical Support
+%% Publications Technical Group
+%% 201 Charles Street
+%% Providence, RI 02904
+%% USA
+%% tel: (401) 455-4080
+%% (800) 321-4267 (USA and Canada only)
+%% fax: (401) 331-3842
+%% email: tech-support@ams.org
+%%
+%% This work may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either version 1.3c
+%% of this license or (at your option) any later version.
+%% The latest version of this license is in
+%% http://www.latex-project.org/lppl.txt
+%% and version 1.3c or later is part of all distributions of LaTeX
+%% version 2005/12/01 or later.
+%%
+%% This work has the LPPL maintenance status `maintained'.
+%%
+%% The Current Maintainer of this work is the American Mathematical
+%% Society.
+%%
+%% ========================================================================
+\documentclass{amsart}
+
+% The option [openright] is used in the macro set, which assumes the use
+% of amsbook; it is not provided by amsart, so set it up here.
+\makeatletter
+\newif\if@openright
+\makeatother
+
+% Use the same macros applied to the Handbooks.
+\usepackage{ahandinstr-r}
+
+% test redefinition to get \tt underscore
+%\catcode`\_=12
+\renewcommand{\fn}[1]{{\def\_{\ttfamily\char`\_}%
+ \mbox{\texttt{\ignorespaces#1\unskip}}}}
+%\catcode`\_=8
+
+% Replace \scshape in section headings to preserve file names.
+\makeatletter
+\renewcommand{\section}{\@startsection{section}{1}%
+ \z@{.7\linespacing\@plus\linespacing}{.5\linespacing}%
+ {\normalfont\bfseries\centering}}
+\makeatother
+\setcounter{secnumdepth}{0}
+
+\newcommand{\BibTeX}{\textsf{Bib\!\TeX}}
+\newcommand{\XeTeX}{\textsf{Xe\TeX}}
+
+\begin{document}
+\title{Compiling the AMS Author Handbooks from~a~complex source}
+\author[AMS Technical Support Group]%
+ {AMS Technical Support Group\\Version 1.0, September 2017}
+
+\begin{abstract}
+ Publications of the American Mathematical Society (AMS) are of several
+ types, each based on an AMS-specific document class. Manuscripts are
+ prepared by authors and (after editorial acceptance) are submitted to
+ the Society's production department where they are processed for
+ printing and publication.
+
+ In order to make this process as painless as possible for both authors
+ and production staff, instructions for authors---the AMS Author
+ Handbook---has been created in separate versions, one for each type of
+ publication. Author instructions are in large part common to all
+ publication types, with specific additions or variations as needed.
+ The core material is contained in one large \LaTeX\ file, with variant
+ material selected on the basis of binary switch settings, either from
+ embedded options or pulled in from subsidiary files. Creation and
+ management of that exercise is the subject of this overview.
+\end{abstract}
+\maketitle
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Introduction}
+\label{sec:intro}
+The purpose of the present document is to explain how a four-version
+user manual is generated from a ``single'' source, consisting of a
+core central text, modified by or augmented with product-specific
+material provided by command-specified variants or additional files
+addressing specific topics. The manual(s) being described are entitled
+``AMS Author Handbook'', and will be referred to collectively here as
+the ``Handbooks''.
+
+This overview is directed toward \latex/ users who are already familiar
+with the general mechanics of developing packages and writing the
+associated documentation.
+
+AMS publications fall into four types, each based on an AMS-specific
+document class:
+\begin{itemize}
+\item Journals: articles use the \cls{amsart} document class.
+\item Monographs and textbooks: \cls{amsbook} defines the core style,
+ with variations---sometimes extensive---provided in the form of
+ series-specific document classes.
+\item Proceedings and similar collections: articles are prepared using
+ \cls{amsproc} or a series-specific variation. There is no attempt to
+ process a complete volume as a unit; articles are processed separately
+ and combined later from individual \fn{pdf} files. Front matter is
+ also prepared separately using a dedicated \cls{editor} class, which
+ will not be further discussed here.
+\item \Memos: this is a hybrid series with individual units based on
+ \cls{amsbook} with modifications; it is treated as a subscription
+ journal for distribution. (The name \Memos\ is the formal title of
+ the publication, and each individual issue is referred to in the
+ singular form.)
+\end{itemize}
+
+\newpage
+
+The four variations of the Handbook are launched by separate ``driver''
+files, each of which contains only the few instructions necessary to
+set the scene:
+\begin{trivlist}
+\item\relax
+\leftskip=2\normalparindent
+\verb+\documentclass+\\
+\verb+% [openany] %+\qquad
+ The \texttt{openany} option may be used for screen viewing.\\
+\verb+ {amsbook}+\\
+\verb+\usepackage{ahandinstr-r}+\\
+\verb+\setboolean{+\<document type>\verb+}{true}+\\
+\verb+\input{Author_Handbook_Body}+\\
+\verb+\end{document}+
+\end{trivlist}
+
+The components are described in the following sections.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{The macro package:
+ \texorpdfstring{\fn{ahandinstr-r.sty}}{ahandinstr-r.sty}}
+This collection of macros provides commands for selecting the document
+type and formatting the contents.
+
+Document type selection is controlled by two types of commands: binary
+switches (a.k.a.\ ``booleans'') and macros with arguments. The latter
+are defined based on the switches for making the desired selection, and
+in turn are most often used to select small text strings or to pull in
+subsidiary files. Here are a couple of examples, with typical uses.
+\begin{verbatim}|leftskip=2|normalbaselineskip
+\newcommand{\jmp}[3]{%
+ \ifjournal #1\fi
+ \ifmonograph #2\fi
+ \ifproceedings #3\fi
+}
+\jmp{\input J-Series}{\input M-Series}{\input PC-Series}
+
+\newcommand{\notmonograph}[1]{%
+ \ifmonograph
+ \else #1\fi
+}
+\item Do not use \textbf{author-defined macros} in author names,
+ titles, \notmonograph{abstract, }%
+ section and theorem headings, or references;
+\end{verbatim}
+Choice of a boolean or macro has been based on what seemed to be most
+robust and easy to maintain as the document was written or updated.
+
+It is also possible to tailor the output for printing or reading online.
+The default formatting option for \cls{amsbook} is \opt{openright}; that
+is, start every chapter on a right-hand page. But the resulting blank
+pages are a distraction for online reference, so \opt{openany} can be
+specified if that is the expected use. This option had already been
+applied selectively to the handbooks, to force the two-page table of
+contents onto a page span, and for all but the monographs version (which
+has a two-page introduction) to run the introduction in on the otherwise
+blank page following the contents. To permit this exception, while
+retaining the ability to follow the intended document-wide formatting,
+an internal option, \cn{if@openany}, has been added.
+
+The subject macro package has been used in compiling the present document
+in order to maintain a consistent format.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Files composing the Author Handbook complex}
+
+The four versions of the Handbook are produced by separate driver files,
+already described in the introduction, on page~\pageref{sec:intro}.
+\begin{itemize}
+\item \fn{Author\_Handbook\_Journals.tex}
+\item \fn{Author\_Handbook\_Mono.tex}
+\item \fn{Author\_Handbook\_ProcColl.tex}
+\item \fn{Author\_Handbook\_Memo.tex}
+\end{itemize}
+
+The macro package responsible for styling the contents,
+\fn{ahandinstr-r.sty}\,, has also been described above.
+
+A single file, \fn{Author\_Handbook\_Body.tex}, contains the main content;
+see page~\pageref{sec:body}.
+
+One version of the Handbook covers only a single publication, \Memos;
+the coverage of the other three is provided as three separate lists,
+each in its own file to permit easy updates:
+\begin{itemize}
+\item \fn{J-Series.tex}
+\item \fn{M-Series.tex}
+\item \fn{PC-Series.tex}
+\end{itemize}
+
+Each version of the Handbook contains a list of requirements tailored
+for the specific type of publication:
+\begin{itemize}
+\item \fn{J-Checklist.tex}
+\item \fn{M-Checklist.tex}
+\item \fn{PC-Checklist.tex}
+\item \fn{Mem-Checklist.tex}
+\end{itemize}
+Since many checklist items are identical in more than one version, they
+are defined as token strings. A name is assigned to each token string
+by the \cn{newtoks} command, in the macro file. The (variant) texts are
+defined in the body, just before the section in which each is to be used;
+only the token string name appears in the input text.
+
+The content of a publication's top matter differs by publication type,
+so the details are provided in separate files:
+\begin{itemize}
+\item \fn{TopMatterTags\_J.tex}
+\item \fn{TopMatterTags\_M.tex}
+\item \fn{TopMatterTags\_PC.tex}
+\item \fn{TopMatterTags\_Mem.tex}
+\end{itemize}
+
+The requirements for graphics are common to all types of publications,
+but a different author is responsible for this material, so the text
+is in a file by itself. Several illustrations are present as \fn{.eps}
+files, with equivalent \fn{.pdf} versions.
+\begin{itemize}
+\item \fn{Graphics\_Guidelines.tex}
+\item \fn{Color2Gray.eps} / \fn{Color2Gray.pdf}
+\item \fn{gamuts.eps} / \fn{gamuts.pdf}
+\item \fn{rgb-cmyk.eps} / \fn{rgb-cmyk.pdf}
+\item \fn{spectrum.eps} / \fn{spectrum.pdf}
+\end{itemize}
+
+Finally, two chapters dealing with procedures and the bibliography
+complete the collection. That they are in separate files is an
+accident of history.
+\begin{itemize}
+\item \fn{Submitting2AMS.tex}
+\item \fn{ResourcesHelp.tex}
+\item \fn{AH\_Bibliography.tex}
+\end{itemize}
+
+Total distinct files in the collection making up the Handbooks: 29.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{The main text file:
+\texorpdfstring{\fn{Author\_Handbook\_Body.tex}}{Author\_Handbook\_Body.tex}}
+\label{sec:body}
+
+This file contains the bulk of the text.
+
+If a difference between versions is small (e.g., a few words), or can
+be represented by a compact instruction (e.g.,
+\verb+\input{+\<file name>\verb+}+, a macro with arguments denoting the
+requisite version(s) is used.
+
+If the difference is extensive---more than one paragraph is changed or
+variations are nested---the boolean \cn{if} commands are used directly.
+
+An effort has been made to avoid repetition, sometimes at the cost of
+input coding that is more complex than desirable. The reason for this
+choice is the high probability that duplicated content could be
+overlooked when updates are made. In the case of an instruction manual,
+this can affect a large number of users and result in unnecessary
+questions, whereas getting the input coding right usually depends on
+only one person or a small group.
+
+Rather than showing involved examples here, it is more instructive to
+look at the actual files. Some examples of varying complexity can be
+found following these lines: \verb+\chapter{Introduction}+ and
+\verb+\subsection{indexing}+.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Rationale for determining segmentation}
+
+As hinted at earlier, the decision to include material in a single file
+or multiple files is based on several factors.
+
+For the project described here, the use of several independent driver
+files makes it possible to preserve the output for all versions while
+working on only one of them. It also makes identification of the
+different versions straightforward, since the appropriate version name
+is permanantly associated with each.
+
+Segregation of project-specific macros in a dedicated style file
+(loaded with \cn{usepackage}) brings such benefits as the ability to
+use ``internal'' control sequence names without having to bother with
+\cn{makeatletter} and the like.
+
+Development and maintenance of the content can easily be divided among
+multiple authors if it is possible to \cn{input} or \cn{include} it.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Environmental considerations affecting this document}
+
+The AMS production environment in great measure affects what is described
+in the Handbooks, and indeed in the present document as well. The AMS
+published more than 60,000 pages in 2016 from \LaTeX\ input. To support
+an operation of this size, automation and consistency of input are key
+considerations.
+
+The principal engine used for AMS production is \textsf{pdflatex}, with
+\fn{dvi} output for print and \fn{pdf} output for online posting. This
+supports the essential requirements that line and page breaks must be
+identical in the two forms of a paper or book, and also that hyperlinks
+must be accurately placed in the electronic version.
+
+A third requirement is the ability to perform automated checking of
+graphics, which are becoming increasingly common in mathematical
+publications. This is, so far, all but impossible once a document is in
+pdf form; as a former member of the AMS technical support group once put
+it, ``In a \fn{pdf} file, everything is just hamburger.'' A line in a
+graph is no longer distinguishable from many other features in the file,
+and it is not always possible even to isolate the content of a graphic
+from the surrounding text. A graphic in a separate file, along with the
+sizing information in the \fn{dvi} file, can be processed by a script to
+determine (among other things) line thickness (color-adjusted if
+necessary), font size, and color usage (RGB vs.\ CMYK), and only those
+graphics containing a questionable element are flagged for review by a
+human.
+
+Another production decision of long standing is to use the Computer
+Modern fonts. Again, there are exceptions, but they must be given
+special handling; processing of documents using the STIX fonts will
+require the use of \XeTeX, and the infrastructure necessary for that
+change is being developed. (\textsf{LuaLaTeX} has, until recently, been
+too unstable to consider for production use; even now, consistency and
+backward compatibility are not guaranteed, but the time may have come to
+study the possibility.)
+
+Bibliography processing is supported only for \BibTeX\ and \pkg{amsrefs};
+for journals and proceedings papers, bibliography input is normalized to
+\pkg{amsrefs}, drawing ``standard'' coding and content from the
+MathSciNet database. \pkg{amsrefs} was developed and adopted as an
+alternative to \BibTeX\ before the creation of \pkg{biblatex}, and the
+(rather extensive) effort to provide support for \pkg{biblatex} was
+therefore never undertaken.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{Reporting problems}
+
+Inaccuracies or other problems in either this overview or in the various
+files that make up the Handbook complex can be reported to the AMS
+technical support group by email, to \texttt{tech-support@ams.org}\,.
+Please specify ``Author Handbook'' as the subject. Suggestions for
+improvement are welcome as well.
+
+\end{document}