From 06ca0b68a1199a658979f91eec6aec65bca22075 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 14 Sep 2015 21:54:00 +0000 Subject: dtxtut (14sep15) git-svn-id: svn://tug.org/texlive/trunk@38375 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/dtxtut/README | 11 +- Master/texmf-dist/doc/latex/dtxtut/cskeleton.dtx | 8 +- Master/texmf-dist/doc/latex/dtxtut/cskeleton.ins | 16 +-- Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf | Bin 263687 -> 304588 bytes Master/texmf-dist/doc/latex/dtxtut/dtxtut.tex | 128 ++++++++++++++--------- Master/texmf-dist/doc/latex/dtxtut/skeleton.dtx | 10 +- Master/texmf-dist/doc/latex/dtxtut/skeleton.ins | 16 +-- 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 +% Copyright (C) 2015 by Scott Pakin % ------------------------------------------------------- % % 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 +%% Copyright (C) 2015 by Scott Pakin %% %% 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 +Copyright (C) 2015 by Scott Pakin 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 Binary files a/Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf and b/Master/texmf-dist/doc/latex/dtxtut/dtxtut.pdf 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{}} -\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 - %<>\NeedsTeXFormat{LaTeX2e}[1999/12/01] + %<>\NeedsTeXFormat{LaTeX2e}[2005/12/01] %<>\ProvidesPackage{} %<> [//
v ] % @@ -545,7 +557,7 @@ the \styfile{} file, stripping off the ``|%<>|'' 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{} [//
v ] \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} - %<>\NeedsTeXFormat{LaTeX2e}[1999/12/01] + %<>\NeedsTeXFormat{LaTeX2e}[2005/12/01] %<>\ProvidesClass{} %<<*class>> [//
v ] @@ -1650,7 +1668,7 @@ The replacement code specifies which lines belong to the class file and which belong to the style file: \begin{verbatim} - %<>\NeedsTeXFormat{LaTeX2e}[1999/12/01] + %<>\NeedsTeXFormat{LaTeX2e}[2005/12/01] %<>\ProvidesClass{} %<>\ProvidesPackage{} %<<*class|package>> @@ -1658,6 +1676,20 @@ and which belong to the style file: %<> \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) by 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) by 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 -%<>\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%<>\NeedsTeXFormat{LaTeX2e}[2005/12/01] %<>\ProvidesPackage{} %<> [//
v ] % @@ -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{.dtx} %<> -%<>\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%<>\NeedsTeXFormat{LaTeX2e}[2005/12/01] %<>\ProvidesClass{} %<<*class>> [//
v ] 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 +% Copyright (C) 2015 by Scott Pakin % ------------------------------------------------------- % % 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} % -%\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%\NeedsTeXFormat{LaTeX2e}[2005/12/01] %\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 +%% Copyright (C) 2015 by Scott Pakin %% %% 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 +Copyright (C) 2015 by Scott Pakin 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 -- cgit v1.2.3