summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex')
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex128
1 files changed, 80 insertions, 48 deletions
diff --git a/Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex b/Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex
index 1dc4ea129a9..cf9d73698e8 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex
+++ b/Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex
@@ -1,11 +1,11 @@
%%% ====================================================================
%%% @LaTeX-file{
%%% author = "Scott Pakin",
-%%% version = "2.0a",
-%%% date = "05 November 2004",
-%%% time = "01:36:46 MST",
+%%% version = "2.1",
+%%% date = "13 September 2015",
+%%% time = "23:06:32 MDT",
%%% filename = "dtxtut.tex",
-%%% checksum = "54933 2075 7618 70409"
+%%% checksum = "38789 2107 7734 71546"
%%% email = "scott+dtx@pakin.org (Internet)",
%%% codetable = "ISO/ASCII",
%%% keywords = "LaTeX, packages, .ins files, .dtx files,
@@ -33,14 +33,26 @@
\usepackage{varioref}
\usepackage{makeidx}
\usepackage{alltt}
-\IfFileExists{tocbibind.sty}{\usepackage{tocbibind}}{}
-\IfFileExists{hyperref.sty}{\usepackage[bookmarksopen]{hyperref}}{}
+\usepackage{tocbibind}
+\usepackage[bookmarksopen]{hyperref}
+\usepackage{hyperxmp}
+% Define this document's metadata.
\title{How to Package Your \LaTeX{} Package}
\author{Scott Pakin \texttt{<scott+dtx@pakin.org>}}
-\date{5 November 2004}
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\date{13 September 2015}
+\hypersetup{%
+ pdftitle={How to Package Your LaTeX Package},
+ pdfauthor={Scott Pakin},
+ pdfcontactemail={scott+dtx@pakin.org},
+ pdfcontacturl={http://www.pakin.org/\xmptilde scott},
+ pdfsubject={Writing .ins and .dtx files for LaTeX},
+ pdfkeywords={LaTeX package documentation, literate programming, typesetting, installer files},
+ pdfcaptionwriter={Scott Pakin},
+ pdfcopyright={Copyright (C) 2015 Scott Pakin},
+ pdflicenseurl={http://latex-project.org/lppl/},
+ pdflang={en-US}
+}
% Define a term.
\newcommand{\defn}[2][X]{%
@@ -224,13 +236,13 @@ specifying the copyright\index{copyright} and license information:
%%
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
- %% version 1.2 of this license or (at your option) any later
+ %% version 1.3 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.2 or later is part of all distributions of
- %% LaTeX version 1999/12/01 or later.
+ %% and version 1.3 or later is part of all distributions of
+ %% LaTeX version 2005/12/01 or later.
%%
\end{verbatim}
@@ -314,13 +326,13 @@ commentary that will be written to the top of every generated file:
This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
- version 1.2 of this license or (at your option) any later
+ version 1.3 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.2 or later is part of all distributions of
- LaTeX version 1999/12/01 or later.
+ and version 1.3 or later is part of all distributions of
+ LaTeX version 2005/12/01 or later.
\endpreamble
\end{verbatim}
@@ -346,13 +358,13 @@ to begin as follows:
%%
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
- %% version 1.2 of this license or (at your option) any later
+ %% version 1.3 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.2 or later is part of all distributions of
- %% LaTeX version 1999/12/01 or later.
+ %% and version 1.3 or later is part of all distributions of
+ %% LaTeX version 2005/12/01 or later.
%%
\end{verbatim}
@@ -486,13 +498,13 @@ license\index{license} comment:
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
- % version 1.2 of this license or (at your option) any later
+ % version 1.3 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.2 or later is part of all distributions of
- % LaTeX version 1999/12/01 or later.
+ % and version 1.3 or later is part of all distributions of
+ % LaTeX version 2005/12/01 or later.
%
% \fi
\end{verbatim}
@@ -527,7 +539,7 @@ intended not for a human reader, but for \ds{} (hence, no
\label{code:ProvidesPackage}
\begin{verbatim}
% \iffalse
- %<<package>>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+ %<<package>>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<<package>>\ProvidesPackage{<package>}
%<<package>> [<YYYY>/<MM>/<DD> v<version> <description>]
%
@@ -545,7 +557,7 @@ the \styfile{} file, stripping off the ``|%<<package>>|'' in the
process. Hence, our \styfile{} file will begin with the following:
\begin{verbatim}
- \NeedsTeXFormat{LaTeX2e}[1999/12/01]
+ \NeedsTeXFormat{LaTeX2e}[2005/12/01]
\ProvidesPackage{<package>}
[<YYYY>/<MM>/<DD> v<version> <description>]
\end{verbatim}%
@@ -556,7 +568,7 @@ process. Hence, our \styfile{} file will begin with the following:
For example:
\begin{verbatim}
- \NeedsTeXFormat{LaTeX2e}[1999/12/01]
+ \NeedsTeXFormat{LaTeX2e}[2005/12/01]
\ProvidesPackage{skeleton}
[2002/03/25 v1.0 .dtx skeleton file]
\end{verbatim}%
@@ -1371,7 +1383,7 @@ problem is that \usemacro{DocInput} relies on the
\usemacro{fileversion} and \usemacro{filedate} macros. However, a
class file can't be loaded with |\usepackage|. Nor can we simply load
it with |\documentclass{|\m{package}|}| because only one class can be
-loaded per document and we need that class to be |ltxdoc|.
+loaded per document and we need that class to be \usething{ltxdoc}.
The solution is to use \usemacro{ProvidesFile} to make the file
version and date available to the \dtxfile{} file.
@@ -1481,6 +1493,11 @@ structured header section.
\item You can use \usemacro{index} in the normal way to index things
other than macros and environments.
+ \item Because macro names can be long, consider using the
+ \defthing{idxlayout} package to reduce the number of columns in
+ the index. (It provides control over other aspects of index
+ formatting, as well.)
+
\item If you use \Emacs{} as your text editor, try out \swiftexel's
|doctex-mode|\index{doctex-mode@\texttt{doctex-mode}}, an \Emacs{}
mode designed specifically for writing \dtxfile{} files.
@@ -1511,7 +1528,7 @@ structured header section.
\end{itemize}
-\section{Obscure packaging features}
+\section{Advanced packaging techniques}
This section describes various bits of wizardry that can be
accomplished with \DOC{} and \ds. Few packages require these
@@ -1572,6 +1589,7 @@ otherwise, each file will get its own index. After all of the
\index{indexing|)}
\subsection{Single-file package distributions}
+\label{sec:single-file}
Although \latex{} packages are typically distributed as both
a~\insfile{} and a \dtxfile{} file, it is possible to distribute a
@@ -1639,7 +1657,7 @@ in the \dtxfile{} file shown in
Appendix~\ref{sec:skeleton-dtx-file-class}:
\begin{verbatim}
- %<<class>>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+ %<<class>>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<<class>>\ProvidesClass{<package>}
%<<*class>>
[<YYYY>/<MM>/<DD> v<version> <brief description>]
@@ -1650,7 +1668,7 @@ The replacement code specifies which lines belong to the class file
and which belong to the style file:
\begin{verbatim}
- %<<class|package>>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+ %<<class|package>>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<<class>>\ProvidesClass{<package>}
%<<package>>\ProvidesPackage{<package>}
%<<*class|package>>
@@ -1658,6 +1676,20 @@ and which belong to the style file:
%<</class|package>>
\end{verbatim}
+\subsection{Gallery of advanced packaging techniques}
+
+See the \dtxfile\ gallery on
+\CTAN\ \URL{https://www.ctan.org/tex-archive/info/dtxgallery} for
+examples of various packaging possibilities, including the following:
+
+\begin{itemize}
+ \item single-file package distributions (cf.~Section~\ref{sec:single-file})
+
+ \item conditional code inclusion (cf.~Table~\ref{tbl:comment-visibility})
+
+ \item rearranging code for presentation in the documentation
+\end{itemize}
+
\appendix
@@ -1678,13 +1710,13 @@ templates for creating your own packages.\index{package}
%%
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
-%% version 1.2 of this license or (at your option) any later
+%% version 1.3 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.2 or later is part of all distributions of
-%% LaTeX version 1999/12/01 or later.
+%% and version 1.3 or later is part of all distributions of
+%% LaTeX version 2005/12/01 or later.
%%
\input docstrip.tex
@@ -1700,13 +1732,13 @@ Copyright (C) <year> by <your name>
This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
-version 1.2 of this license or (at your option) any later
+version 1.3 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.2 or later is part of all distributions of
-LaTeX version 1999/12/01 or later.
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
\endpreamble
@@ -1738,13 +1770,13 @@ LaTeX version 1999/12/01 or later.
%%
%% This file may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either
-%% version 1.2 of this license or (at your option) any later
+%% version 1.3 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.2 or later is part of all distributions of
-%% LaTeX version 1999/12/01 or later.
+%% and version 1.3 or later is part of all distributions of
+%% LaTeX version 2005/12/01 or later.
%%
\input docstrip.tex
@@ -1760,13 +1792,13 @@ Copyright (C) <year> by <your name>
This file may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
-version 1.2 of this license or (at your option) any later
+version 1.3 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.2 or later is part of all distributions of
-LaTeX version 1999/12/01 or later.
+and version 1.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
\endpreamble
@@ -1802,19 +1834,19 @@ LaTeX version 1999/12/01 or later.
% -----------------------------------
%
% This file may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.2
+% conditions of the LaTeX Project Public License, either version 1.3
% 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.2 or later is part of all distributions of LaTeX
-% version 1999/12/01 or later.
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
%
% \fi
%
% \iffalse
-%<<package>>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<<package>>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<<package>>\ProvidesPackage{<package>}
%<<package>> [<YYYY>/<MM>/<DD> v<version> <brief description>]
%
@@ -1911,14 +1943,14 @@ LaTeX version 1999/12/01 or later.
% -----------------------------------
%
% This file may be distributed and/or modified under the
-% conditions of the LaTeX Project Public License, either version 1.2
+% conditions of the LaTeX Project Public License, either version 1.3
% 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.2 or later is part of all distributions of LaTeX
-% version 1999/12/01 or later.
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
%
% \fi
%
@@ -1926,7 +1958,7 @@ LaTeX version 1999/12/01 or later.
%<<*driver>>
\ProvidesFile{<package>.dtx}
%<</driver>>
-%<<class>>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<<class>>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<<class>>\ProvidesClass{<package>}
%<<*class>>
[<YYYY>/<MM>/<DD> v<version> <brief description>]