dtxtut (14sep15)

git-svn-id: svn://tug.org/texlive/trunk@38375 c570f23f-e606-0410-a88d-b1316a301751

7 files changed, 111 insertions, 78 deletions

diff --git a/Master/texmf-dist/doc/latex/dtxtut/README b/Master/texmf-dist/doc/latex/dtxtut/README
index 9cb11d2d01a..70d96cbcff0 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/README
+++ b/Master/texmf-dist/doc/latex/dtxtut/README
@@ -1,8 +1,8 @@
 
-	       +-------------------------------------+
-	       |  HOW TO PACKAGE YOUR LATEX PACKAGE  |
-	       | By Scott Pakin, scott+dtx@pakin.org |
-	       +-------------------------------------+
+               +-------------------------------------+
+               |  HOW TO PACKAGE YOUR LATEX PACKAGE  |
+               | By Scott Pakin, scott+dtx@pakin.org |
+               +-------------------------------------+
 
 This tutorial is intended for advanced LaTeX2e users who want to learn
 how to create .ins and .dtx files for distributing their homebrewed
@@ -25,6 +25,7 @@ files:
 
    * Robin Fairbairns
    * Marcel Heldoorn
+   * Alex Hirzel
    * Rolf Niepraschk
    * Hans Fredrik Nordhaug
-
+   * Will Robertson
diff --git a/Master/texmf-dist/doc/latex/dtxtut/cskeleton.dtx b/Master/texmf-dist/doc/latex/dtxtut/cskeleton.dtx
index 2374838738b..dd833da90eb 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/cskeleton.dtx
+++ b/Master/texmf-dist/doc/latex/dtxtut/cskeleton.dtx
@@ -1,17 +1,17 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2004 by Scott Pakin <scott+dtx@pakin.org>
+% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org>
 % -------------------------------------------------------
 % 
 % 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
 %
diff --git a/Master/texmf-dist/doc/latex/dtxtut/cskeleton.ins b/Master/texmf-dist/doc/latex/dtxtut/cskeleton.ins
index 511fcf507dd..b99b06df691 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/cskeleton.ins
+++ b/Master/texmf-dist/doc/latex/dtxtut/cskeleton.ins
@@ -1,15 +1,15 @@
 %%
-%% Copyright (C) 2004 by Scott Pakin <scott+dtx@pakin.org>
+%% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org>
 %%
 %% This file may be distributed and/or modified under the conditions of
-%% the LaTeX Project Public License, either version 1.2 of this license
+%% 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.
 %%
 
 \input docstrip.tex
@@ -21,17 +21,17 @@
 
 This is a generated file.
 
-Copyright (C) 2004 by Scott Pakin <scott+dtx@pakin.org>
+Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org>
 
 This file may be distributed and/or modified under the conditions of
-the LaTeX Project Public License, either version 1.2 of this license
+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.
 
 \endpreamble
 
diff --git a/Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf b/Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf
index f43af2f7cb6..e6bf6c21eed 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf
+++ b/Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf
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>]
diff --git a/Master/texmf-dist/doc/latex/dtxtut/skeleton.dtx b/Master/texmf-dist/doc/latex/dtxtut/skeleton.dtx
index 6fb4374087b..83a7b52fee2 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/skeleton.dtx
+++ b/Master/texmf-dist/doc/latex/dtxtut/skeleton.dtx
@@ -1,17 +1,17 @@
 % \iffalse meta-comment
 %
-% Copyright (C) 2004 by Scott Pakin <scott+dtx@pakin.org>
+% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org>
 % -------------------------------------------------------
 % 
 % 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
 %
@@ -19,7 +19,7 @@
 %<*driver>
 \ProvidesFile{skeleton.dtx}
 %</driver>
-%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
 %<package>\ProvidesPackage{skeleton}
 %<*package>
     [2004/11/05 v1.0 .dtx skeleton file]
diff --git a/Master/texmf-dist/doc/latex/dtxtut/skeleton.ins b/Master/texmf-dist/doc/latex/dtxtut/skeleton.ins
index 14d15142be3..0f2277429bb 100644
--- a/Master/texmf-dist/doc/latex/dtxtut/skeleton.ins
+++ b/Master/texmf-dist/doc/latex/dtxtut/skeleton.ins
@@ -1,15 +1,15 @@
 %%
-%% Copyright (C) 2004 by Scott Pakin <scott+dtx@pakin.org>
+%% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org>
 %%
 %% This file may be distributed and/or modified under the conditions of
-%% the LaTeX Project Public License, either version 1.2 of this license
+%% 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.
 %%
 
 \input docstrip.tex
@@ -21,17 +21,17 @@
 
 This is a generated file.
 
-Copyright (C) 2004 by Scott Pakin <scott+dtx@pakin.org>
+Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org>
 
 This file may be distributed and/or modified under the conditions of
-the LaTeX Project Public License, either version 1.2 of this license
+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.
 
 \endpreamble