\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.