summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-bits+pieces.tex
diff options
context:
space:
mode:
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.tex74
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?}