summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/secnum/secnum.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/secnum/secnum.dtx')
-rw-r--r--macros/latex/contrib/secnum/secnum.dtx340
1 files changed, 295 insertions, 45 deletions
diff --git a/macros/latex/contrib/secnum/secnum.dtx b/macros/latex/contrib/secnum/secnum.dtx
index 1220b7ec59..b8309f8c4d 100644
--- a/macros/latex/contrib/secnum/secnum.dtx
+++ b/macros/latex/contrib/secnum/secnum.dtx
@@ -29,12 +29,20 @@
# secnum
-This package provides a macro \setsecnum to format section numbering intuitively.
+This package provides a macro `\setsecnum` to format section numbering intuitively.
## Usage
-One can simply use `\setsecnum{1.1.1}` to set the section numbering
-format as `arabic.arabic.arabic` and depth to be 3.
+One can simply use `\setsecnum{A,1.i}` to set the section numbering
+format as `Alph` for the sections, `arabic` for the subsections and
+`arabic.roman` for the subsubsections and
+the `secnumdepth` and `tocdepth` will be 3.
+
+If one want to set the tocdepth manually,
+there is an option `tocdep` for it.
+
+One may notice that the comma `,` plays a special role in the numbering format:
+for deep levels, the numbering before the comma are hided.
## Installation
@@ -44,7 +52,7 @@ The installation is the same as usual Tex packages.
1. Run the following to create the package file `secnum.sty` (as well as this file `README.md`)
- XeTeX secnum.dtx
+ pdfTeX secnum.dtx
2. Move the following file into proper directories searched by TeX.
The recommended directory is
@@ -53,7 +61,7 @@ The installation is the same as usual Tex packages.
3. To produce the documentation run the following
- XeLaTeX secnum.dtx
+ pdfLaTeX secnum.dtx
4. The recommended directory for the documentation is
@@ -135,8 +143,8 @@ The Current Maintainer of this work is
\usepackage{indentfirst}
\usepackage{booktabs}
\usepackage{xcolor}
-\usepackage{secnum}
-\setsecnum{A}
+\usepackage[tocdep=2]{secnum}
+\setsecnum{A,1.i}
\ExplSyntaxOn
\cs_set_eq:NN \__codedoc_macro_end_style:n \use_none:n
\ExplSyntaxOff
@@ -168,20 +176,31 @@ The Current Maintainer of this work is
%
% \tableofcontents
% \begin{documentation}
+%
+% \section{Example}
+% This document uses the following setting of section numbering format.
+% \begin{verbatim}
+% \usepackage[tocdep=2]{secnum}
+% \setsecnum{A,1.i}
+% \end{verbatim}
+%
% \section{Usage}
% Before using the macro, load the package in preamble.
% \begin{verbatim}
-% \usepackage{secnum}
+% \usepackage{secnum}
% \end{verbatim}
-% Then, one can format the section numbering by using the
+%
+% \subsection{Set numbering format}
+% One can format the section numbering by using the
% marco \cs{setsecnum} in preamble.
% \begin{function}{\setsecnum}
% \begin{syntax}
% \cs{setsecnum}\marg{num format}
% \end{syntax}
+%
% A typical \meta{num format} is like this:
% \begin{center}
-% \verb|1.1.1|
+% \verb|A,1.i|
% \end{center}
% It consists of some syntax abbrs of numbering formats,
% reffering the follows,
@@ -194,28 +213,87 @@ The Current Maintainer of this work is
% \bottomrule
% \end{tabular}
% \end{center}
-% and some separators, which can be any character except
-% the abbrs and special characters such as barces ``\verb|{}|'',
-% comma ``\verb|,|'', space ``\verb*| |'', etc.
+% and some separators delimiting them.
+%
+% The separators can be any character except above abbrs,
+% the tokens ``\verb|{|'', ``\verb|}|'' and ``\verb|#|''
+% (more precisely, explicit character tokens with category code
+% 1 (begin-group) or 2 (end-group), and tokens with category code 6) and the space ``\verb*| |''.
+%
+% Note that \meta{num format} must end with an abbr.
+%
+% \begin{texnote}
+% This command will overwrite
+% \opt{secnumdepth} and \opt{tocdepth}
+% \end{texnote}
+% \end{function}
+%
+% \subsection{Breaking the numbering}
+% The comma ``\verb|,|'' in above example is used as the breaking mark:
+% for deep levels (in our case, deeper than sections),
+% the numbering before ``\verb|,|'' will be hided.
+%
+% Note that the breaking mark must immediately follows an abbr.
+%
+% \subsection{Package options}
+% \subsubsection{tocdep}
+% There is an option setting \opt{tocdepth}, the table-of-contents depth manually.
+% \begin{function}{ tocdep }
+% \begin{syntax}
+% \opt{tocdep} = \meta{integer}
+% \end{syntax}
+%
+% The \meta{integer} refers to the table-of-contents depth,
+% which should between $1$ and $5$.
+%
+% \begin{texnote}
+% If this option is used, then \cs{setsecnum} will not overwrite \opt{tocdepth}.
+% \end{texnote}
+% \end{function}
+%
+% \subsubsection{breaking}
+% Another option is used to change the breaking mark.
+% \begin{function}{ breaking }
+% \begin{syntax}
+% \opt{breaking} = \meta{token}
+% \end{syntax}
+%
+% The \meta{token} will be the breaking mark
+% (the default is the comma ``\verb|,|'').
+% It can be any character except above abbrs,
+% the tokens ``\verb|{|'', ``\verb|}|'' and ``\verb|#|''
+% (more precisely, explicit character tokens with category code
+% 1 (begin-group) or 2 (end-group), and tokens with category code 6) and the space ``\verb*| |''.
% \end{function}
%
% \section{Process}
% The process of the macro \cs{setsecnum} can be
% explained as follows.
% \begin{enumerate}[label=Step \arabic*.]
-% \item The main function eats the input, saying \opt{I.1.a},
+% \item The main function eats the input, saying \opt{A,1.i},
% and stores it in a token list.
% \item Replace abbrs by macros.
% In our example, it results
-% ``\cs{Roman}\opt{.}\cs{arabic}\opt{.}\cs{alph}''
+% ``\cs{Alph}\opt{,}\cs{arabic}\opt{.}\cs{roman}''
% \item Split this token list into a sequence by macros.
-% In our example, it results ``\cs{Roman}'',
-% ``\opt{.}\cs{arabic}'' and ``\opt{.}\cs{alph}''.
+% In our example, it results ``\cs{Alph}'',
+% ``\opt{,}\cs{arabic}'' and ``\opt{.}\cs{roman}''.
% \item Store those codes in indivial containers.
-% \item Use them to renew \cs{thesection}, \cs{thesubsection},
+% \item Detect if there is \cs{thechapter}.
+% Skip the chapter level if not.
+% In our example, this is the case.
+% \item Use the containers to redefine
+% \cs{thesection}, \cs{thesubsection},
% \cs{thesubsubsection} etc.
-% provided there is no \cs{chapter}.
+% In each step, detect if such level needs numbering and
+% if there is a breaking mark in the container.
+% In our example, the numbering formats will be redefined as
% \end{enumerate}
+% \begin{verbatim}
+% \renewcommand*{\thesection}{\Alph{section}}
+% \renewcommand*{\thesubsection}{\arabic{subsection}}
+% \renewcommand*{\thesubsubsection}{thesubsection.\roman{subsubsection}}
+% \end{verbatim}
%
% \end{documentation}
%
@@ -227,7 +305,7 @@ The Current Maintainer of this work is
% Users can ignore.
% \subsection{Preparations}
% This package uses \LaTeX3.
-% Therefore, the packages \pkg{expl3} and \pkg{xparse}
+% Therefore, the packages \pkg{expl3}, \pkg{xparse} and \pkg{l3keys2e}
% are needed and should use
% \cs{ProvidesExplPackage} rather than \cs{ProvidesPackage}.
%
@@ -236,16 +314,17 @@ The Current Maintainer of this work is
%<@@=syu>
\NeedsTeXFormat{LaTeX2e}
\RequirePackage{expl3}
-\ProvidesExplPackage{secnum}{2020/02/02}{}
+\ProvidesExplPackage{secnum}{2021/08/28}{}
{ An intuitive way to format section numbering }
-\RequirePackage{xparse}
+\RequirePackage{xparse,l3keys2e}
% \end{macrocode}
%
% \begin{variable}{ \l__syu_secnum_tl, \l__syu_secnum_seq }
-% The two variables are used to store the formatting information.
+% The variables are used to store the formatting information.
% \begin{macrocode}
\tl_new:N \l__syu_secnum_tl
\seq_new:N \l__syu_secnum_seq
+\int_new:N \l__syu_secnum_depth
% \end{macrocode}
% \end{variable}
%
@@ -287,8 +366,57 @@ The Current Maintainer of this work is
% \end{macrocode}
% \end{variable}
%
+% \begin{variable}{ \l__syu_secnum_bkm }
+% This variable is used to store the breaking mark.
+% \begin{macrocode}
+\tl_new:N \g__syu_secnum_bkmr
+\tl_gset:Nx \g__syu_secnum_bkmr {,}
+% \end{macrocode}
+% Note that one needs the following variants
+% \begin{macrocode}
+\cs_generate_variant:Nn \tl_if_in:NnTF { NV }
+\cs_generate_variant:Nn \tl_remove_all:Nn { NV }
+% \end{macrocode}
+% \end{variable}
+%
+% \changes{2020/01/12}{2020/01/12}{Add package option to set \opt{tocdepth}.}
+% \subsection{Package option}
+% \begin{macrocode}
+\keys_define:nn { syu / options }
+ {
+% \end{macrocode}
+%
+% \begin{macro}{ tocdep }
+% Set the table-of-contents depth.
+% \begin{macrocode}
+ tocdep .code:n =
+ {
+ \int_const:Nn \g__syu_tocdep {#1}
+ \setcounter{tocdepth}{ \g__syu_tocdep }
+ },
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{ breaking }
+% Set the breaking mark used in \meta{num format}.
+% \begin{macrocode}
+ breaking .code:n =
+ {
+ \tl_gset:Nx \g__syu_secnum_bkmr {#1}
+ },
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+ }
+% \end{macrocode}
+%
+% Passing keys to options.
+% \begin{macrocode}
+\ProcessKeysOptions{ syu / options }
+% \end{macrocode}
+%
% \subsection{Main function}
-%
% \begin{macro}{\setsecnum}
% Here is the definition of the main function \cs{setsecnum}.
% \begin{macrocode}
@@ -314,8 +442,30 @@ The Current Maintainer of this work is
% Set the \opt{secnumdepth} and \opt{tocdepth}.
% \changes{2020/01/12}{2020/01/12}{Add codes to set \opt{tocdepth}.}
% \begin{macrocode}
- \setcounter{secnumdepth}{ \seq_count:N \l__syu_secnum_seq }
- \setcounter{tocdepth}{ \seq_count:N \l__syu_secnum_seq }
+ \int_set:Nn \l__syu_secnum_depth
+ {
+ \seq_count:N \l__syu_secnum_seq
+ }
+ \setcounter{secnumdepth}
+ {
+ \int_eval:n
+ {
+ \l__syu_secnum_depth - \g__syu_if_thechapter_int
+ }
+ }
+ \int_if_exist:NTF \g__syu_tocdep
+ {
+ \setcounter{tocdepth}{ \g__syu_tocdep }
+ }
+ {
+ \setcounter{tocdepth}
+ {
+ \int_eval:n
+ {
+ \l__syu_secnum_depth - \g__syu_if_thechapter_int
+ }
+ }
+ }
% \end{macrocode}
% Format numberings.
% \begin{macrocode}
@@ -434,14 +584,28 @@ The Current Maintainer of this work is
\cs_new:Nn \__syu_secnum:
{
% \end{macrocode}
+% \subsubsection{Detect if there is \cs{thechapter}}\noindent
% When \cs{thechapter} is defined, start from it.
% \begin{macrocode}
\if_cs_exist:N \thechapter
\renewcommand*{\thechapter}
{ \g__syu_chapter_tl {chapter} }
- \renewcommand*{\thesection}
- { \thechapter
- \g__syu_section_tl {section} }
+% \end{macrocode}
+% Test if the numbering breaks before section.
+% \begin{macrocode}
+ \tl_if_in:NVTF \g__syu_section_tl \g__syu_secnum_bkmr
+ {
+ \tl_remove_all:NV \g__syu_section_tl \g__syu_secnum_bkmr
+ \renewcommand*{\thesection}
+ { \g__syu_section_tl {section} }
+ }
+ {
+ \renewcommand*{\thesection}
+ {
+ \thechapter
+ \g__syu_section_tl {section}
+ }
+ }
% \end{macrocode}
% Otherwise start from \cs{thesection}.
% \begin{macrocode}
@@ -450,21 +614,107 @@ The Current Maintainer of this work is
{ \g__syu_section_tl {section} }
\fi:
% \end{macrocode}
-% The rest levels.
-% \begin{macrocode}
- \renewcommand*{\thesubsection}
- { \thesection
- \g__syu_subsection_tl {subsection} }
- \renewcommand*{\thesubsubsection}
- { \thesubsection
- \g__syu_subsubsection_tl {subsubsection} }
- \renewcommand*{\theparagraph}
- { \thesubsubsection
- \g__syu_paragraph_tl {paragraph} }
- \renewcommand*{\thesubparagraph}
- { \theparagraph
- \g__syu_subparagraph_tl {subparagraph} }
- }
+%
+% \changes{2021/08/28}{2021/08/28}{The usage of breaking commas}
+% \subsubsection{Subsections}\noindent
+% Test if the subsections are needed to be numbered.
+% \begin{macrocode}
+ \tl_if_empty:NTF \g__syu_subsection_tl
+ {}
+ {
+% \end{macrocode}
+% Test if the numbering breaks before subsection.
+% \begin{macrocode}
+ \tl_if_in:NVTF \g__syu_subsection_tl \g__syu_secnum_bkmr
+ {
+ \tl_remove_all:NV \g__syu_subsection_tl \g__syu_secnum_bkmr
+ \renewcommand*{\thesubsection}
+ { \g__syu_subsection_tl {subsection} }
+ }
+ {
+ \renewcommand*{\thesubsection}
+ {
+ \thesection
+ \g__syu_subsection_tl {subsection}
+ }
+ }
+ }
+% \end{macrocode}
+%
+% \subsubsection{Subsubsections}\noindent
+% Test if the subsubsections are needed to be numbered.
+% \begin{macrocode}
+ \tl_if_empty:NTF \g__syu_subsubsection_tl
+ {}
+ {
+% \end{macrocode}
+% Test if the numbering breaks before subsubsection.
+% \begin{macrocode}
+ \tl_if_in:NVTF \g__syu_subsubsection_tl \g__syu_secnum_bkmr
+ {
+ \tl_remove_all:NV \g__syu_subsubsection_tl \g__syu_secnum_bkmr
+ \renewcommand*{\thesubsubsection}
+ { \g__syu_subsubsection_tl {subsubsection} }
+ }
+ {
+ \renewcommand*{\thesubsubsection}
+ {
+ \thesubsection
+ \g__syu_subsubsection_tl {subsubsection}
+ }
+ }
+ }
+% \end{macrocode}
+%
+% \subsubsection{Paragraphs}\noindent
+% Test if the paragraphs are needed to be numbered.
+% \begin{macrocode}
+ \tl_if_empty:NTF \g__syu_paragraph_tl
+ {}
+ {
+% \end{macrocode}
+% Test if the numbering breaks before paragraph.
+% \begin{macrocode}
+ \tl_if_in:NVTF \g__syu_paragraph_tl \g__syu_secnum_bkmr
+ {
+ \tl_remove_all:NV \g__syu_paragraph_tl \g__syu_secnum_bkmr
+ \renewcommand*{\theparagraph}
+ { \g__syu_paragraph_tl {paragraph} }
+ }
+ {
+ \renewcommand*{\theparagraph}
+ {
+ \thesubsubsection
+ \g__syu_paragraph_tl {paragraph}
+ }
+ }
+ }
+% \end{macrocode}
+%
+% \subsubsection{Subparagraphs}\noindent
+% Test if the subparagraphs are needed to be numbered.
+% \begin{macrocode}
+ \tl_if_empty:NTF \g__syu_subparagraph_tl
+ {}
+ {
+% \end{macrocode}
+% Test if the numbering breaks before paragraph.
+% \begin{macrocode}
+ \tl_if_in:NVTF \g__syu_subparagraph_tl \g__syu_secnum_bkmr
+ {
+ \tl_remove_all:NV \g__syu_subparagraph_tl \g__syu_secnum_bkmr
+ \renewcommand*{\thesubparagraph}
+ { \g__syu_subparagraph_tl {subparagraph} }
+ }
+ {
+ \renewcommand*{\thesubparagraph}
+ {
+ \theparagraph
+ \g__syu_subparagraph_tl {subparagraph}
+ }
+ }
+ }
+ }
% \end{macrocode}
% \end{variable}
%
@@ -477,4 +727,4 @@ The Current Maintainer of this work is
% \changes{2020/01/01}{2020/01/01}{Correct the package name.}
%
% \Finale
-\endinput \ No newline at end of file
+\endinput