summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/plainpkg
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-09-21 22:42:23 +0000
committerKarl Berry <karl@freefriends.org>2012-09-21 22:42:23 +0000
commit001ce1425d9a3d1dcf6d3eade95e7dcd53c5be9b (patch)
tree9e328c707629868ab374011733fc92d11ee275c8 /Master/texmf-dist/source/generic/plainpkg
parent01b93a5e06fc5b6aecdf087e7b0a9ca8eb14a010 (diff)
new generic package plainpkg (21sep12)
git-svn-id: svn://tug.org/texlive/trunk@27765 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/generic/plainpkg')
-rw-r--r--Master/texmf-dist/source/generic/plainpkg/plainpkg-doc.tex282
-rw-r--r--Master/texmf-dist/source/generic/plainpkg/srcfiles.tex12
2 files changed, 294 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/plainpkg/plainpkg-doc.tex b/Master/texmf-dist/source/generic/plainpkg/plainpkg-doc.tex
new file mode 100644
index 00000000000..882dce5ac4b
--- /dev/null
+++ b/Master/texmf-dist/source/generic/plainpkg/plainpkg-doc.tex
@@ -0,0 +1,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.
diff --git a/Master/texmf-dist/source/generic/plainpkg/srcfiles.tex b/Master/texmf-dist/source/generic/plainpkg/srcfiles.tex
new file mode 100644
index 00000000000..8a07a31a36c
--- /dev/null
+++ b/Master/texmf-dist/source/generic/plainpkg/srcfiles.tex
@@ -0,0 +1,12 @@
+\ProvidesFile{srcfiles.tex}[2012/08/22 file infos -> SrcFILEs.txt]
+\RequirePackage{nicefilelist,myfilist}
+\EmptyFileList %%% [readprov.sty,myfilist.sty]
+%% packages:
+\ReadFileInfos{plainpkg}
+%% documentation:
+\ReadFileInfos{plainpkg-doc}
+%% documentation settings and auxiliaries:
+% \ReadPackageInfos{fifinddo,makedoc,niceverb}
+% \ReadFileInfos{makedoc.cfg,mdoccorr.cfg,srcfiles}
+\ListInfos[SrcFILEs.txt]
+