notebeamer.dtx

% \iffalse meta-comment
%
% File: notebeamer.dtx
% -----------------------------------------------------------------------
%   Copyright (C) 2023-2025 by Mingyu Xia <myhsia@outlook.com>          *
%                                                                       *
%   It may be distributed and/or modified under the conditions of the   *
%   LaTeX Project Public License (LPPL), either version 1.3c of this    *
%   license or (at your option) any later version. The latest version   *
%   of this license is in the file                                      *
%                                                                       *
%       http://www.latex-project.org/lppl.txt                           *
%                                                                       *
%   This work has the LPPL maintenance status `maintained`.             *
%                                                                       *
%   The Current Maintainer of this work is Mingyu Xia.                  *
%                                                                       *
%   This work consists of the files notebeamer.dtx,                     *
%             and the derived files notebeamer.ins,                     *
%                                   notebeamer.sty,                     *
%                                   notebeamer.pdf,                     *
%                               and README.md.                          *
% -----------------------------------------------------------------------
%
%   Any modification of this file should ensure that the copyright and
%   license information is placed in the derived files.
%
% -----------------------------------------------------------------------
%
%<*internal>
\iffalse
%</internal>
%
%<*readme>
# notebeamer

The `notebeamer` package provides a method for inputting slides on note
papers quickly.

Basic Usage
-----------

The package provides the `\includebeamer` macro

    \includebeamer [<keyvals>] {<filename>} [<keyvals>]

to set the format that how the slides is arranged on note papers.

See `notebeamer.pdf` for more. Happy TeXing!

Copyright and License
---------------------

  Copyright (C) 2023-2025 by Mingyu Xia <myhsia@outlook.com>

  It may be distributed and/or modified under the conditions of the
  LaTeX Project Public License (LPPL), either version 1.3c of this
  license or (at your option) any later version. The latest version
  of this license is in the file
      http://www.latex-project.org/lppl.txt
  This work has the LPPL maintenance status `maintained`.

  The Current Maintainer of this work is Mingyu Xia.

  This work consists of the files notebeamer.dtx,
            and the derived files notebeamer.ins,
                                  notebeamer.sty,
                                  notebeamer.pdf,
                              and README.md (this file).
%</readme>
%
%<*internal>
\fi
%</internal>
%
%<*driver|package>
\RequirePackage{expl3, xparse}
%</driver|package>
%<*driver>
\documentclass[svgnames]{l3doc}
\usepackage[pass]{geometry}
\usepackage{notebeamer}
\AddToHook{env/function/before}{\vspace*{-.6\baselineskip}}
\def \key #1{\textcolor{red}{\textbf{\texttt{#1}}}}
\def \keyval #1#2{\key{#1} \normalfont \texttt{=} \meta{\textup{#2}}}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{notebeamer} Package\thanks
%    {^^A
%     \url{https://github.com/myhsia/notebeamer},
%     \url{https://ctan.org/pkg/notebeamer}^^A
%    }
% }
%
% \author{^^A
%   Mingyu Xia
%   \texttt{<\href{mailto:myhsia@outlook.com}{myhsia@outlook.com}>}^^A
% }
%
% \date{Released 2025-02-12\quad \texttt{v4.0D}}
%
% \maketitle
%
% \begin{documentation}
%
% \section{Introduction}
%
% The \pkg{notebeamer} package provides an easy way to input slides on note
% pages quickly for making annotations, developed by \pkg{expl3} based on
% \pkg{tikz} and \pkg{l3graphics}. It is compatible with \hologo{TeX} Live 2019
% or later distributions and supports compilation methods such as
% \hologo{pdfLaTeX}, \hologo{XeLaTeX}, and \hologo{LuaLaTeX}, etc.
%
% \section{Usage}
%
% To load this package, write the line
% \begin{quote}
%   |\usepackage{notebeamer}|
% \end{quote}
%
% \begin{function}{\includebeamer}
%   \begin{syntax}
%     \cs{includebeamer} \oarg{keyvals} \marg{filename} \oarg{keyvals}
%   \end{syntax}
%   The \cs{includebeamer} command can create pages with note lines, and import
%   the specific pages of the \file{.pdf} file on the left side of the note
%   pages. The mandatory argument can set the \file{.pdf} file that will be
%   inserted. The optional argument accepts the following keys
%   \begin{description}[leftmargin = 0pt]
%     \item [\keyval{color}{string}] can set the color of the note lines
%     (Default: \cmd{black}), key's name could be omitted.
%     \item [\keyval{ratio}{fp}] can set the ratio of imported slides' and empty
%     area's width (Default: \cmd{0.5}).
%     \item [\keyval{sep}{dim}] can set the vertical space between slides
%     (Default: \cmd{2ex}).
%     \item [\keyval{nup}{int}] can set the number of slides on every page
%     (Default: \cmd3).
%     \item [\keyval{pages}{comma separated list}] can select pages to insert.
%     The comma separated list contains combination of (ranges of) page numbers.
%     (Default: \cmd1).
%     \item [\keyval{lefthead}{string}, \keyval{righthead}{string}] can set the
%     left / right header of the pages.
%   \end{description}
% \end{function}
%
% Meanwhile, You can use \cs{newgeometry}. For instance
% \begin{verbatim}
%   \newgeometry{margin = .75in}
%   \includebeamer
%     [ nup = 4, pages    = {2-4, 6},  lines     = 32, ratio = .28, 
%       Navy,    lefthead = Chapter 1, righthead = Page~\thepage
%     ] { example-image-a4-numbered.pdf }
% \end{verbatim}
%
% \newgeometry{margin = .75in}
% \includebeamer
%   [ nup = 4, pages    = {2-4, 6},  lines     = 32, ratio = .28, 
%     Navy,    lefthead = Chapter 1, righthead = Page~\thepage
%   ] { example-image-a4-numbered.pdf }
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{The Source Code}
%
% \linespread{1.15}
%
%    \begin{macrocode}
%<*package>
%<@@=notebm>
%    \end{macrocode}
%
% The package starts here.
%
%    \begin{macrocode}
\ProvidesExplPackage{notebeamer}{2025-02-12}{v4.0D}
  {Package provides macros for inputting slides on note papers quickly.}
\RequirePackage{l3graphics, tikz, tikzpagenodes}
%    \end{macrocode}
%
% \subsection{User's Interface}
%
% \DescribeMacro{\includebeamer}
% Define the \cs{includebeamer} command.
%    \begin{macrocode}
\NewDocumentCommand \includebeamer { O{} m O{} }
  {
    \group_begin:
    \keys_set:nn { notebeamer / includebeamer } { #1, #3 }
    \__@@_include_aux:n {#2}
    \group_end:
  }
%    \end{macrocode}
%
% \subsection{Keys}
%
% Define the keys for the \cs{includebeamer} command.
%
%    \begin{macrocode}
\keys_define:nn { notebeamer / includebeamer }
  {
    color     .tl_set:N  = \l__@@_include_color_tl,
      color   .initial:n = black,
    pages     .tl_set:N  = \l__@@_include_pages_tl,
      pages   .initial:n = 1,
    nup       .int_set:N = \l__@@_include_nup_int,
      nup     .initial:n = 3,
    lines     .int_set:N = \l__@@_include_lines_int,
    ratio     .fp_set:N  = \l__@@_include_ratio_fp,
      ratio   .initial:n = .5,
    sep       .dim_set:N = \l__@@_include_sep_dim,
      sep     .initial:n = 2ex,
    lefthead  .tl_set:N  = \l__@@_include_lefthead_tl,
    righthead .tl_set:N  = \l__@@_include_righthead_tl,
    unknown   .code:n    = \tl_if_novalue:nF {#1}
      { \tl_set_eq:NN \l__@@_include_color_tl \l_keys_key_tl }
  }
%    \end{macrocode}
%
% \subsection{Internal Auxiliary}
%
% \begin{variable}{\l__@@_nup_dim,\l__@@_include_ratio_dim}
%   Store the heights and widths of the logical pages in a specific nup.
%    \begin{macrocode}
\dim_new:N \l__@@_nup_dim
\dim_new:N \l__@@_include_ratio_dim
%    \end{macrocode}
% \end{variable}
% \newpage
% \begin{variable}{\l__@@_pages_total_int,\l__@@_pages_residue_int}
%   Store the number of total physical pages and residue logical pages.
%    \begin{macrocode}
\int_new:N \l__@@_pages_total_int
\int_new:N \l__@@_pages_residue_int
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l__@@_tmpa_clist}
%   Store the results of \cs{@@_range_to_list:nN}.
%    \begin{macrocode}
\clist_new:N \l__@@_tmpa_clist
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\__@@_include_aux:n}
%   Define the auxiliary command of \cs{includebeamer}.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \__@@_include_aux:n #1
  {
    \graphics_get_pagecount:nN {#1} \l__@@_include_filepages_int
    \dim_set:Nn \l__@@_nup_dim { \textheight/\l__@@_include_nup_int }
    \dim_set:Nn \l__@@_include_ratio_dim
      { \fp_use:N \l__@@_include_ratio_fp \textwidth }
    \tl_if_eq:NnTF \l__@@_include_pages_tl { - }
      {
        \@@_range_to_list:nN
          { 1 - \l__@@_include_filepages_int } \l__@@_tmpa_clist
      }
      {
        \exp_args:NV \@@_range_to_list:nN
          { \l__@@_include_pages_tl } \l__@@_tmpa_clist
      }
    \int_set:Nn \l__@@_pages_total_int
      {
        \fp_eval:n
          {
            ceil(\clist_count:N \l__@@_tmpa_clist/\l__@@_include_nup_int,0)
          } - 1
      }
    \int_set:Nn \l__@@_pages_residue_int
      {
        \int_eval:n
          {
            \clist_count:N \l__@@_tmpa_clist -
            \l__@@_include_nup_int * \l__@@_pages_total_int
          }
      }
    \int_step_inline:nn { \int_use:N \l__@@_pages_total_int }
      {
        \clearpage
        \__@@_empty_note_aux:
        \int_step_inline:nn { \l__@@_include_nup_int }
          {
            \tikz [ remember~picture, overlay ]
              \node [ xshift = \l__@@_include_ratio_dim/2,
                      yshift = \fp_eval:n { -####1 + .5 } \l__@@_nup_dim
                    ] at (current~page~text~area.north~west)
                {
                  \includegraphics
                    [ height = \dim_eval:n
                        { \l__@@_nup_dim - \l__@@_include_sep_dim },
                      page = \clist_item:Nn \l__@@_tmpa_clist
                        { ####1 + \l__@@_include_nup_int * ( ##1 - 1 ) }
                    ] {#1}
                };
          }
        \clearpage
      }
    \__@@_empty_note_aux:
    \int_step_inline:nn { \int_use:N \l__@@_pages_residue_int }
      {
        \tikz [ remember~picture, overlay ]
          \node [ xshift = \l__@@_include_ratio_dim/2,
                  yshift = \fp_eval:n {( -##1 + .5 )} \l__@@_nup_dim
                ] at (current~page~text~area.north~west)
            {
              \includegraphics
                [ height = \dim_eval:n
                    { \l__@@_nup_dim - \l__@@_include_sep_dim },
                  page = \clist_item:Nn \l__@@_tmpa_clist
                    { \l__@@_include_nup_int * \l__@@_pages_total_int + ##1 }
                ] {#1}
            };
      }
    \clearpage
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\__@@_empty_note_aux:}
%   Define the auxiliary command for creating empty note line page.
%    \begin{macrocode}
\cs_new_protected_nopar:Nn \__@@_empty_note_aux:
  {
    \tikzpicture [ remember~picture, overlay ]
      \draw [ very~thick, \l__@@_include_color_tl!80 ]
        (current~page~text~area.north~west) --
        (current~page~text~area.north~east)
       node [ at~start, above~right, font = \Large \bfseries ]
        { \l__@@_include_lefthead_tl }
       node [ above~left, font = \Large \bfseries ]
        { \l__@@_include_righthead_tl };
      \draw [ very~thick, \l__@@_include_color_tl!80 ]
        (current~page~text~area.south~west) --
        (current~page~text~area.south~east);
      \int_step_inline:nn { \l__@@_include_lines_int - 1 }
        {
          \draw [ thick, \l__@@_include_color_tl!60 ]
            ([xshift = \l__@@_include_ratio_dim,
              yshift = -\textheight/\l__@@_include_lines_int * ##1
             ]current~page~text~area.north~west) --++
            (\dim_eval:n { \textwidth - \l__@@_include_ratio_dim },0);
        }
    \endtikzpicture
    \pagestyle{empty}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}{\l__@@_tmpa_seq,\l__@@_tmpb_seq}
%   Store the results of 2D array segmentation.
%    \begin{macrocode}
\seq_new:N \l__@@_tmpa_seq
\seq_new:N \l__@@_tmpb_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\@@_range_to_list:nN}
%   Convert the combination of number and number range to a list.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \@@_range_to_list:nN #1#2
  {
    \clist_clear:N #2
    \seq_set_split:Nnn \l__@@_tmpa_seq { , } {#1}
    \seq_map_inline:Nn \l__@@_tmpa_seq 
      {
        \tl_if_in:nnTF {##1} { - }
          {
            \seq_set_split:Nnn \l__@@_tmpb_seq { - } {##1}
            \int_step_inline:nnn 
              { \seq_item:Nn \l__@@_tmpb_seq { 1 } } 
              { \seq_item:Nn \l__@@_tmpb_seq { 2 } } 
              { \clist_put_right:Nn #2 {####1} }
          } { \clist_put_right:Nn #2 {##1} }
      }
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%<@@=>
%    \end{macrocode}
%
% The package ends here.
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
\endinput
%%
%% End of file `notebeamer.dtx'