 |
 |
 |
Writing LaTeX for multiple output formats |  |
 |
|
|
|
|
Writing LaTeX for multiple output formats | |
|
|
We have tested only the article format. A fontsize of 12pt on A4 paper should be specified. This is the largest font size available in standard LaTeX and the smallest considered to be appropriate for a clear print format by the RNIB [1]. Using a clear print format will ensure your base document format can be immediately accessed by more people. This is particularly important when producing a PDF containing — the reader will not be able to change the font and equations will not be reflowed with the text if the font size is increased. The RNIB also recommends that the text layout be simple and clear hence text should be presented in one column only.
\documentclass[12pt,a4paper,onecolumn]{article}
The following packages and commands can or must be used:
%All changes to page geometry must be via the geometry package.
\usepackage[a4paper]{geometry} %Required
\usepackage[english]{babel} %Required
\usepackage[OT1]{fontenc} %Required
\usepackage[intlimits]{amsmath} %Required if using amsmath
\usepackage{amssymb} %Required if using amssymb
\usepackage{amsfonts} %Required if using amsfonts
\usepackage[mathscr]{eucal} %Required if using eucal
\usepackage{eufrak} %Required if using eufrak
\usepackage{amsthm} %Required if typesetting theorems etc.
\usepackage{longtable} %Required if using tables with headings
\usepackage{graphicx} %Required if including images
\usepackage{verbatim} %Required if including verbatim text
\usepackage{url} %Required if including urls
\let\columnlines\empty %Required (transformation to Word format)
%All theorem-like entities should use a newtheorem-like structure,
%do not use {\bf Theorem} etc. as the structure is lost.
%Currently the transformation via plastex does not retain numbering,
%this will be fixed in the future.
\newtheorem{theorem}{Theorem}[section]
\newtheorem{corollary}[theorem]{Corollary}
%Theorem styles can be used but in large print will be redefined.
\theoremstyle{definition}
\newtheorem{definition}{Definition}[section]
\theoremstyle{remark}
%Unnumbered theorem environments may be used
\newtheorem*{note}{Note}
%All newenvironments should be produced using the newenvironment tool
\newenvironment{Proof}{\noindent{\bf Proof.}\hspace*{1em}}{\qed\par}
%All definitions must be via newcommand or renewcommand to ensure that
%previous definition is not overridden. Do not use declaremathoperator
%or def. All definitions which include superscripts or subscripts
%will need to be copied into tex4ht configuration file for the document.
%Do not use newcommand to produce macros for begin and end environments.
\newcommand{\xsb}{x_{1}}
\newcommand{\xsp}{x^{2}}
\newcommand{\xsbnum}[1]{x_{#1}}
\newcommand{\boo}{\mathrm{boo}}
\newcommand{\End}{\mathrm{End}}
%Required to ensure that the theorem numbering is correct after plastex
%transformation. As well as this the equation numbering needs to be set
%back to 0 at the start of every section and subsection including
%numbered equations. Numbering should not be reset apart from this.
%\nonumber can be used, \tag and \notag cannot be
\numberwithin{equation}{subsection}
\newif\ifplastex %Required
\plastexfalse %Required
\newif\iftht %Required
\thtfalse %Required
\newif\ifLP %Required
\LPfalse %Required
\ifLP %Required
%Reflow cannot occur within a root symbol in large print PDF so the
%root symbol is transformed to other notation
\renewcommand{\sqrt}[2][2]
{\left( #2 \right)^{\frac{1}{#1}}}
\fi
\newcommand{\nextalt}[1]{} %Required for alt tags
\newcommand{\PICalt}[1]{{#1}} %Required for alt tags
%Required for basic commuting diagrams, please note that labelled
%diagonal arrows are not currently possible.
%\tab must be used inside commuting diagrams instead of &
\newcommand{\mapright}[1]
{{\stackrel{#1}{\longrightarrow}}}
\newcommand{\mapdown}[1]
{\Big\downarrow{\scriptstyle{#1}}}
\newcommand{\tab}{&}
\allowdisplaybreaks %Required
The introduction of any other packages may cause any or all of the transformations to fail even if no commands from the package are used! Examples of this were found when assessing the legacy documents but will not be documented here. If you introduce any other package you will need to test all the output formats accordingly.
Other RNIB guidelines include:
The font you choose should be clear, avoiding anything stylised.
All body text should be left aligned.
Use bold sparingly, only highlight a few words rather than a paragraph.
Don’t use blocks of capitalised letters, and try not to use any italics or underlining.
All text should be the same orientation on the page.
The following sequence of commands will switch the global document font, remove indents (using whitespace between paragraphs instead), redefine \emph to use bold for emphasis instead of italics and establish basic document information which will assist students with difficulties accessing text to quickly establish whether this is the document for which they are looking.
\setlength{\parindent}{0.0pt}
\setlength{\parskip}{1.0\baselineskip}
\renewcommand{\emph}{\textbf}
%Required for identifying documents
%date should be hardcoded as future versions with identical
%content may be compiled on a different date or student might
%be provided with the LaTeX file
\title{Writing \LaTeX~ for multiple output formats}
\author{Emma Cliffe}
\date{May 2012}
%Helps with navigation, if you use this you must supply short
%forms of section titles (~4 words max) if they are long.
\pagestyle{headings}
%To ensure that the page numbering of the front matter and
%the main content (after the contents page) is distinct.
\pagenumbering{roman}
\begin{document}
\ifplastex
\else \iftht
\else
\renewcommand{\familydefault}{phv}
\fontfamily{phv}\selectfont
\fi \fi
\maketitle %Required for identifying documents
The last line in the file must be
\end{document}
Content after this point can interfere with some transformation processes.
Finally, when writing your LaTeX file it is important to recall that two of the transformation formats involve a student having direct access to the LaTeX source itself. It is advisable that you only include what you wish to be read so either avoid comments or using a tools to strip comments out to create a clean version is recommended.
This structure of document and all advice is given in the context of compiling to PDF using pdflatex, that is, straight to pdf without using DVI or postscript as an intermediate format. This method of compiling means that packages which work only with postscript will not function. However, in all cases considered documents making use of such packages will not transform anyway. Specific advice on using images in this context is given elsewhere in the document.
The transformations will not be covered in this document, please see the separate document on the main project page.
It is more important to remember that what you are writing will be transformed. Most authors use LaTeX to produce PDF or hard-copy documents. Most authors will compile a document as they write to see precisely how it is formatted and make adjustments by hand — treating LaTeX as a strict typesetting tool. The act of transforming the LaTeX can destroy or alter much of the formatting and layout (consider a version delivered only in speech, or a format in a 20pt font size for instance).
Ideally, of course, you should proofread all output formats in use — and if the format supports speech then you should in addition proofread the speech output. However, practically speaking it is admitted that this is likely to be very time-consuming. Student feedback acknowledges this but recommends that at least a subset of the documents you produce are proofread in all formats. Authors are likely to find this a useful exercise as it can assist in the transition of mindset from using LaTeX to typeset an inflexible document to using it primarily to encode content and describe structure.
Having ensured that only the packages, structures and symbols described in this document are used, errors with transformations when given a LaTeX document which compiles can still occur. The most common errors when performing the transformations, come from instances where LaTeX is, arguably, more permissive than expected or welcome. To avoid these problems ensure that following:
Brackets of all kinds must match and must match within their immediate context. If you require an unmatched bracket then use a construct such as \left\{ ... \right.. Braces, that is {...} within the text must always match. A context is, for instance, an environment, a box, inside braces or between ampersands. All cases of mismatching brackets in the legacy documents where
Not intended e.g. x^{(n+1});
in output from a LaTeX editor e.g. $x \text{(from above}$) or
within display math environments and matching across ampersands.
It can help to use an editor which bracket matches or a piece of bracket matching software such as those available on CTAN1.
Typos when creating subscripts and superscripts such as Z{_{(1)}}^{T}.
Other similar ordering typos such as
\underset{}{\underset{\theta }{\min } SS(\theta )}
where LaTeX will silently do something but probably not what was intended.
The inclusion of tabular-like environments inside math modes (use array!).
The redefining of environment begin and end declarations using macros (this is strongly advised against in standard LaTeX).
The redefinition of short LaTeX macros such as \a (use of newcommand ensures this is checked for). Note the following from [2]: "Many one letter sequences have predefined meanings and thus cause conflicts if you try to use them for your own macros. Most of these one-letter macros are part of the TeX core, and usually not documented in LaTeX books. Thus, if a macro isn’t listed in the index of a LaTeX book, it doesn’t mean that it is not in use. To be certain that a macro isn’t in use, you would have to check the original Knuth TeXbook, in addition to a comprehensive LaTeX reference."
Attempts to change the font size or attributes for the verbatim environments (e.g. enclosing the verbatim environment inside a small environment). Note that global font changes are fine and this document specifies how to produce them.
Ending an equation environment (either internal or external to the environment) with a \\ (though, note below that use of \\ can also cause layout problems on successful transformations).
Footnotes
|
|
|
Writing LaTeX for multiple output formats | |
|
|