diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex | 74 |
1 files changed, 50 insertions, 24 deletions
diff --git a/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex b/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex index dc0d8788dd6..113d1139e4e 100644 --- a/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex +++ b/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex @@ -1,4 +1,4 @@ -% $Id: faq-bits+pieces.tex,v 1.31 2012/12/07 19:34:33 rf10 Exp rf10 $ +% $Id: faq-bits+pieces.tex,v 1.32 2014/01/28 18:17:36 rf10 Exp rf10 $ \section{Bits and pieces of \AllTeX{}} @@ -476,13 +476,13 @@ it is very thoroughly managed by the \Package{babel} package; use of \latex{} aims to be a general-purpose document processor. Such an aim could be achieved by a selection of instructions which would enable users to use \tex{} primitives, but such a procedure is considered too -inflexible (and probably too daunting for ordinary users), and so the +inflexible (and probably too daunting for ordinary users). Thus the designers of \latex{} created a model which offered an \emph{abstraction} of the design of documents. Obviously, not all documents can look the same (even with the defocussed eye of abstraction), so the model uses \emph{classes} of document. Base \latex{} offers five classes of document: \Class{book}, -\Class{report}, \Class{report}, \Class{article} and \Class{letter}. +\Class{report}, \Class{article} and \Class{letter}. For each class, \latex{} provides a \emph{class file}; the user arranges to use it via a \csx{documentclass} command at the top of the document. So a document starting @@ -500,17 +500,17 @@ existing class, and then does its own thing with the document design. If the user finds such a refined class, all is well, but if not, the common way is to load a \emph{package} (or several). -\latex{} provides rather few package files, but there are lots of them -to be found on the archives by a wide variety of authors; several -packages are designed just to adjust the design of a document~--- -using such packages achieves what the programmer might have achieved -by refining the class. +The \latex{} distribution, itself, provides rather few package files, +but there are lots of them, by a wide variety of authors, to be found +on the archives. Several packages are designed just to adjust the +design of a document~--- using such packages achieves what the +programmer might have achieved by refining the class. Other packages provide new facilities: for example, the -\Package{graphics} package (actually provided by the \latex{} team) -allows the user to load externally-provided graphics into a document, -and the \Package{hyperref} package enables the user to construct -hyper-references within a document. +\Package{graphics} package (actually provided as part of any \latex{} +distribution) allows the user to load externally-provided graphics +into a document, and the \Package{hyperref} package enables the user +to construct hyper-references within a document. On disc, class and package files only appear different by virtue of their name ``extension''~--- class files are called \File{*.cls} while @@ -524,6 +524,7 @@ everything was called a style (``document style'' or ``document style option''). It doesn't really matter that the nomenclature has changed: the important requirement is to understand what other people are talking about. +\LastEdit{2013-10-21} \Question[Q-whatenv]{What are \latex{} ``environments''} @@ -645,23 +646,48 @@ have to wrap it in a macro of its own: \Question[Q-dtx]{Documented \LaTeX{} sources (\extension{dtx} files)} -\LaTeXe{}, and most contributed macro packages, are now written in a -\Qref*{literate programming style}{Q-lit}, with source and +\LaTeXe{}, and many contributed \latex{} macro packages, are written +in a \Qref*{literate programming style}{Q-lit}, with source and documentation in the -same file. This format, known as `doc', in fact originated before the +same file. This format in fact originated before the days of the \LaTeX{} project as one of the ``Mainz'' series of -packages. A documented source file conventionally has the suffix +packages. A documented source file conventionally has the suffix \extension{dtx}, and will normally be `stripped' before use with -\LaTeX{}; an installation file (\extension{ins}) is normally provided, +\LaTeX{}; an installation (\extension{ins}) file is normally provided, to automate this process of removing comments for speed of loading. -To read the comments, you can run \LaTeX{} on the +If the \extension{ins} file is available, you may process \emph{it} +with \latex{} to produce the package (and, often, auxiliary files). + +Output should look something like: +\begin{quote} +\begin{verbatim} +Generating file(s) ./foo.sty + +Processing file foo.dtx (package) -> foo.sty +File foo.dtx ended by \endinput. +Lines processed: 2336 +Comments removed: 1336 +Comments passed: 2 +Codelines passed: 972 +\end{verbatim} +\end{quote} +The lines ``\texttt{Processing \dots{}\ ended by \csx{endinput}}'' may +be repeated if the \extension{dtx} file provides more than one +`unpacked' file. + +To read the comments ``as a document'', you can run \LaTeX{} on the \extension{dtx} file to produce a nicely formatted version of the -documented code. Several -packages can be included in one \extension{dtx} file (they're sorted -out by the \extension{ins} file), with conditional -sections, and there are facilities for indexes of macros, etc. +documented code. (Most \latex{} packages on \ctan{}, nowadays, already +have \acro{PDF} of the result of processing the \extension{dtx} file, +as ``documentation''.) + +Several packages may be included in one \extension{dtx} file, with +conditional sections, and there are facilities for indexes of macros, +etc. All of this m\'elange is sorted out by directives in the +\extension{ins} file; conventional indexing utilities may be necessary +for ``full'' output. -Anyone can write \extension{dtx} files; the format is explained in +Anyone may write \extension{dtx} files; the format is explained in \Qref*{The \LaTeX{} Companion}{Q-latex-books}, and a tutorial is available from \acro{CTAN} (which comes with skeleton \extension{dtx} and \extension{ins} files). @@ -714,7 +740,7 @@ thus permitting documented distribution of bundles containing code for \item[makedtx]\CTANref{makedtx} \item[sty2dtx]\CTANref{sty2dtx} \end{ctanrefs} -\LastEdit{2011-06-01} +\LastEdit{2014-06-03} \Question[Q-whatenc]{What are encodings?} |