pnotes.dtx

% \iffalse meta-comment
%
% Copyright (C) 2014-2016 by jonasc, rwen32
%
% This file may be distributed and/or modified under the conditions of the
% Creative Commons Attribution-ShareAlike 3.0 Unported License.
% The license can be found in LICENSE and on:
%
%     https://creativecommons.org/licenses/by-sa/3.0/
%
% \fi

% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1994/06/01]
%<package>\ProvidesPackage{pnotes}[2017/03/23 v1.4 pdfpc presentation notes]
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{pnotes}
\usepackage{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
    \DocInput{pnotes.dtx}
\end{document}
%</driver>
% \fi
%
% \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{v0.1}{2014/11/02}{Initial version}
% \changes{v1.0}{2016/01/17}{Create .dtx and .ins file}
% \changes{v1.1}{2016/01/18}{Add all authors to documentation}
% \changes{v1.2}{2016/01/27}{Remove \texttt{iconv} call; completely trim all whitespaces}
% \changes{v1.3}{2016/01/30}{Add \meta{fontsize} package option}
% \changes{v1.4}{2017/03/23}{Remove leading hyphen on otherwise empty lines. Close input file. Rewrite output procedure with other macros.}

% \GetFileInfo{pnotes.sty}

% \title{The \textsf{pnotes} package\thanks{
%     This document corresponds to \textsf{pnotes}~\fileversion,
%     dated~\filedate, and can be found on github at \url{https://github.com/jonasc/pnotes}.}}
% \author{jonasc \\ \href{mailto:github@bcdf.eu}{\texttt{github@bcdf.eu}}}

% \maketitle

% \newcommand{\pdfpc}{\textsf{pdfpc}}

% \begin{abstract}
% When writing \LaTeX{} presentations with the \textsf{beamer} class and displaying them with the \pdfpc\footnote{\url{https://pdfpc.github.io/}} tool one wants to be able to add meta information to the \LaTeX{} source which is then displayed inside \pdfpc.
% This package aims to close exactly this gap.
% \end{abstract}

% \section{Contributions and License}
% This package's code is originally based on an answer on \TeX{} Stack Exchange\footnote{\url{https://tex.stackexchange.com/a/119267}} by user cebe\footnote{\url{https://tex.stackexchange.com/users/10327/cebe}} published under the Creative Commons Attribution-ShareAlike 3.0 license\footnote{\url{https://creativecommons.org/licenses/by-sa/3.0/}} (CC BY-SA 3.0).

% First versions were co-developed with ronwzl\footnote{\url{https://github.com/ronwzl}}, some improvements were suggested by kaueraal\footnote{\url{https://github.com/kaueraal}}.

% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}

% We first need to import four packages.
% |xstring| is used to replace paragraph breaks by line breaks and to split the string into pieces.
% |kvoptions| is used for the package options.
% |expl3| is used for the |\pnotes@trimspaces| macro.
% Finally, |etoolbox| is used for loops and conditional expressions.
%    \begin{macrocode}
\RequirePackage{xstring}
\RequirePackage{kvoptions}
\RequirePackage{expl3}
\RequirePackage{etoolbox}
%    \end{macrocode}

% \subsection{Package options}
% The package accepts four different options.
% First of all you can set the desired presentation \meta{duration}  which is used by \pdfpc{} to display a timer counting down instead of up.
%
% The second option is to specify an \meta{endslide} that is the number of the slide which should be treated as the last one.
% This should usually not be encoded directly but determined dynamically by using |\plastslide| in the corresponding frame.
%
% The third option specifies the \meta{outputdir}, the folder all the temporary files are written to by the \LaTeX{} compiler.
% Since there is no automatic way of determining this it must be given if it differs from the standard which is the current directory.
%
% As a fourth option we can specify the \meta{fontsize} at which the help text should be displayed by \pdfpc.
%    \begin{macrocode}
\DeclareStringOption[0]{duration}
\DeclareStringOption[0]{endslide}
\DeclareStringOption[.]{outputdir}
\DeclareStringOption[0]{fontsize}
\ProcessKeyvalOptions*
%    \end{macrocode}

% \subsection{Whitespace trimming}
% We define some functionality to trim whitespaces to be used when writing the notes to the file.
% The code comes from \TeX{} Stack Exchange\footnote{\url{https://tex.stackexchange.com/a/69771}}, written by Joseph Wright\footnote{\url{https://tex.stackexchange.com/users/73/joseph-wright}}.
%    \begin{macrocode}
\ExplSyntaxOn
\cs_new_eq:NN \pnotes@trimspaces \tl_trim_spaces:n
\ExplSyntaxOff
%    \end{macrocode}

% \subsection{External files}
% Since we are going to write a \pdfpc{} file and an additional help file we need some file handles.
%    \begin{macrocode}
\newwrite\pnotes@output
\newwrite\pnotes@endslideout
\newread\pnotes@endslidein
%    \end{macrocode}

% Before the document actually starts we open the \pdfpc{} file handle.
%    \begin{macrocode}
\AtBeginDocument{%
    \immediate\openout\pnotes@output\jobname.pdfpc\relax%
%    \end{macrocode}
%
% The first thing to write is the name of the corresponding pdf file.
%    \begin{macrocode}
    \immediate\write\pnotes@output{[file]}%
    \immediate\write\pnotes@output{\jobname.pdf}%
%    \end{macrocode}
%
% If the \meta{duration} option is specified by the user and positive we write its value.
%    \begin{macrocode}
    \ifnum\pnotes@duration>0%
        \immediate\write\pnotes@output{[duration]}%
        \immediate\write\pnotes@output{\pnotes@duration}%
    \fi%
%    \end{macrocode}
%
% If the \meta{fontsize} option is specified by the user and positive we write its value.
%    \begin{macrocode}
    \ifnum\pnotes@fontsize>0%
        \immediate\write\pnotes@output{[font_size]}%
        \immediate\write\pnotes@output{\pnotes@fontsize}%
    \fi%
%    \end{macrocode}
%
% If the \meta{endslide} option is given and positive we output its value.
% This means that the user wants the end slide to be hard coded.
%    \begin{macrocode}
    \ifnum\pnotes@endslide>0%
        \immediate\write\pnotes@output{[end_user_slide]}%
        \immediate\write\pnotes@output{\pnotes@endslide}%
    \else%
%    \end{macrocode}
%
% In case the \meta{endslide} option is not given we try to read it from an helper |.pce| file.
% This is the file in which the end slide's number is written when using |\plastslide|.
%    \begin{macrocode}
        \IfFileExists{\jobname.pce}{%
            \immediate\openin\pnotes@endslidein=\jobname.pce\relax%
            \immediate\read\pnotes@endslidein to \pnotes@endslide%
            \immediate\write\pnotes@output{[end_user_slide]}%
            \immediate\write\pnotes@output{\pnotes@endslide}%
            \immediate\closein\pnotes@endslidein%
        }{}%
    \fi%
%    \end{macrocode}
%
% Now we begin with the contents of the notes themselves.
%    \begin{macrocode}
    \immediate\write\pnotes@output{[notes]}%
}
%    \end{macrocode}

% At the end of the \LaTeX{} file we close the \pdfpc{} file.
%    \begin{macrocode}
\AtEndDocument{%
    \immediate\closeout\pnotes@output%
}
%    \end{macrocode}

% \subsection{Being able to output \#}
% Before beginning slide comments we need to output |### <frame number>|.
% We therefore reset the category code of |#| to \emph{other}\footnote{\url{https://en.wikibooks.org/wiki/TeX/catcode}} and then globally define a command which outputs |### | (three hash marks followed by one space).
%    \begin{macrocode}
\begingroup%
    \catcode`\#=12%
    \gdef\pnotes@slidestart{### }%
\endgroup
%    \end{macrocode}

% \subsection{Counters}
% Since \pdfpc{} does not work with multiple slide starts of the same slide number we need one counter to remember the last slide we wrote some comments.
%    \begin{macrocode}
\newcount\pnotes@lastframe
\pnotes@lastframe=0
%    \end{macrocode}

% \subsection{Writing notes to the file}
% The following command actually writes a note to the output file.
%    \begin{macrocode}
\newcommand{\pnote@writenote}[1]{%
%    \end{macrocode}
%
% Only write the current slide number if it changed since the last write.
%    \begin{macrocode}
    \ifnum\value{framenumber}=\pnotes@lastframe\else%
        \immediate\write\pnotes@output{\pnotes@slidestart\theframenumber}%
    \fi%
%    \end{macrocode}
%
% Replace all paragraphs in the given text by double line breaks.
%    \begin{macrocode}
    \expandarg%
    \StrSubstitute{\unexpanded{#1}}{\unexpanded{\par}}{\unexpanded{\\\\}}[\pnotes@rest]%
%    \end{macrocode}
%
% Split the text at the first line break.
%    \begin{macrocode}
    \StrCut{\pnotes@rest}{\unexpanded{\\}}\pnotes@first\pnotes@rest%
%    \end{macrocode}
%
% Loop as long either the first or the second part contain something.
%    \begin{macrocode}
    \whileboolexpr{
        not test {\ifdefempty{\pnotes@first}}
        or
        not test {\ifdefempty{\pnotes@rest}}
    }{%
%    \end{macrocode}
%
% If the first part is empty, we only output a new line.
% Otherwise we trim the whitespace and output the line with a leading |"- "|.
%    \begin{macrocode}
        \ifdefempty{\pnotes@first}{%
            \immediate\write\pnotes@output{}%
        }{%
            \immediate\write\pnotes@output{%
                - \expandafter\pnotes@trimspaces\expandafter{\pnotes@first}%
            }%
        }%
%    \end{macrocode}
%
% Repeat the text splitting for the next loop.
%    \begin{macrocode}
        \StrCut{\pnotes@rest}{\unexpanded{\\}}\pnotes@first\pnotes@rest%
    }%
%    \end{macrocode}
%
% Save the current frame so we won't output its number twice.
%    \begin{macrocode}
    \pnotes@lastframe=\value{framenumber}%
}
%    \end{macrocode}

% \subsection{The user macros}
% \begin{macro}{\pnote}
% This macro is used to output comments to the current frame.
% We use |\only<1>| to have it output exactly once.
%    \begin{macrocode}
\newcommand{\pnote}[1]{%
    \only<1>{\pnote@writenote{#1}}%
}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\plastslide}
% This macro should be put on the last regular slide.
% It is then output as the last slide for \pdfpc.
%    \begin{macrocode}
\newcommand{\plastslide}{%
    \immediate\openout\pnotes@endslideout\jobname.pce\relax%
    \immediate\write\pnotes@endslideout{\theframenumber}%
    \immediate\closeout\pnotes@endslideout%
}
%    \end{macrocode}
% \end{macro}

% \Finale