diff --git a/source/presenter.dtx b/source/presenter.dtx index 837ddef..688037d 100644 --- a/source/presenter.dtx +++ b/source/presenter.dtx @@ -291,7 +291,9 @@ % \end{macrocode} % \end{macro} % \begin{macro}{foreground/sectioning} -% Handle the sectioning logic. +% Handle the sectioning logic. Use in pair with \texttt{foreground/headline}. +% The call of \cs{pretsec_register_name_title:nn} is required for every +% implementation code of this object type. % \begin{arguments} % \item the name of sectioning. % \item the content of the sectioning title. diff --git a/source/pretfg.dtx b/source/pretfg.dtx index 39f5f0a..41a71b6 100644 --- a/source/pretfg.dtx +++ b/source/pretfg.dtx @@ -171,15 +171,14 @@ { \AssignTemplateKeys \group_begin: - \l_@@_fg_headline_style_tl - \tl_use:N \l_@@_fg_headline_title_tl + \l_@@_fg_headline_style_tl \pretsec_cur_title: \group_end: \hfil } \DeclareTemplateCode { foreground / sectioning } { default } { 2 } { } { - \tl_set:Nn \l_@@_fg_headline_title_tl { #2 } + \pretsec_register_name_title:nn { #1 } { #2 } } \tl_new:N \l_@@_fg_footline_style_tl \DeclareTemplateCode { foreground / footline } { default } { 0 } @@ -219,7 +218,7 @@ { \AssignTemplateKeys \group_begin: - \pretsec_get_parent_child_title:NN \l_tmpa_seq \l_tmpb_tl + \pretsec_get_stack_parent_child_title:NN \l_tmpa_seq \l_tmpb_tl \seq_if_empty:NTF \l_tmpa_seq { \l_@@_fg_headline_child_style_tl \l_tmpb_tl @@ -239,7 +238,8 @@ \DeclareTemplateCode { foreground / sectioning } { dual } { 2 } { } { - \pretsec_push_name_title:nn { #1 } { #2 } + \pretsec_register_name_title:nn { #1 } { #2 } + \pretsec_push_stack_name_title:nn { #1 } { #2 } } \tl_new:N \l_@@_fg_footline_style_tl \DeclareTemplateCode { foreground / footline } { dual } { 0 } @@ -259,7 +259,7 @@ % \paragraph{\pkg{cascade} style.} % % Almost the same as \pkg{dual} style. But all the parent nodes are displayed. -% Since the parent sequence returned from \cs{pretsec_get_parent_child_title:NN} +% Since the parent sequence returned from \cs{pretsec_get_stack_parent_child_title:NN} % is in the reversed order, when displaying it, reverese the sequence first. % % \begin{macrocode} @@ -277,7 +277,7 @@ { \AssignTemplateKeys \group_begin: - \pretsec_get_parent_child_title:NN \l_tmpa_seq \l_tmpb_tl + \pretsec_get_stack_parent_child_title:NN \l_tmpa_seq \l_tmpb_tl \seq_if_empty:NTF \l_tmpa_seq { \l_@@_fg_headline_child_style_tl \l_tmpb_tl @@ -299,7 +299,8 @@ \DeclareTemplateCode { foreground / sectioning } { cascade } { 2 } { } { - \pretsec_push_name_title:nn { #1 } { #2 } + \pretsec_register_name_title:nn { #1 } { #2 } + \pretsec_push_stack_name_title:nn { #1 } { #2 } } \tl_new:N \l_@@_fg_footline_style_tl \DeclareTemplateCode { foreground / footline } { cascade } { 0 } diff --git a/source/pretsec.dtx b/source/pretsec.dtx index 09b1051..c0b2d74 100644 --- a/source/pretsec.dtx +++ b/source/pretsec.dtx @@ -98,8 +98,54 @@ % % \subsection{Sectioning Title Management} % -% \pkg{pretsec} uses two stacks for storing both the level and the title info -% of sectioning. +% \subsubsection{Required} +% +% \emph{Every sectioning implementation} requires to register the current +% sectioning name and the sectioning title by calling +% \cs{pretsec_register_name_title:nn} for the communication with other +% components of \presenter{}. +% +% \begin{variable}[int]{\g_@@_cur_name_tl, \g_@@_cur_title_tl} +% These private variables store the metadata of current sectioning name or +% current sectioning title. +% \begin{macrocode} +\tl_new:N \g_@@_cur_name_tl +\tl_new:N \g_@@_cur_title_tl +% \end{macrocode} +% \end{variable} +% \begin{macro}{\pretsec_register_name_title:nn} +% Register the current sectioning name and sectioning title to the \presenter{} +% sectioning mechanism, which is required to be called for \emph{every +% sectioning implementation code}. +% \begin{arguments} +% \item sectioning name token list +% \item sectioning title token list +% \end{arguments} +% \begin{macrocode} +\cs_new:Npn \pretsec_register_name_title:nn #1#2 { + \tl_set:Nn \g_@@_cur_name_tl { #1 } + \tl_set:Nn \g_@@_cur_title_tl { #2 } +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\pretsec_cur_name:, \pretsec_cur_title:} +% Macro of current sectioning name or the current sectioning title. +% \begin{macrocode} +\cs_new:Nn \pretsec_cur_name: { \g_@@_cur_name_tl } +\cs_new:Nn \pretsec_cur_title: { \g_@@_cur_title_tl } +% \end{macrocode} +% \end{macro} +% +% \subsubsection{Stack-Based} +% +% For the scenario of getting the route from the root to the leaf of the +% current sectioning position of the outline tree, it is efficient to use a +% stack-based solution to keep track of the sectioning. +% Since the sectioning level usually doesn't exceed 5 (subparagrah), the stack +% depth will also no more than 5, which makes possible to process on the fly +% without additional file storage. +% \pkg{pretsec} solution uses two stacks for storing both the level and the +% title info of sectioning. % % \begin{figure}[H] % \newcommand{\docseqitem}[1]{\framebox[6em]{\vphantom{girl}#1}} @@ -113,6 +159,26 @@ % \end{tabular} % \end{figure} % +% The current implemetation is as follows: +% \begin{itemize} +% \item If the \meta{name} is \texttt{star}, then set \cs{g_@@_star_mark_bool} +% to \texttt{true} and store the \meta{title} to the temporary storage +% \cs{g_@@_star_title_tl}. +% Since the current implementation of \cs{@ssect} cannot be aware of what +% level of sectioning for the starred version of those sectioning +% commands. +% \item If the \meta{name} is \texttt{part}, then clear two stacks +% \cs{g_@@_lv_seq} and \cs{g_@@_title_seq}. +% Since the current implementation of \tn{part} cannot receive the +% parameter of \meta{part title} and will do the special typesetting +% distinguished from other sectioning commands. +% \item Otherwise, pop the stacks until \meta{current level} $<$ +% \meta{stack-top level}, at the moment, the items in the stacks are the +% ancestors of the current. In the end, push the current item to the +% stacks. Now, the top of the stack is the child. Be aware, the ancestors +% are in a reversed order in the sequence (the leftmost is the lowest). +% \end{itemize} +% % \begin{texnote} % % In the current implementation of \file{l3seq.dtx}, for the sequence of length @@ -163,14 +229,14 @@ % \end{macrocode} % \end{variable} % -% \begin{macro}{\pretsec_push_name_title:nn} +% \begin{macro}{\pretsec_push_stack_name_title:nn} % Store the title at the level of sectioning name. % \begin{arguments} % \item sectioning name % \item title % \end{arguments} % \begin{macrocode} -\cs_new:Npn \pretsec_push_name_title:nn #1#2 { +\cs_new:Npn \pretsec_push_stack_name_title:nn #1#2 { \tl_if_eq:nnTF { #1 } { star } { \bool_set_true:N \g_@@_star_mark_bool @@ -207,14 +273,14 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\pretsec_get_parent_child_title:NN} +% \begin{macro}{\pretsec_get_stack_parent_child_title:NN} % Get the parent title sequence (lowest is in the first) and the child title. % \begin{arguments} % \item parent nodes sequence variable in bottom-up (reversed) order % \item child node token list variable % \end{arguments} % \begin{macrocode} -\cs_new:Npn \pretsec_get_parent_child_title:NN #1#2 { +\cs_new:Npn \pretsec_get_stack_parent_child_title:NN #1#2 { \seq_clear:N #1 \tl_clear:N #2 \bool_if:NTF \g_@@_star_mark_bool @@ -233,29 +299,6 @@ % \end{macrocode} % \end{macro} % -% \begin{macro}{\pretsec_get_cur_name:N} -% Get the current sectioning name. -% NOTICE: when the sequence \cs{g_@@_lv_seq} is empty, according to the -% current algorithm of \cs{pretsec_push_name_title:nn}, it is regarded as -% \texttt{part}. A reasonable explanation about the scenario where no -% sectioning command has been issued at the beginning of the document is -% that it is in Part 0 of this document. -% \begin{arguments} -% \item output token list variable of current sectioning name -% \end{arguments} -% \begin{macrocode} -\cs_new:Npn \pretsec_get_cur_name:N #1 { - \bool_if:NTF \g_@@_star_mark_bool - { \tl_set:Nn #1 { star } } - { - \seq_get:NNTF \g_@@_lv_seq \l_tmpb_int - { \pretsec_get_lv_name:nN { \l_tmpb_int } #1 } - { \tl_set:Nn #1 { part } } - } -} -% \end{macrocode} -% \end{macro} -% % \iffalse % % \fi