summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/dtxtut
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-09-14 21:54:00 +0000
committerKarl Berry <karl@freefriends.org>2015-09-14 21:54:00 +0000
commit06ca0b68a1199a658979f91eec6aec65bca22075 (patch)
treeb8a5ffc9a845baa842893f8eb2854e17cd122791 /Master/texmf-dist/doc/latex/dtxtut
parentac4c34e7f36adcd9f1b3ecd0179ddbd29daafcce (diff)
dtxtut (14sep15)
git-svn-id: svn://tug.org/texlive/trunk@38375 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/dtxtut')
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/README11
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/cskeleton.dtx8
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/cskeleton.ins16
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdfbin263687 -> 304588 bytes
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex128
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/skeleton.dtx10
-rw-r--r--Master/texmf-dist/doc/latex/dtxtut/skeleton.ins16
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
Binary files differ
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