% \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 notebeamer.ins,                     *
%             and the derived files 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>
The `notebeamer` Package
============

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

Overview
--------

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!

Issues
------

The issue tracker for `notebeamer` is currently located
[on GitHub](https://github.com/myhsia/notebeamer/issues).

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.
%</readme>
%
%<*internal>
\fi
%</internal>
%
%<*driver|package>
\RequirePackage{expl3, xparse}
%</driver|package>
%<*driver>
\documentclass[svgnames, onlydoc]{l3doc}
\usepackage[pass]{geometry}
\usepackage{notebeamer}
\AddToHook{env/function/before}{\vspace*{-.65\baselineskip}}
\AddToHook{env/syntax/after}{\vspace*{.15\baselineskip}}
\makeatletter
\def \@key #1{\textcolor{red}{\textbf{\texttt{#1}}} \normalfont \texttt{=}}
\def \s@key #1{\textcolor{red}{\textbf{\texttt{#1}}}}
\DeclareRobustCommand \key {\@ifstar\s@key\@key}
\def \val #1{\meta{\textup{#1}}}
\def \HoLogo@ApTeX #1{\HOLOGO@mbox {Ap\kern -.1667em\TeX}}
\makeatother
\makeindex
\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-28\quad \texttt{v4.1A}}
%
% \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 various compilation methods, such as
% \hologo{pdfLaTeX}, \hologo{XeLaTeX}, \hologo{ApTeX}, \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{itemize}[leftmargin = 0pt]
%     \item [\key{color}] \val{string} 
%     \item [\key{ratio}] \val{float point num} can set imported slides' ratio
%       and empty area's width (Default: |0.5|).
%     \item [\key{sep}] \val{dim} can set the vertical space between slides
%     (Default: |2ex|).
%     \item [\key{nup}] \val{int} can set the number of slides on every page
%     (Default: |3|).
%     \item [\key{pages}] \val{comma separated list} can select pages to insert.
%     The comma separated list contains combination of (ranges of) page numbers.
%     (Default: |1|).
%     \item [\key{lhead, rhead}] \val{string} can set the left / right header
%       of the pages.
%   \end{itemize}
% \end{function}
%
% For instance, \cs[no-index]{newgeometry} could be used for assistance.
% \begin{verbatim}
%   \newgeometry{margin = .75in}
%   \includebeamer
%     [ nup = 4, pages = {2-4, 6},  lines = 32, ratio = .28,
%       Navy,    lhead = Chapter 1, rhead = Page~\thepage
%     ] { example-image-a4-numbered.pdf }
% \end{verbatim}
% \newgeometry{margin = .75in}
% \includebeamer
%   [ nup = 4, pages = {2-4, 6},  lines = 32, ratio = .28,
%     Navy,    lhead = Chapter 1, rhead = Page~\thepage
%   ] { example-image-a4-numbered.pdf }
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{The Source Code}
%
% \linespread{1.15}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%    \begin{macrocode}
%<@@=ntbm>
%    \end{macrocode}
%
%    \begin{macrocode}
\ProvidesExplPackage {notebeamer} {2025-02-28} {v4.1A}
  {Package provides macros for inputting slides on note papers quickly.}
%    \end{macrocode}
%
%    \begin{macrocode}
\RequirePackage{l3graphics, tikz, tikzpagenodes}
%    \end{macrocode}
%
% \subsection{User's Interface}
%
% \begin{macro}{\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}
%   \begin{variable}
%     {
%       \@@_include_color_tl, \@@_include_pages_tl,
%       \@@_include_nup_int,  \@@_include_lines_int,
%       \@@_include_ratio_fp, \@@_include_sep_dim,
%       \@@_include_lhead_tl, \@@_include_rhead_tl
%     }
% Key--value definitions for the \cs{includebeamer} command.
%    \begin{macrocode}
\keys_define:nn { notebeamer / includebeamer }
  {
    color   .tl_set:N  = \@@_include_color_tl,
      color .initial:n = black,
    pages   .tl_set:N  = \@@_include_pages_tl,
      pages .initial:n = 1,
    nup     .int_set:N = \@@_include_nup_int,
      nup   .initial:n = 3,
    lines   .int_set:N = \@@_include_lines_int,
    ratio   .fp_set:N  = \@@_include_ratio_fp,
      ratio .initial:n = .5,
    sep     .dim_set:N = \@@_include_sep_dim,
      sep   .initial:n = 2ex,
    lhead   .tl_set:N  = \@@_include_lhead_tl,
    rhead   .tl_set:N  = \@@_include_rhead_tl,
    unknown .code:n    = \tl_if_novalue:nF {#1}
      { \tl_set_eq:NN \@@_include_color_tl \l_keys_key_tl }
  }
%    \end{macrocode}
%   \end{variable}
% \end{macro}
%
% \subsection{Internal Auxiliary}
%
% \begin{variable}{\@@_nup_dim,\@@_include_ratio_dim}
%   Store the heights and widths of the logical pages in a specific nup.
%    \begin{macrocode}
\dim_new:N \@@_nup_dim
\dim_new:N \@@_include_ratio_dim
%    \end{macrocode}
% \end{variable}
% \newpage
% \begin{variable}{\@@_pages_total_int,\@@_pages_residue_int}
%   Store the number of total physical pages and residue logical pages.
%    \begin{macrocode}
\int_new:N \@@_pages_total_int
\int_new:N \@@_pages_residue_int
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\@@_tmpa_clist}
%   Store the results of \cs{@@_range_to_list:nN}.
%    \begin{macrocode}
\clist_new:N \@@_tmpa_clist
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\@@_include_aux:n}
%   Define the auxiliary command for \cs{includebeamer}.
%    \begin{macrocode}
\cs_new_protected_nopar:Npn \@@_include_aux:n #1
  {
    \graphics_get_pagecount:nN {#1} \@@_include_filepages_int
    \dim_set:Nn \@@_nup_dim { \textheight/\@@_include_nup_int }
    \dim_set:Nn \@@_include_ratio_dim
      { \fp_use:N \@@_include_ratio_fp \textwidth }
    \tl_if_eq:NnTF \@@_include_pages_tl { - }
      {
        \@@_range_to_list:nN
          { 1 - \@@_include_filepages_int } \@@_tmpa_clist
      }
      {
        \exp_args:NV \@@_range_to_list:nN
          { \@@_include_pages_tl } \@@_tmpa_clist
      }
    \int_set:Nn \@@_pages_total_int
      {
        \fp_eval:n
          { ceil
              ( \clist_count:N \@@_tmpa_clist/
                  \@@_include_nup_int,0
              ) - 1
          }
      }
    \int_set:Nn \@@_pages_residue_int
      {
        \int_eval:n
          {
            \clist_count:N \@@_tmpa_clist -
            \@@_include_nup_int * \@@_pages_total_int
          }
      }
    \int_step_inline:nn { \int_use:N \@@_pages_total_int }
      {
        \clearpage
        \@@_empty_note_aux:
        \int_step_inline:nn { \@@_include_nup_int }
          {
            \tikz [ remember~picture, overlay ]
              \node [ xshift = \@@_include_ratio_dim/2,
                      yshift = \fp_eval:n { -####1 + .5 } \@@_nup_dim
                    ] at (current~page~text~area.north~west)
                {
                  \includegraphics
                    [ height = \dim_eval:n
                        { \@@_nup_dim - \@@_include_sep_dim },
                      page = \clist_item:Nn \@@_tmpa_clist
                        { ####1 + \@@_include_nup_int * ( ##1 - 1 ) }
                    ] {#1}
                };
          }
        \clearpage
      }
    \@@_empty_note_aux:
    \int_step_inline:nn { \int_use:N \@@_pages_residue_int }
      {
        \tikz [ remember~picture, overlay ]
          \node [ xshift = \@@_include_ratio_dim/2,
                  yshift = \fp_eval:n {( -##1 + .5 )} \@@_nup_dim
                ] at (current~page~text~area.north~west)
            {
              \includegraphics
                [ height = \dim_eval:n
                    { \@@_nup_dim - \@@_include_sep_dim },
                  page = \clist_item:Nn \@@_tmpa_clist
                    {
                      \@@_include_nup_int *
                      \@@_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, \@@_include_color_tl!80 ]
        (current~page~text~area.north~west) --
        (current~page~text~area.north~east)
       node [ at~start, above~right, font = \Large \bfseries ]
        { \@@_include_lhead_tl }
       node [ above~left, font = \Large \bfseries ]
        { \@@_include_rhead_tl };
      \draw [ very~thick, \@@_include_color_tl!80 ]
        (current~page~text~area.south~west) --
        (current~page~text~area.south~east);
      \int_step_inline:nn { \@@_include_lines_int - 1 }
        {
          \draw [ thick, \@@_include_color_tl!60 ]
            ([xshift = \@@_include_ratio_dim,
              yshift = -\textheight/\@@_include_lines_int * ##1
             ]current~page~text~area.north~west) --++
            (\dim_eval:n { \textwidth - \@@_include_ratio_dim },0);
        }
    \endtikzpicture
    \pagestyle{empty}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}{\@@_tmpa_seq,\@@_tmpb_seq}
%   Store the results of 2D array segmentation.
%    \begin{macrocode}
\seq_new:N \@@_tmpa_seq
\seq_new:N \@@_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 \@@_tmpa_seq { , } {#1}
    \seq_map_inline:Nn \@@_tmpa_seq 
      {
        \tl_if_in:nnTF {##1} { - }
          {
            \seq_set_split:Nnn \@@_tmpb_seq { - } {##1}
            \int_step_inline:nnn 
              { \seq_item:Nn \@@_tmpb_seq { 1 } } 
              { \seq_item:Nn \@@_tmpb_seq { 2 } } 
              { \clist_put_right:Nn #2 {####1} }
           } { \clist_put_right:Nn #2 {##1} }
      }
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex