clojure-pamphlet (24aug19)

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

2 files changed, 393 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/support/clojure-pamphlet/clojure-pamphlet.dtx b/Master/texmf-dist/source/support/clojure-pamphlet/clojure-pamphlet.dtx
new file mode 100644
index 00000000000..e0cb5b2f022
--- /dev/null
+++ b/Master/texmf-dist/source/support/clojure-pamphlet/clojure-pamphlet.dtx
@@ -0,0 +1,339 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2019 by Lanchares Sanchez, Ernesto
+%
+% This file may be distributed and/or modified under the
+% conditions of the GNU General Public License as published by
+% the Free Software Foundation; either version 3, or (at your option)
+% any later version.
+%
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+% GNU General Public License for more details.
+%
+% You should have received a copy of the GNU General Public License
+% along with this program.  If not, see <http://www.gnu.org/licenses/>.
+%
+% \fi
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
+%<package>\ProvidesPackage{clojure-pamphlet}[2019/07/08 v1.o .dtx clojure pamphlet file]
+%
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage{clojure-pamphlet}
+\usepackage{hyperref}
+\usepackage{csquotes}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+    \DocInput{clojure-pamphlet.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{175}
+%
+% \CharacterTable
+%   {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+% \changes{v1.0}{2019/07/14}{Initial version}
+%
+% \GetFileInfo{clojure-pamphlet.sty}
+% 
+% \DoNotIndex{\bgroup,\egoup,\ ,\advance,\begin,\bf,\big,\closeout,\csname}
+% \DoNotIndex{\def,\do,\edef,\else,\end,\endcsname,\endinput,\expandafter}
+% \DoNotIndex{\fi,\global,\hbox,\hskip,\hyperlink,\hypertarget,\if,\ifcsname}
+% \DoNotIndex{\ifdefined,\iffalse,\iftrue,\immediate,\it,\jobname,\label,\let}
+% \DoNotIndex{\lstnewenvironment,\lstset,\nameref,\newcommand,\newenvironment}
+% \DoNotIndex{\newline,\newwrite,\next,\noindent,\openout,\relax,\string,\the}
+% \DoNotIndex{\unexpanded,\write,\xdef,\\,\{,\},\@for,\@input,\@empty}
+% \DoNotIndex{\@currentlabelname}
+%
+% \title{The \textsf{clojure-pamphlet} package\thanks{This document
+%   corresponds to \textsf{clojure-pamphlet}~\fileversion,
+%   dated~\filedate.}}
+% \author{Ernesto Lanchares Sanchez\\ \texttt{e.lancha98@gmail.com}}
+%
+% \maketitle
+%
+% \begin{abstract}
+%   A package to make beautiful literate programming documents. The system is
+%   based on clojure's pamphelt files.
+% \end{abstract}
+%
+% \section{Introduction}
+%
+% \href{http://www.literateprogramming.com/}{Literate Programming} is a
+% programming paradigm that changes the goal of the program:
+% \begin{displayquote}
+%   Let us change our traditional attitude to the construction of programs:
+%   Instead of imagining that our main task is to instruct a computer what to do,
+%   let us concentrate rather on explaining to human beings what we want a
+%   computer to do.
+% \end{displayquote}
+% 
+% Since it's creation, many systems have been created to accomplish this goal,
+% systems like \texttt{WEB}, \texttt{CWEB}, \texttt{noweb}, \ldots This systems
+% all share the same structure: There is one source file and two programs
+% needed, one that extracts the code to be compiled and other that extracts the
+% literature (usually a \TeX/\LaTeX file) to be compiled.
+%
+% This is the reason that we preffer clojure's system where there is one \LaTeX
+% source file that can be compiled and one program to extract the code to be
+% compiled. Although the clojure system is fine as it is, we think the resulting
+% documentation can be a bit prettier hence this package. The difference in
+% using this package or the clojure system as a developer is non-existent,
+% however we think the documentation with our system is a bit more readable. It
+% also automaticly adds hyperlinks to the output in order to make it easier to
+% navigate when viewing in a computer.
+%
+% \section{Usage}
+%
+% The \texttt{clojure-pamphlet} system is designed to be as simple as possible,
+% so this package only provides one environment and one command. The system is
+% based arround code chunks. This chunks are the part of the documents that
+% contain code and can be extracted. The chunks also contain a name so that they
+% can be referenced in the document and in other chunk blocks. The name is also
+% needed for the tangler to extract the chunk.
+%
+% \subsection{\texttt{chunk} environment}
+% \DescribeEnv{chunk}
+% The chunk environment is used to define code blocks. This code blocks have a
+% name and are what the tangler will actually output. It is based on the
+% \href{https://www.ctan.org/pkg/listings}{listings} package, so all style
+% formats that yo can apply to \texttt{lstlisting} environments, you can also
+% apply to chunk environments by simply using the command \texttt{lstset}.
+%
+% Here's an example of a code usage and it's output
+% \begin{verbatim}
+% \begin{chunk}{main}
+% int main(int argc, char* argv[]) {
+%   printf("Hello World.\n");
+% }
+% \end{chunk}
+% \end{verbatim}
+%
+% \iffalse
+%<*test>
+% \fi
+\begin{chunk}{main}
+ int main(int argc, char* argv[]) {
+   printf("Hello World.\n");
+ }
+\end{chunk}
+% \iffalse
+%</test>
+% \fi
+%
+% \DescribeMacro{\getchunk}
+% Also, inside the \texttt{chunk} environment, you can use the \verb|\getchunk|
+% command, which includes the referenced chunk at that exact same spot. The \verb|\getchunk|
+% command requires to be in it's own separate line. Let's
+% illustrate this with an example:
+%
+% \begin{verbatim}
+% \begin{chunk}{onechunk}
+% CHUNK ONE
+% \end{chunk}
+% \begin{chunk}{otherchunk}
+% PREVIOUS
+% \getchunk{onechunk}
+% POST
+% \end{chunk}
+% \end{verbatim}
+%
+% \iffalse
+%<*test>
+% \fi
+\begin{chunk}{print}
+printf("Hello World");
+\end{chunk}
+\begin{chunk}{main}
+int main(int argc, char* argv[]) {
+    \getchunk{print}
+}
+\end{chunk}
+% \iffalse
+%</test>
+% \fi
+%
+% \subsection{The tangler}
+% The tangler is designed to be as simple to use as possible. You just need
+% to provide it with a \LaTeX \texttt{clojure-pamphlet} file and a code chunk to
+% extract. Then the tangler will output the code to be compiled in the standard
+% output. For example in order to extract the main chunk of code we will need to
+% run
+% \begin{verbatim}
+% pamphletangler [filename.tex] main
+% \end{verbatim}
+%
+% And the output will be
+% \begin{verbatim}
+% int main(int argc, char* argv[]) {
+%       printf("Hello World");
+% }
+% \end{verbatim}
+%
+% \StopEventually{\PrintIndex}
+%
+% \section{Implementation}
+%
+% We need to import the listings package to create the code blocks
+% and the hyperref package to create the clickable links
+%    \begin{macrocode}
+\RequirePackage{listings}
+\RequirePackage{hyperref}
+%    \end{macrocode}
+%
+% We need to import the referecences, a.k.a. the ``used by'' text
+% below the code
+%    \begin{macrocode}
+\@input{\jobname.pam}
+%    \end{macrocode}
+%
+% We initialize a counter, needed to define a unique csname in each
+% \verb|getchunk| call.
+%    \begin{macrocode}
+\newcount\pam@references
+%    \end{macrocode}
+%
+% We define commands to write and compare the \{ and \} characters
+% Solution from \url{https://tex.stackexchange.com/a/47453}
+%    \begin{macrocode}
+\edef\wbgroup{\iftrue\string{\else}\fi}
+\edef\wegroup{\iffalse{\else\string}\fi}
+%    \end{macrocode}
+% \begin{macro}{\pam@storetext}
+% This macro is used inside getchunkenv. This will consume tokens
+% and store them inside \verb|pam@tex| macro until it reads a ``\}'' macro
+% (defined by lst), then it calls the \verb|\getchunk| command on the stored
+% text. Finally, calls the ``\}'' macro needed by lst to finish processing the
+% code block.
+%    \begin{macrocode}
+\def\pam@storetext#1{%
+    \expandafter\if\string#1\wegroup%
+        \getchunk{\pam@text}%
+        #1%
+    \else%
+        \edef\pam@text{\pam@text#1}%
+        \expandafter\pam@storetext% This expandafter is so the input of
+                                  % \pam@storetext is not \fi
+    \fi%
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{environment}{pam@getchunkenv}
+% This environment is not ment to be used outside this document and it's only
+% purpose it's to wrap the \verb|pam@storetext| macro inside an environment.
+%    \begin{macrocode}
+\newenvironment{pam@getchunkenv}{\def\pam@text{}%
+\expandafter\pam@storetext}{}
+%    \end{macrocode}
+% \end{environment}
+%
+% \begin{environment}{chunk}
+% Here is the main environment.
+%    \begin{macrocode}
+\lstnewenvironment{chunk}[1]{%
+    \hypertarget{#1}%
+    {\ }\newline\noindent%
+    \hbox{\hskip 2.0cm}{\bf --- #1 ---}%
+    \edef\@currentlabelname{#1}%
+    \lstset{alsodigit={.-},alsoletter={\\}}%
+    \lstset{escapebegin=\begin{pam@getchunkenv}}%
+    \lstset{escapeend=\end{pam@getchunkenv}}%
+    \lstset{escapeinside={\\getchunk\{}{\}}}%
+}{
+    {\ }\newline\noindent%
+    \hbox{\hskip 2.0cm}%
+    {\it ---\csname referenced#1\endcsname---}%
+}
+%    \end{macrocode}
+% \end{environment}
+% \begin{macro}{\getchunk}
+% We run into the most complicated command. First, we preparate the label so it
+% can be referenced and place the text.
+%    \begin{macrocode}
+\newcommand{\getchunk}[1]{%
+    {\big<}\hyperlink{#1}{#1}{\big>}%
+    \edef\pam@label{reference-\the\pam@references}%
+    \label{\pam@label}%
+    \ifcsname used#1\endcsname\else%
+        \expandafter\def\csname used#1\endcsname{Used by}%
+    \fi%
+%    \end{macrocode}
+% Here we expand the Used by command two times, this is so we fully expand
+% the \verb|\csname| and the command but we don't expand the refs
+%    \begin{macrocode}
+    \edef\pam@tmp{\unexpanded\expandafter\expandafter%
+    \expandafter{\csname used#1\endcsname}}%
+%    \end{macrocode}
+% We add to the used by command, adding a space and the new reference. Also, we
+% increase the global counter and mark the chunk as referenced.
+%    \begin{macrocode}
+\expandafter\xdef\csname used#1\expandafter\endcsname\expandafter{%
+    \expandafter\unexpanded\expandafter{\pam@tmp},%
+    \ \unexpanded\expandafter{\expandafter\nameref\expandafter{\pam@label}}%
+}%
+\global\advance\pam@references 1\relax%
+\ifdefined\pam@chunks%
+    \xdef\pam@chunks{\pam@chunks,#1}%
+\else%
+    \xdef\pam@chunks{#1}%
+\fi%
+}
+%    \end{macrocode}
+% \end{macro}
+% Here we will write the used by commands and references. This will only be
+% done if there are chunks referenced.
+%    \begin{macrocode}
+\AtEndDocument{%
+    \ifdefined\pam@chunks%
+       \newwrite\@pamfile%
+       \immediate\openout\@pamfile=\jobname.pam%
+%    \end{macrocode}
+% Then, we loop through the list and write out the used by commands
+% but the list may contain duplicates so we need to account for it.
+% loop based on \url{https://tex.stackexchange.com/a/16695}
+%    \begin{macrocode}
+\@for\next:=\pam@chunks\do{%
+    \ifcsname lstel@\next\endcsname%
+    \else%
+        \expandafter\let\csname lstel@\next\endcsname\@empty%
+        \immediate\write\@pamfile{%
+            \unexpanded{\expandafter\def\csname }%
+            referenced\next\unexpanded{\endcsname}%
+            \wbgroup%
+            \unexpanded\expandafter\expandafter\expandafter%
+            {\csname used\next\endcsname}%
+            \wegroup%
+        }%
+    \fi%
+}%
+%    \end{macrocode}
+% Finally, we close the auxiliary file
+%    \begin{macrocode}
+       \immediate\closeout\@pamfile%
+   \fi%
+}
+\endinput
+%    \end{macrocode}
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/support/clojure-pamphlet/clojure-pamphlet.ins b/Master/texmf-dist/source/support/clojure-pamphlet/clojure-pamphlet.ins
new file mode 100644
index 00000000000..97cb9794848
--- /dev/null
+++ b/Master/texmf-dist/source/support/clojure-pamphlet/clojure-pamphlet.ins
@@ -0,0 +1,54 @@
+%%
+%% Copyright (C) 2019 by Lanchares Sanchez, Ernesto
+%%
+%% This file may be distributed and/or modified under the
+%% conditions of the GNU General Public License as published by
+%% the Free Software Foundation; either version 3, or (at your option)
+%% any later version.
+%%
+%% This program is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+%% GNU General Public License for more details.
+%%
+%% You should have received a copy of the GNU General Public License
+%% along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+\input docstrip.tex
+\keepsilent
+\usedir{/tex/latex/pam}
+
+\preamble
+This is a generated file.
+
+Copyright (C) 2019 by Lanchares Sanchez, Ernesto
+
+This file may be distributed and/or modified under the
+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.3 or later is part of all distributions of
+LaTeX version 2005/12/01 or later.
+\endpreamble
+
+\generate{\file{clojure-pamphlet.sty}{\from{clojure-pamphlet.dtx}{package}}}
+
+\obeyspaces
+\Msg{****************************************************}
+\Msg{*                                                  *}
+\Msg{* To finish the installation you have to move the  *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{*                                                  *}
+\Msg{*     clojure-pamphlet.sty                         *}
+\Msg{*                                                  *}
+\Msg{* To produce the documentation run the file        *}
+\Msg{* clojure-pamphelt.dtx through LaTeX.              *}
+\Msg{*                                                  *}
+\Msg{* Happy TeXing!                                    *}
+\Msg{*                                                  *}
+\Msg{****************************************************}
+
+\endbatchfile