diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-wdidt.tex')
| -rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/faq-wdidt.tex | 230 |
1 files changed, 188 insertions, 42 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-wdidt.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-wdidt.tex index 97ab75e31a9..c6cdd8e95e8 100644 --- a/Master/texmf-dist/doc/generic/FAQ-en/faq-wdidt.tex +++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-wdidt.tex @@ -1,4 +1,4 @@ -% $Id: faq-wdidt.tex,v 1.23 2012/11/24 10:56:03 rf10 Exp $ +% $Id: faq-wdidt.tex,v 1.24 2014/01/22 17:29:03 rf10 Exp $ \section{Why does it \emph{do} that?} @@ -141,14 +141,21 @@ chance. For example: \verb+\error+ \end{verbatim} \end{quote} -will work (typesetting `\csx{error}'), but +will work (typesetting `\csx{error}'), but if we define no more than a +no-op macro, \begin{quote} \begin{verbatim} \newcommand{\unbrace}[1]{#1} +\end{verbatim} +\end{quote} +which simply regurgitates its argument, and use it as: +\begin{quote} +\begin{verbatim} \unbrace{\verb+\error+} \end{verbatim} \end{quote} -will not (it will attempt to execute \csx{error}). Other errors one +the combinartion will not (it will attempt to execute \csx{error}). +Other errors one may encounter are `\csx{verb} ended by end of line', or even the rather more helpful `\csx{verb} illegal in command argument'. The same sorts of thing happen with \cmdinvoke{begin}{verbatim} \dots{} @@ -192,7 +199,7 @@ necessary?''. ``\Qref*{typesetting \acro{URL}s}{Q-setURL}'' offers advice here. \item If you're putting \csx{verb} into the argument of a boxing command (such as \csx{fbox}), consider using the \environment{lrbox} - environmen)t: + environment: \begin{quote} \begin{verbatim} \newsavebox{\mybox} @@ -214,9 +221,8 @@ medium of prefixing the macro with \csx{cprotect}: \cprotect\section{Using \verb|verbatim|} \end{verbatim} \end{quote} -The package (at the time this author tested it) was still under -development (though it \emph{does} work in this simple case) and -deserves consideration in most cases; the package documentation gives +The package \emph{does} work in this simple case, and deserves +consideration in many others cases; the package documentation gives more details. Another way out is to use one of ``argument types'' of the @@ -240,7 +246,7 @@ argument sequence of an otherwise ``normal'' sort of command; that `\texttt{\char`\|}' \end{typesetversion} \begin{htmlversion} - `\texttt{|}' + `\texttt{|}' % | balance for emacs text-colouring \end{htmlversion} may be any old character that doesn't conflict with the content of the argument. @@ -250,7 +256,7 @@ own) but the downside is that \Package{xparse} pulls in the experimental \latex{}3 programming environment (\Package{l3kernel}) which is pretty big. -Other than the \Package{cprotect} package, there are three partial +Other than the \Package{cprotect} package, there are four partial solutions to the problem: \begin{itemize} \item Some packages have macros which are designed to be responsive @@ -273,7 +279,23 @@ solutions to the problem: Rather simpler is the \Package{verbdef} package, whose \csx{verbdef} command defines a (robust) command which expands to the verbatim - argument given. + argument given; the \Package{newverbs} package provides a similar + function as well as several related ones. +\item In a similar vein, the \Package{verbatimbox} package makes it + possible to put verbatim material in a box: + \begin{quote} +\begin{verbatim} +\begin{verbbox} +some exotic _&$ stuff +\end{verbbox} +\theverbbox +\end{verbatim} + \end{quote} + the operation typesets exotic stuff into an anonymous box, and its + contents may be retrieved using the command \csx{theverbbox}. It is + clear that it's in the same mould as the \csx{verbdef} command + mentioned above; the package defines other similar commands. +\item The \Package{tcolorbox} package provides a similar facility \item If you have a single character that is giving trouble (in its absence you could simply use \csx{texttt}), consider using \csx{string}. \cmdinvoke{texttt}{my\csx{string}\_name} @@ -296,17 +318,56 @@ solutions to the problem: troublesome character (though it's plainly not necessary for things like percent signs for which \AllTeX{} already provides robust macros). + +\item One may also consider putting verbatim material in an external + file; this is somewhat more tedious, but the file may be reused + several times within a single document. The \Package{tcolorbox} + permits this: +\begin{quote} +\begin{verbatim} +\begin{tcbverbatimwrite}{<file name>} +... +\end{tcbverbatimwrite} +\end{verbatim} +\end{quote} + which (as one might guess) writes to the named file; load the saved + contents using \cmdinvoke{input}{<file name>} + + A second environment puts your verbatim material in an (apparently) + anonymous temporary file: +\begin{quote} +\begin{verbatim} +\begin{tcbwritetemp}{<file name>} +... +\end{tcbverbatimwrite} +\end{verbatim} +\end{quote} + In this case, you use the anonymous file with the \csx{tcbusetemp} + macro. (You can change the name used for the `anonymous' file, if + its default proves troublesome.) + + The \Package{moreverb} package provides a \csx{verbatimwrite} + command, which doesn't provide an anonynous file. + + Macros, to achieve the same effect, are outlined in the + documentation of the \Package{verbatim} package; the macros use the + facilities of the package, but the user has to write a mini-package + actually to use them. \end{itemize} \begin{ctanrefs} \item[cprotect.sty]\CTANref{cprotect} \item[fancyvrb.sty]\CTANref{fancyvrb} \item[l3kernel \nothtml{\rmfamily}bundle]\CTANref{l3kernel} \item[memoir.cls]\CTANref{memoir} +\item[newverbs.sty]\CTANref{newverbs} +\item[tcolorbox.sty]\CTANref{tcolorbox} \item[url.sty]\CTANref{url} +\item[verbatim.sty]\CTANref{verbatim} +\item[verbatimbox.sty]\CTANref{verbatimbox} \item[verbdef.sty]\CTANref{verbdef} \item[xparse.sty]Distributed as part of \CTANref{l3packages}[xparse] \end{ctanrefs} -\LastEdit{2013-02-15} +\LastEdit{2013-10-21} \Question[Q-noline]{``No line here to end''} @@ -328,10 +389,11 @@ See the LaTeX manual or LaTeX Companion \end{verbatim} \end{narrowversion} \end{quote} -comes in reaction to you giving \LaTeX{} a \texttt{\bsbs } command at a time -when it's not expecting it. The commonest case is where you've -decided you want the label of a list item to be on a line of its own, -so you've written (for example): +appears when you give \LaTeX{} a \texttt{\bsbs } command at a time +when it's not expecting it; it is a \emph{line-breaking} command, and +is confused if \latex{} isn't building a paragraph when you give the +command. A common case is where you've decided you want the label of +a list item to be on a line of its own, and written (for example): \begin{quote} \begin{verbatim} \begin{description} @@ -341,14 +403,14 @@ so you've written (for example): \end{verbatim} \end{quote} % ridiculous coding for sanitize.pl -- careful! -\bsbs {} is actually a rather bad command to use in this case (even if -it worked), since it would force the `paragraph' that's made up of the -text of the item to terminate a line which has nothing on it but the -label. This would lead to an ``\texttt{Underfull }\csx{hbox}'' warning message -(usually with `infinite' badness of 10000); while this message doesn't -do any actual harm other than slowing down your \LaTeX{} run, any -message that doesn't convey any information distracts for no useful -purpose. +% \bsbs {} is actually a rather bad command to use in this case (even if +% it worked), since it could force the `paragraph' that's made up of the +% text of the item to terminate a line which has nothing on it but the +% label. This could lead to an ``\texttt{Underfull }\csx{hbox}'' warning message +% (usually with `infinite' badness of 10000); while this message doesn't +% do any actual harm other than slowing down your \LaTeX{} run, any +% message that doesn't convey any information distracts for no useful +% purpose. The proper solution to the problem is to write a new sort of \environment{description} environment, that does just what you're after. (The @@ -356,16 +418,16 @@ The proper solution to the problem is to write a new sort of \Qref[question]{\emph{\LaTeX{} Companion}}{Q-latex-books}\nothtml{~---} offers a rather wide selection of variants of these things.) -The quick-and-easy solution, which avoids the warning, is to write: +A straightforward solution, which avoids the warning, is to write: \begin{quote} \begin{verbatim} \begin{description} -\item[Very long label] \hspace*{\fill} \\ +\item[Very long label] \leavevmode \\ Text... \end{description} \end{verbatim} \end{quote} -which fills out the under-full line before forcing its closure. The +which starts a paragraph before forcing a break. The \Package{expdlist} package provides the same functionality with its \csx{breaklabel} command, and \Package{mdwlist} provides it via its \csx{desclabelstyle} command. @@ -396,11 +458,24 @@ be had by saying: \end{center} \end{verbatim} \end{quote} + +You \emph{can} use \csx{leavevmode}, as above: +\begin{quote} +\begin{verbatim} +\begin{center} + First (heading) line\\ + \leavevmode\\ + body of the centred text... +\end{center} +\end{verbatim} +\end{quote} +but that is just as tiresome to type as \texttt{\bsbs } with an optional +argument, and can not be recommended. \begin{ctanrefs} \item[expdlist.sty]\CTANref{expdlist} \item[mdwlist.sty]Distributed as part of \CTANref{mdwtools}[mdwlist] \end{ctanrefs} -\LastEdit{2011-06-01} +\LastEdit{2014-01-13} % other instances: \[no]linebreak in vertical mode @@ -462,6 +537,42 @@ not work with obsolete (pre-\LaTeXe{}) packages such as genesis of \csx{includegraphics}. \LastEdit{2012-11-16} +\Question[Q-centre-flt]{Why is my table/figure/\dots{} not centred?} + +You want a float whose contents are centred, but \latex{} ignores your +\environment{center} environment. Most likely, you have written: +\begin{quote} +\begin{verbatim} +\begin{center} + \begin{figure} + ... + \end{figure} +\end{center} +\end{verbatim} +\end{quote} +In this case, \latex{} has ``taken the \environment{figure} away'', +and will typeset it at some location it fancies (it does the same with +\environment{table}s) the only thing we can say (for sure) about the +location is that it \emph{won't} be inside that \environment{center} +environment. As a result, the \environment{center} environment is +left with nothing to do~\dots{} except to % !line break +\Qref*{make a mess of your vertical spacing}{Q-vertspacefloat}. + +The solution is the same as that outlined in % !line break +\Qref*{the same answer}{Q-vertspacefloat}, noting that all control of +an \environment{figure} or \environment{table} needs to be +inside the environment. So the example's code should be converted to +\begin{quote} +\begin{verbatim} +\begin{figure} + \centering + ... +\end{figure} +\end{verbatim} +\end{quote} +(or something similar for a \environment{table}). +\LastEdit*{2013-11-19} + \Question[Q-2colfltorder]{Two-column float numbers out of order} When \LaTeX{} can't place a float immediately, it places it on one of @@ -1197,21 +1308,27 @@ way \TeX{} works, and Lamport describes a solution (place a pair of braces after a command's invocation) in the description of \LaTeX{} syntax. Thus the requirement is in effect part of the definition of \LaTeX{}. -This \acro{FAQ}, -for example, is written with definitions that \emph{require} one to -type \cmdinvoke{fred}{\relax} % the \relax prevents {} being gobbled - % in html production (sigh) +These \acro{FAQ}s, +for example, is written in \latex{} for production of a web site. The +HTML code is generated by a script that \emph{requires} a pair of +braces, to make a null argument, as in: +\begin{quote} + \cmdinvoke{fred}{\relax} % the \relax prevents {} being gobbled + % in html production (sigh) + % (we needn't tell them about _that_ ;-) +\end{quote} for almost all macro invocations, regardless -of whether the following space is required: however, this \acro{FAQ} -is written by highly dedicated (and, some would say, eccentric) -people. Many users find all those braces become very tedious very +of whether the following space is required: however, these \acro{FAQ}s +should not itself be regarded as a model of \latex{} style. + +Many users find all those braces become very tedious very quickly, and would really rather not type them all. An alternative structure, that doesn't violate the design of \LaTeX{}, is to say \csx{fred}\csx{ }~--- the \csx{ } command is ``self terminating'' (like \texttt{\bsbs }) and you don't need braces after -\emph{it}. Thus one can reduce to one the extra characters one needs -to type. +\emph{it}. Thus one can reduce to one the number of extra characters +one needs to type. If even that one character is too many, the package \Package{xspace} defines a command \csx{xspace} that guesses whether there should have @@ -1246,16 +1363,22 @@ The \csx{xspace} command must be the last thing in your macro definition (as in the example); it's not completely foolproof, but it copes with most obvious situations in running text. -The \Package{xspace} package doesn't save you anything if you only use -a modified macro once or twice within your document. In any case, be +The \Package{xspace} package doesn't save you anything if you use it in +a macro that appears only once or twice within your document, and it +is not totally foolproof. (The original author of the package wrote +it because he had been bitten by lost spaces. He no longer recommends +its use, simply because of the possibility of error.) + +In any case, be careful with usage of \csx{xspace}~--- it changes your input syntax, which can be confusing, notably to a collaborating author (particularly if you create some commands which use it and some which -don't). Of course, no command built into \LaTeX{} or into any +don't). No command built into \LaTeX{} or into any ``standard'' class or package will use \csx{xspace}. \begin{ctanrefs} \item[xspace.sty]Distributed as part of \CTANref{2etools}[xspace] \end{ctanrefs} +\LastEdit{2013-11-26} \Question[Q-overfull]{\AllTeX{} makes overfull lines} @@ -1541,7 +1664,7 @@ problem by ending the initial paragraph before starting the comment: \begin{verbatim} Paragraph text ... ... paragraph body ends. -\par\noindent +\par\nothtml{\noindent} {\footnotesize Comment on the paragraph.} Next paragraph starts... @@ -1571,6 +1694,7 @@ Main body of text... \Question[Q-tocloftwrong]{Numbers too large in table of contents, etc.} +\keywords{memoir table-of-contents spacing} \LaTeX{} constructs the table of contents, list of figures, tables, and similar tables, on the basis of a layout specified in the class. As a result, they do \emph{not} react to the sizes of things in them, @@ -1584,7 +1708,29 @@ fit in the space allowed for them in the class. A separate answer discusses % ! line break \nothtml{re-designing the tables ---} % ! line break \Qref{re-designing the tables}{Q-tocloft}\nothtml{ ---} -and those techniques can be employed to make the numbers fit. +and techniques from that answer may be employed to make the numbers +fit: +\begin{quote} +\begin{verbatim} +\setlength\cftsectionnumwidth{4em} +\end{verbatim} +\end{quote} + +The same command may be employed in documents typeset with the +\Class{memoir} package (by the same author as \Package{tocloft}). + +\Class{Memoir} has another mechanism for the job: +\cmdinvoke{cftsetindents}{\meta{kind}}{indent}{numwidth}. Here +\emph{kind} is \texttt{chapter}, \texttt{section}, or whatever; the +\emph{indent} specifies the `margin' before the entry starts; and the +\emph{width} is of the box into which the number is typeset (so needs +to be wide enough for the largest number, with the necessary spacing +to separate it from what comes after it in the line. +\begin{ctanrefs} +\item[memoir.cls]\CTANref{memoir} +\item[tocloft.sty]\CTANref{tocloft} +\end{ctanrefs} +\LastEdit{2013-08-20} \Question[Q-gutter]{Why is the inside margin so narrow?} @@ -1786,7 +1932,7 @@ The font-selection commands of \LaTeXo{} were \csx{rm}, \csx{sf}, commands, so you used them as: \begin{quote} \begin{verbatim} -{\bf Fred} was {\it here\/}}. +{\bf Fred} was {\it here\/}. \end{verbatim} \end{quote} with the font change enclosed in a group, so as to limit its effect; |