summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/plainpkg/plainpkg-doc.tex
blob: 882dce5ac4bfa6140ff9b00c8457f8320aef3b4f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
\ProvidesFile{plainpkg-doc.tex}[2012/09/19 documenting plainpkg.tex]
\title{\pkg{\huge plainpkg}\\---\\%%%Rudimentary Package Management 
%        without \LaTeX\thanks{This document describes 
       a ``Minimal" Method\\for Making ``Generic" Packages\thanks{%
       This document describes
       \file{plainpkg.tex}'s                            %% 2012/08/24
       version~\textcolor{blue}{\UseVersionOf{plainpkg.tex}} 
       as of~\textcolor{blue}{\UseDateOf{plainpkg.tex}}.}} 
% \listfiles  %% 2012/09/16
% \RequirePackage{inputtrc}\dotracinginputs
{ \RequirePackage{makedoc} \ProcessLineMessage{}
  \renewcommand*{\mdSectionLevelOne}{\string\subsection}
  \renewcommand*{\mdJobName}{plainpkg}
  \MakeJobDoc[tex]{21}%% 2012/08/25
  {\SectionLevelTwoParseInput}  }
\documentclass[fleqn]{article}%% TODO paper dimensions!?
\input{makedoc.cfg} %% shared formatting settings
% \ReadFileInfos{plainpkg} %% 2012/09/16 Fehler, wird wohl schon 
                           %% durch fifinddo via stacklet aufgerufen.
\MDkeywords{Macro programming, package management}
\newcommand*{\plpkg}[1]{\pkg{plainpkg} #1ackage}
\newcommand*{\plpkgpkg}{\plpkg p}
\newcommand*{\Plpkgpkg}{\plpkg P}
\sloppy
\begin{document}
\maketitle
\begin{MDabstract}
'plainpkg.tex' provides some rudimentary \LaTeX-like package
management for ``generic" packages: \ 
(i)\enspace a (rather arbitrary) implementation of 
\LaTeX's `\ProvidesFile' (support for \ctanpkgref{readprov}), \
(ii)\enspace an implementation of \LaTeX's `\ProvidesPackage' 
that, in addition to (i), avoids loading twice, \ 
(iii)\enspace a simple implementation of \LaTeX's `\RequirePackage' %% P 2012/09/19
to allow nesting of package files with and without \LaTeX\ \ and \
%% <- 2012/08/25
(iv)\enspace loading 'stacklet.sty' for managing private letters 
with nested package files. \ Also, 
(v)\enspace a rather experimental `\ifltx' is provided indicating 
whether the format is \LaTeX---or \CtanPkgRef{miniltx}{miniltx.tex} 
has been loaded earlier~... \
A by-product is \ (vi)\enspace the helper `\withcsname' for 
`csname' constructs.                                                %% rm. \ 2012/09/19
%% 2012/09/19:
The documentation also introduces a notion of ``\plpkgpkg s" 
for a central explanation of how to make and work with ``generic" 
packages based on 'plainpkg'.

\MDaddtoabstract{Related Packages} 
\ctanpkgref{miniltx}, \ctanpkgref{maybeload};
\ctanpkgref{catoptions},\\\null\qquad 'pcatcode' from \ctanpkgref{amsrefs}, 
\ctanpkgref{texapi}
%% 2012/09/19:
\MDaddtoabstract{Required Packages} 'stacklet.sty' from 
\ctanpkgref{catcodes} bundle
\end{MDabstract}
% \newpage
\tableofcontents
\section{Purpose and Usage}
\label{sec:pu}
\subsection{Purpose}
'plainpkg.tex' in the first instance is a tool for \TeX\ macro packages 
to work with \LaTeX\ as well as with Plain \TeX, perhaps even with other 
\TeX\ formats. 
When \LaTeX\ seems to be missing, a definition for `\ProvidesPackage' 
is provided that avoids loading such a package a second time. 
Earlier (in the \ctanpkgref{dowith} package), I tried to ``hide" 
the `\ProvidesPackage' command when it was not defined, 
the original motive was to have that command somewhere so 
its version information can be accessed by the \ctanpkgref{readprov} package.
As such ``generic" packages often use private \LaTeX\ internals, 
I thought that 'plainpkg' also should offer a stack for handling category 
codes of `@' in nested package files. Rather than providing such a stack 
in `plainpkg.tex', I use the more general 'stacklet.sty', because I 
have used different ``private letters" in other nested package files 
that \emph{require \LaTeX}, so such stacks should be accessible 
\emph{without} 'plainpkg'.
% 
% Details, including why a mere document author should consider it, 
% are following.

\subsection{Installing: How and Why}
The file `plainpkg.tex' is provided ready, like `stacklet.sty' 
(\ctanpkgref{catcodes} bundle), installation only requires
putting both somewhere where \TeX\ finds them
(which may need updating the filename data
 base).\urlfoot{ukfaqref}{inst-wlcf} 

\subsection{Features}
\label{sec:feat}
Besides providing 'stacklet''s features---see the 'catcodes' bundle
documentation in `catcodes.pdf'---and a fallback definition 
|\ProvidesPackage| for running without \LaTeX, some |\withcsname|, 
a conditional |\ifltx| as well as 
fallback definitions for |\RequirePackage| and |\ProvidesFile| 
are provided---see implementation sections for details.

\subsection{Loading `plainpkg.tex'}
\label{sec:load}
`plainpkg.tex' may be loaded by |\input plainpkg| or---with \LaTeX---by 
|\input{plainpkg}|. However, in a document source file this is useful only 
when so-called ``weak \plpkgpkg s" according to Section~\ref{sec:plpkg} 
are loaded additionally. With \LaTeX, the only effect will be that 
`\withcsname' works and that the 'stacklet' package is loaded.
So if you just want to have the 'stacklet' functionality of support for
private letters in nested package files, you better use 
|\RequirePackage{stacklet}| or |\usepackage{stacklet}| directly. 
The latter still is a little strange---it may be helpful for private 
letters other than `@' in a \LaTeX\ document, or with ``weak 'stacklet' 
packages," a notion that I have not introduced yet.

\subsection{Notion and Usage of ``\Plpkgpkg s"}
\label{sec:plpkg}
The main purpose of the present section is to have a central 
reference for all ``generic" packages based on 'plainpkg', 
to avoid repeating details in the documentation of each single 
package of that kind.

\subsubsection{The Notion: ``Strong" and ``Weak \Plpkgpkg s"}
\label{sec:not}
I introduce the notion of ``\strong{\plpkgpkg s}" for ``generic" packages 
based on 'plainpkg.tex' and requiring it. 
\begin{description}
  \item[Strong \plpkgpkg s] (i)~have filename extension |.sty| 
    \ and \ (ii)~contain |\input plainpkg|. 
  \item[Weak   \plpkgpkg s] do not load `plainpkg.tex', 
    but their \emph{documentation} says that they must be loaded 
    \emph{after} `plainpkg.tex' has been loaded.
    They have filename extension |.sty| as well.
\end{description}
\emph{My} \plpkgpkg s will also contain \ |\ProvidesPackage{<pkg>}[<ver>]| \
(\mbox{after} `\input plpkgpkg').
A package loading `plainpkg.tex' and \emph{not} containing `\ProvidesPackage'
may work and be called a ``\plpkgpkg", but the usefulness of such a 
practice, hmm, is in some sense discussed in Section~\ref{sec:load}.

``Weak" \plpkgpkg s are just an idea that came to my mind when I thought 
about the present documentation, at present I prefer \emph{strong} 
\plpkgpkg s, I do not want to explain usage of weak \plpkgpkg s.

I like to place the `\input plainpkg' ``right-adjusted" in the 
plain text file hoping this way the file information of the next 
\cs{Provides\dots} line is not overlooked.

\subsubsection{How to Load a \Plpkgpkg}
For loading a \plpkgpkg\ `<generic>.sty' from within some file <loading>, 
we have the following cases:
\begin{description}
  \item[from within the \LaTeX\ document preamble] of <loading>:\\
    |\usepackage{<generic>}|\footnote{$\dots$ or even 
        &\RequirePackage{<generic>} \dots}
  \item[not intended for \LaTeX:] |\input <generic>.sty|
  \item[possibly with \LaTeX (``generic"):] |\Require{<generic>}|\\---and 
    `plainpkg.tex' should have been loaded before,\\ 
    \strong{recommendation:} <loading> a \plpkgpkg\ `<lodyng>.sty' itself.
\end{description}
\strong{Note:}\quad The optional argument as in 
|\RequirePackage{<generic>}[<date>]| is \strong{not supported} (at present)!

\subsubsection{How to Make a \Plpkgpkg}
% \subsubsection{What a \Plpkgpkg\ Must Contain}
% For what a \plpkgpkg\ \emph{must} contain, 
% ---see Section~\ref{sec:not}.
Section~\ref{sec:not} tells what rather is \emph{required} for a 
\plpkgpkg, and Section~\ref{sec:may} summarizes what additionally 
\emph{works} in a \plpkgpkg, due to 'plainpkg''s \emph{features.}

\subsubsection{What a \Plpkgpkg\ May Contain}
\label{sec:may}
A \plpkgpkg\ may contain 
\begin{itemize}
  \item |\ProvidesPackage|, |\RequirePackage|
    (without optional argument), 
  \item |\ifltx|, and |\withcsname|; 
  \item 'stacklet' commands properly paired: 
    for each ``private letter" <char>, place 
    \begin{itemize}
      \item |\PushCatMakeLetter\<char>| above its first use 
    and place 
      \item |\PopLetterCat\<char>| after the last use, above `\endinput'. 
      \item If <char> is `@', 
    |\PushCatMakeLetterAt| and |\PopLetterCatAt| are recommended instead.
    \end{itemize}
\end{itemize}

% \subsubsection{Implications}
% See Section~\ref{sec:feat} for what is available besides the 
% specific features advertised for some \plpkgpkg.
% 
\subsubsection{Other ``\pkg{plainpkg} Files"}
As 'plainpkg' also provides a fallback definition for 
|\ProvidesFile|, another notion could be that of a 
``\pkg{plainpkg} file" <file> that \ 
(i)~has an arbitrary filename extension, \
(ii)~is loaded by |\input <file>| or, with \LaTeX, |\input{<file>}|
\ and \
(iii)~may contain what is allowed according to Section~\ref{sec:may}, 
apart from `\ProvidesPackage'.
As an obvious example, all the document source files such as `<part>.tex'
may start with `\ProvidesFile', or certain `.def' files could be 
considered ``\pkg{plainpkg} files."

% \subsection{More PU\dots}
% \begin{enumerate}                    %% 2012/08/24
% \item 
% `plainpkg.tex' should be loaded by
% % \[|\input plainpkg|\]
% \[\cs{input plainpkg}\]
% starting a file <generic> for Plain~\TeX\ or that should be 
% independent of a \TeX\ format (basically based on `plain.tex'). 
% \item 
% Below that line, such a file may contain 
% \begin{enumerate}
%   \item a \LaTeX\ |\ProvidesFile| or |\ProvidesPackage|
%         command (purpose: accessible by '\ctanpkgref{readprov}.sty'),
%   \item commands from the 'stacklet' package managing 
%         private letters with nested packages, 
%   \item |\RequirePackage<args>|,
%   \item |\ifltx| indicating running under \LaTeX\ or with 
%         \CtanPkgRef{miniltx}{miniltx.tex}. 
%         However, something may fail when 'miniltx.tex'
%         is loaded \emph{after} 'plainpkg.tex'. 
%         In this case, `\ifltx' at least indicates 
%         what \emph{format} is used. 
% \end{enumerate}
% \item 
% When <generic> is some `<generig>.sty' also intended to 
% work as a \LaTeX\ package, 'plainpkg' will at least ensure 
% that the 'stacklet' commands in <generic> work.
% \item 
% (Such) <generic> `<generig>.sty' files should be loaded by 
% \[|\RequirePackage{generig}|\]
% ---\emph{not} \qtd{\cs{input <generig>.sty}}---to ensure that, 
% under \LaTeX,                                    %% 2012/09/16
% \[`\ProvidesPackage{generig}'\]
% works properly and to avoid multiple loading.    %% 2012/09/16
% \item 
% \emph{Without} \LaTeX, |\ProvidesPackage| also stops reading 
% the rest of the file when it has been loaded earlier. 
% Thus it is a replacement for \ctanpkgref{maybeload}.
% \end{enumerate}

% \setcounter{section}{-1}
\section{Comparison with 'miniltx' and 'maybeload'}
% Packages based on 'plainpkg' can and should employ `\ProvidesPackage'
% and `\RequirePackage' even without \LaTeX. In the latter situation, 
% however, their definitions 
Without \LaTeX, the definitions of `\ProvidesPackage' and `\RequirePackage'
are by no means copies from \LaTeX, as they are in \ctanpkgref{miniltx}. 
Rather, \cs{Provides}\-\code{Package} will work like \ctanpkgref{maybeload}'s 
`\thisfileis'.---\pkg{maybeload} was made for ``\LaTeX," too, 
according to its comment. But that rather was 
pre\mbox{-}$2_{\varepsilon}$ \LaTeX. 'plainpkg' might also have been called 
``\pkg{maybeload2e}", as we are essentially combining 'maybeload''s functionality 
with fall-back support for \LaTeXe's basic package commands.
But of course, that name would not reflect loading 'stacklet', 
whose purpose also has been to have as little as possible 
above `\ProvidesPackage'.

\section{The Package File}
\subsection{Header---Bootstrapping and Legalese}
The first line is for Section~\ref{sec:once}. 
Next I want to have \cs{Provides\textellipsis} info at the top 
of the file, but such a command hasn't been defined yet. 
`\def\filename' etc. could be bad as well, overriding `\filedate' 
of a package that loads 'plainpkg.tex'. 
\input{plainpkg.doc}

\end{document}

VERSION HISTORY

2012/08/22  for v0.1    very first 
2012/08/24  for v0.3    \thanks supplemented
2012/08/25              "installing" sec. -> `plainpkg.tex', 
                        adjusted \HeaderLines, abstract extended, 
                        TOC on \newpage, explaining top lines, 
                        mentioning \ifltx
2012/08/26              LaTeX -> \LaTeX; doc. grammar fix
2012/09/19              different title, moving documentation here 
                        from package file and reworking it, 
                        changing doc structure, abstract mod.