catcodes (8nov12)

git-svn-id: svn://tug.org/texlive/trunk@28210 c570f23f-e606-0410-a88d-b1316a301751

5 files changed, 282 insertions, 22 deletions

diff --git a/Master/texmf-dist/source/generic/catcodes/catcodes.tex b/Master/texmf-dist/source/generic/catcodes/catcodes.tex
index 8f38766e4b3..c88a5ea7625 100644
--- a/Master/texmf-dist/source/generic/catcodes/catcodes.tex
+++ b/Master/texmf-dist/source/generic/catcodes/catcodes.tex
@@ -1,4 +1,4 @@
-\ProvidesFile{catcodes.tex}[2012/09/20 documenting catcodes files]
+\ProvidesFile{catcodes.tex}[2012/11/07 documenting catcodes files]
 \title{\pkg{catcodes}\\---\\``Generic" Switching of Category Codes}
 % \listfiles
 { \RequirePackage{makedoc} \ProcessLineMessage{}
@@ -18,8 +18,11 @@
 \newcommand*{\headersec}{%
     \subsection{Package File Header---\pkg{plainpkg} and Legalese}}
 \usepackage{ngerman} \originalTeX
-\usepackage{catchdq}
+\usepackage{catchdq}    %% try it more often! TODO 2012/11/07
+\usepackage{langcode}                           %% 2012/11/07
+\usepackage{filedate}                           %% 2012/11/06
 \sloppy
+% \flushbottom                                    %% 2012/11/07
 \begin{document}
 \maketitle
 \begin{MDabstract}
@@ -33,7 +36,9 @@ switching their category codes and assigning meanings to
 ``active-character tokens." \ 
 (iii)\enspace
 %% 2012/09/16:
-\pkg{catchdq.sty} uses the ``double quote" as an active character 
+\pkg{catchdq.sty} uses the 
+``\acro{ASCII}                          %% 2012/11/06
+double quote" as an active character 
 for simplified access to typographical double quotes.---These 
 packages are ``generic" in the sense that they should 
 be usable at least both with \LaTeX\ and Plain \TeX, 
@@ -47,6 +52,9 @@ based on 'plainpkg.tex'.
 \ctanpkgref{csquotes}.  %% 2012/09/16
 \end{MDabstract}
 \tableofcontents
+\section{Overview}
+Sorry, \dots, the abstract and the table of contents 
+must suffice for today (2012-11-07) \TODO
 
 \section{Shared Features of Usage}
 %%% rm. 2012/09/17:
@@ -66,6 +74,7 @@ in the sense of the
 \ctanpkgref{plainpkg}\foothttpurlref{ctan.org/pkg/plainpkg}
 documentation that exhibits details of what is summarized here. 
 Therefore:
+\pagebreak[2]                               %% 2012/11/07
 \begin{itemize}
   \item All of them require that \TeX\ finds `plainpkg.tex' 
         as well as `stackrel.sty'.
@@ -77,25 +86,94 @@ Therefore:
         $\dots$ \ or perhaps `\input{<catcodes>.sty}'? 
 \end{itemize}
 
-\pagebreak
-\section{'stacklet.sty'---Private Letters}
-See Section~\ref{sec:stacklet-cmds} for the commands provided.
-\headersec
-\input{stacklet.doc}
-
-\pagebreak
 \section{'actcodes.sty'---Active Characters}
-See Section~\ref{sec:actcodes-cmds} for the commands provided.
+%% intro 2012/11/07:
+\subsection{Introduction}
+Active characters can simplify syntax often, i.e., the code 
+may be very pleasant to type and read. But sometimes something 
+may fail. See Section~\ref{sec:actcodes-cmds} for how to cope
+with possibilities and difficulties.
 \headersec
 \input{actcodes.doc}
 
-\section{'catchdq.sty'---Proper Double Quotes by Toggling}
-See Section~\ref{sec:catchdq-cmds} for the commands provided.
-Note that the \ctanpkgref{csquotes} provides more comprehensive 
-functionality.
+\section{'catchdq.sty'---Typographical Double Quotes}
+%% <- TODO cf. morgan.sty 2012/11/06 ->
+% \section{'catchdq.sty'---Automatic Typographical Double Quotes by Toggling}
+% \section{'catchdq.sty'---Proper Double Quotes by Toggling}
+%% <- morgan.sty 2012/11/06 ->
+\subsection{Introduction}
+\catchdqs
+The 'catchdq' package allows getting typographical double quotes 
+by just using the "\acro{ASCII} double quote" |"|. A more precise overview:
+\begin{enumerate}
+  \item Typically, "typographical" quotation marks mean distinguishing 
+        between "opening" and "closing" quotation marks. 
+        Usually, you must enter different characters or commands for 
+        the distinction, such as |``| for "opening" and |''| for 
+        \emph{closing}---in \emph{English} with \emph{\TeX}. 
+        For \emph{English} with \emph{Plain~\TeX}, even |"| suffices for "closing."
+  \item There are much different conventions especially for \emph{German} 
+        and \emph{French}. They require different characters or \TeX~commands
+        than for \emph{English}. The packages \ctanpkgref{german}, 
+        \ctanpkgref{ngerman}, and \ctanpkgref{babel} have dealt with 
+        such conventions. 
+  \item Understanding the ideas mentioned before has been difficult 
+        for a long time, probably because typewriter and computer \emph{keyboards} 
+        never have offered the appropriate keys. Rather, they only offered 
+        the "\acro{ASCII} double quote" that produced an approximation 
+        ("neutral quotation marks")
+        \emph{not} making the difference. Many users and readers 
+        have not realized the difference, they have not realized 
+        how their screen or printer output differed from double quotes 
+        in books and newspapers. Cf.~the 
+        \wikienref{Quotation mark}{Wikipedia article}\footnote{%
+            \urlhttpref{en.wikipedia.org/wiki/Quotation mark}} 
+  \item The idea of the 'catchdq' package is that the user indeed should 
+        not worry about that difference and just type 
+        "\acro{ASCII} double quotes", and they should be "converted" 
+        into the appropriate typographical quotation marks \emph{automatically}. 
+        This should work by "toggling," i.e., the first 
+        "\acro{ASCII} double quote" is interpreted as "opening," 
+        the second as "closing," the next one as "opening"~\dots
+        ---Word processors have provided this feature (as an option) 
+        as well.
+  \item Language-dependency of the feature currently is managed 
+        through the \ctanpkgref{langcode} package.
+  \item The feature may cause problems sometimes. 
+        Therefore, explicit switching the feature "on" 
+        and "off" is required.
+  \item The \ctanpkgref{csquotes} package addresses the issue 
+        in a more comprehensive and perhaps more stable way.
+\end{enumerate}
+See Section~\ref{sec:catchdq-cmds} for 
+% the commands provided.
+% Note that the \ctanpkgref{csquotes} 
+% provides more comprehensive functionality.
+additional details.                         %% 2012/11/06
+\MakeOther\"                                %% TODO 2012/11/06
+
 \headersec
 \input{catchdq.doc}
 
+\pagebreak
+\section{'stacklet.sty'---Private Letters}
+\subsection{Introduction}
+\catchdqs           %% 2012/11/07
+\uselangcode{en}    %% 2012/11/07, \dedqtd above
+"Private letters" \emph{here} are meant to be 
+characters that belong to the "letter" 
+category only within packages. A package typically provides 
+user commands as well as internal commands, and the latter 
+are characterized by containing funny letters in commands such 
+as `\@gobble.' This is to avoid conflicts.
+See Section~\ref{sec:stacklet-cmds} for the commands provided.
+\MakeOther\"        %% 2012/11/07
+\headersec
+\input{stacklet.doc}
+
+%% 'filedate' check 2012/11/06:
+\noNiceVerb 
+\input{fdatechk.tex}
 \end{document}
 
 VERSION HISTORY
@@ -107,3 +185,15 @@ VERSION HISTORY
 2012/09/19                      "plainpkg packages", \pagebreaks, 
                                 Roman numbers in abstract, \headersec
 2012/09/19                      trying ngerman.sty
+
+             UPLOADED with `catcodes' r0.1 2012-09-20
+
+2012/11/06                      supplementing missing word; 
+                                TODO on catchdq, `filedate' checks, 
+                                typeset with recent `niceverb';
+                                more accurate about `catchdq', 
+                                long introduction
+2012/11/07                      final formatting, some more info on 
+                                `stacklet' and `actcodes', TODOs, 
+                                some \catchdqs, `Overview',
+                                2 more \subsec...Intro... 
diff --git a/Master/texmf-dist/source/generic/catcodes/fdatechk.tex b/Master/texmf-dist/source/generic/catcodes/fdatechk.tex
new file mode 100644
index 00000000000..c32d65998cc
--- /dev/null
+++ b/Master/texmf-dist/source/generic/catcodes/fdatechk.tex
@@ -0,0 +1,15 @@
+\ProvidesFile{fdatechk.tex}[2012/11/07 `filedate' checks]
+%% TODO short notation
+\UseReferenceDate{\thepdfmoddate}
+\ModDates
+\ReadFileInfos{catcodes.RLS,srcfiles}
+\CheckDateOfGiven{actcodes.sty}
+\CheckDateOfGiven{catchdq.sty}
+%\DatesDiffWarnings
+\CheckDateOfGiven{stacklet.sty}
+%\DatesDiffErrors
+\CheckDateOfGiven{catcodes.tex}
+\CheckDateOfGiven{fdatechk.tex}
+\CheckDateOfGiven{srcfiles.tex}
+\DatesDiffWarnings
+\CheckDateOfToday{catcodes.RLS}
diff --git a/Master/texmf-dist/source/generic/catcodes/makedoc.cfg b/Master/texmf-dist/source/generic/catcodes/makedoc.cfg
new file mode 100644
index 00000000000..ea9293175e5
--- /dev/null
+++ b/Master/texmf-dist/source/generic/catcodes/makedoc.cfg
@@ -0,0 +1,95 @@
+\ProvidesFile{makedoc.cfg}[2012/11/06 documentation settings] 
+
+\author{Uwe L\"uck\thanks{\url{http://contact-ednotes.sty.de.vu}}}
+% \author{Uwe L\"uck---{\tt http://contact-ednotes.sty.de.vu}}
+
+%% hyperref:
+\RequirePackage{ifpdf}
+\usepackage[%
+  \ifpdf
+%     bookmarks=false,          %% 2010/12/22
+%     bookmarksnumbered,
+    bookmarksopen,              %% 2011/01/24!?
+    bookmarksopenlevel=2,       %% 2011/01/23
+%     pdfpagemode=UseNone,
+%     pdfstartpage=10,
+%     pdfstartview=FitH,
+    pdfstartview=0 0 100,       %% 2011/08/22
+    pdffitwindow=true,          %% 2011/08/22
+    citebordercolor={ .6 1    .6},
+    filebordercolor={1    .6 1},
+    linkbordercolor={1    .9  .7},
+     urlbordercolor={ .7 1   1},   %% playing 2011/01/24
+  \else
+    draft
+  \fi
+]{hyperref}
+%% metadata, |\MDkeywords|, |\MDkeywordsstring|, |\printMDkeywords|
+%% 2011/08/22:
+\makeatletter
+  \newcommand*{\MDkeywords}[1]{%
+    \gdef\MDkeywordsstring{#1}%
+    \hypersetup{pdfkeywords=\MDkeywordsstring}%% TODO!?
+  }
+  \@onlypreamble\MDkeywords
+  \newcommand*{\MDaddtoabstract}[1]{%               %% 2012/05/10
+    \par\smallskip\noindent
+    \strong{#1:}\quad\ignorespaces}
+  \newcommand*{\printMDkeywords}{%
+    \MDaddtoabstract{Keywords}%
+    \MDkeywordsstring 
+    \global\let\MDkeywordsstring\relax
+  }
+  \newenvironment{MDabstract}
+                 {\abstract\noindent
+                  \hspace{1sp}%% for niceverb
+                  \ignorespaces}
+                 {\@ifundefined{MDkeywordsstring}%
+                               {}%
+                               {\printMDkeywords}%
+                  \endabstract}
+\makeatother
+\hypersetup{% 
+    pdfauthor={Uwe L\374ck}% 
+}
+\RequirePackage{niceverb}[2011/01/24] 
+\RequirePackage{readprov}               %% 2010/12/08
+\RequirePackage{hypertoc}               %% 2011/01/23
+\RequirePackage{texlinks}               %% 2011/01/24
+\RequirePackage{relsize}                %% 2011/06/27
+\RequirePackage{color}                  %% 2011/08/06
+\RequirePackage{lmodern}                %% 2012/10/29
+%% Logical markup |\strong{<text>}|, |\file{<text>}|, |\acro{<text>}|,
+%% |\meta{<text>}|, |\pkg{<text>}|, |\code{<text>}|, |\qtdcode{<text>}|:
+\makeatletter
+  \def\do#1#2{\@ifdefinable#1{\let#1#2}}%% 2012/07/13
+  \do\strong\textbf \do\file\texttt \do\acro\textsmaller 
+  %% <- wrong tests before 2012/07/13
+  \do\meta\textit   \do \pkg\textsf \do\code\texttt
+  \newcommand*{\qtdcode}[1]{`\code{#1}'}            %% 2012/10/24
+  \ifpdf
+    \pdfstringdefDisableCommands{%
+        \let\acro\textrm 
+        \let\file\textrm                            %% 2011/11/09
+        \let\code\textrm                            %% 2011/11/20
+        \let\pkg \textrm                            %% 2012/03/23
+    }
+  \fi
+  %% TODO 2011/07/22 -> `htlogml.sty'
+\makeatother
+\newcommand*{\pkgtitle}[2]{%            %% 2012/07/13
+    \global\let\pkgtitle\relax
+    \pkg{\huge #1}\\---\\#2\thanks{This 
+       document describes version 
+       \textcolor{blue}{\UseVersionOf{\jobname.sty}} 
+       of \textsf{\jobname.sty} as of \UseDateOf{\jobname.sty}.}}
+\newcommand*{\TODO}{\textcolor{blue}{\acro{TODO}}}
+\newcommand*{\MDsampleinput}[1]{%          %% 2012/11/06
+    \par\bigskip\hrule\verbatiminput{#1}%
+                \hrule\bigskip}
+
+\errorcontextlines=4
+\pagestyle{headings}
+
+\endinput
+
diff --git a/Master/texmf-dist/source/generic/catcodes/mdoccorr.cfg b/Master/texmf-dist/source/generic/catcodes/mdoccorr.cfg
new file mode 100644
index 00000000000..5914ea260bb
--- /dev/null
+++ b/Master/texmf-dist/source/generic/catcodes/mdoccorr.cfg
@@ -0,0 +1,57 @@
+\ProvidesFile{mdoccorr.cfg}[2012/11/07
+              `makedoc' local typographical corrections]
+%% ... also demonstrates 'niceverb.sty'---see the typeset 
+%% documentation of the present file in `makedoc.pdf'.
+%%
+%% |\SetPatternCodes{<commands>}| redefines 
+%% `\PatternCodes' to be used in parsing and replacing 
+%% (some ``sanitizing"). %% improved line breaks 2010/03/29
+\SetPatternCodes{\MakeOther\\\MakeOther\ }
+%% |\StartPrependingChain| initializes setup of a replacement 
+%% chain:
+\StartPrependingChain
+%% |\PrependExpandableAllReplacer*{<find>}{<subst>}|:
+\PrependExpandableAllReplacer*{etc. }{etc.\ }
+%% ... you can keep inter-sentence space after `etc.'
+%% by a code line break.
+\PrependExpandableAllReplacer*{Cf. }{Cf.\ }    %% 2011/01/12
+\PrependExpandableAllReplacer*{cf. }{cf.\ } %% corr. 2010/03/23
+%% ... but think of `cf.~'. Don't leave `cf.' at code line end!
+\PrependExpandableAllReplacer*{->}{$\to$}      %% 2010/11/06
+\PrependExpandableAllReplacer*{<-}{$\gets$}    %% 2010/11/06
+% \PrependExpandableAllReplacer{...}{...}{$\dots$}
+%% Allow extra space at line end (bug fix `{}' 2011/12/03): 
+\PrependExpandableAllReplacer*{...}{\textellipsis\unkern{}}
+%% 2011/10/13: original `\dots' correct before punctuation:
+% \PrependExpandableAllReplacer{dots,}{...,}{\dots,}
+\PrependExpandableAllReplacer*{...)}{\dots)}   %% 2011/10/25
+\PrependExpandableAllReplacer*{...:}{\dots:}   %% 2012/11/07
+\PrependExpandableAllReplacer*{... }{\textellipsis\unkern\ }
+\PrependExpandableAllReplacer*{TODO}{\TODO{}} 
+%% ... chain starts here, and here |\MakeDocCorrectHook| (silently) 
+%% enters through a default variant |\SetCorrectHookJobLast|
+%% of |\SetCorrectHookJob{<id>}|:
+\SetCorrectHookJobLast
+%% |\ResetPatternCodes| resets `\PatternCodes' to their default 
+%% value (which is `\fdPatternCodes'):
+\ResetPatternCodes
+%% ... restores 'fifinddo' default. 
+\endinput 
+
+HISTORY
+2009/04/05  with makedoc v0.2
+2010/03/11  broke some too long code lines
+2010/03/16  rendered `mdoccorr.cfg'
+2010/03/22  try \Prepend...
+2010/03/23  corrected `cf'
+2010/03/29  use \SetPatternCodes etc.
+2010/11/06  <- and ->
+2010/11/24  `...' ``symmetric variant" of `\textellipsis';
+            \StartPrependingChain, no more \MakeExpandableAllreplacer 
+2011/01/27  blue "TODO"
+2011/09/13  \providecommand for dialogues
+2011/10/13  \MDtwodots, without \PXAR, `...,' `...:'
+2011/10/25  \textellipsis\unkern from csquotes instead, `...)'
+2011/11/13  \PrependExpandableAllReplacer*
+2011/12/03  bug fix for 2011/10/25 at line ends 
+2012/11/07  TODO -> \TODO{}
diff --git a/Master/texmf-dist/source/generic/catcodes/srcfiles.tex b/Master/texmf-dist/source/generic/catcodes/srcfiles.tex
index 22951400e16..13de4782983 100644
--- a/Master/texmf-dist/source/generic/catcodes/srcfiles.tex
+++ b/Master/texmf-dist/source/generic/catcodes/srcfiles.tex
@@ -1,8 +1,7 @@
-\ProvidesFile{srcfiles.tex}[2012/09/20 file infos -> SrcFILEs.txt]
-\RequirePackage[r]{nicefilelist}
-\MFfieldtemplate{f-base}{catcodes}
-\RequirePackage{myfilist}
-\EmptyFileList %%% [readprov.sty,myfilist.sty]
+\ProvidesFile{srcfiles.tex}[2012/11/07 file infos -> SrcFILEs.txt]
+\RequirePackage[r,wrap]{nicefilelist}
+\RequirePackage{filedate}
+\MaxBaseEmptyList* %%% [readprov.sty,myfilist.sty]
 %% packages:
 \ReadPackageInfos{actcodes,catchdq,stacklet}
 %% documentation:
@@ -12,5 +11,9 @@
 % \ReadFileInfos{makedoc.cfg,mdoccorr.cfg,srcfiles}
 % \ReadFileInfos{srcfiles}
 \ReadFileInfos{catcodes.RLS}
-\ListInfos[SrcFILEs.txt]
-
+% \FileListRemark[ -- ]{---USED.---}
+\ReadFileInfos{makedoc.cfg,mdoccorr.cfg}
+\NoStopListInfos[SrcFILEs.txt]
+\EqualityMessages
+\input{fdatechk}
+\stop