diff options
Diffstat (limited to 'macros/latex/contrib/dbshow/dbshow-doc.tex')
-rw-r--r-- | macros/latex/contrib/dbshow/dbshow-doc.tex | 444 |
1 files changed, 272 insertions, 172 deletions
diff --git a/macros/latex/contrib/dbshow/dbshow-doc.tex b/macros/latex/contrib/dbshow/dbshow-doc.tex index 02332a1257..40bef33d17 100644 --- a/macros/latex/contrib/dbshow/dbshow-doc.tex +++ b/macros/latex/contrib/dbshow/dbshow-doc.tex @@ -11,6 +11,10 @@ \tcbuselibrary{listings, skins, raster, breakable} \usepackage{tabularray} +\def\zhdate{2022年1月8日} +\def\endate{2022/01/08} +\def\version{v1.2} + \IndexPrologue { \section*{Index} @@ -122,21 +126,27 @@ \DeclareDocumentCommand \opt { O{} m } { \__codedoc_cmd:no {#1} { #2 } } + +\NewDocumentCommand \linktarget { m m m } {% + \hyperlink{#1}{#3}% + \raisebox{1em}{\hypertarget{#2}{}}% +} \ExplSyntaxOff \begin{document} \title{ - \pkg{dbshow} 宏包 - \protect\footnote{\url{https://github.com/ZhiyuanLck/dbshow}} + \pkg{dbshow} 宏包 \version% + \protect\footnote{% + 代码仓库:\url{https://github.com/ZhiyuanLck/dbshow}, + QQ群:788706534} \rlap{\makebox[4cm][r]{ \normalsize $\Longrightarrow$ \color{red} - \protect\hyperlink{en}{English Version} - \protect\hypertarget{zh}{} + \linktarget{en}{zh}{English Version} }} } \author{\textit{李昌锴} \texttt{<lichangkai225@qq.com>}} -\date{2022年1月7日} +\date{\zhdate} \maketitle \tableofcontents @@ -153,6 +163,8 @@ 和其他数据库宏包比如 \pkg{datatool} 相比,\pkg{dbshow} 更专注于非图表类型的数 据展示。 +\subsection{数据类型} + 宏包基于 \pkg{expl3} 的基础类型构建了6种类型: \begin{Description}[\texttt{clist}] \item[\texttt{date}] @@ -170,8 +182,21 @@ 逗号分隔的列表类型。默认值为空列表。 \end{Description} +\subsection{与 \pkg{datatool} 的区别} + +从核心功能上看,\pkg{dbshow} 和 \pkg{datatool} 实现了相同的功能。区别在于 +\pkg{dbshow} 基于 \pkg{expl3} 实现,支持字符串的正则匹配,还支持多级排序。使用 +方式上更倾向于样式与内容分离,所有的样式都可以通过选项提前定义好并且可以复用。 +\pkg{dbshow} 并没有实现从外部文件读取数据以及将数据持久化的功能,我认为这些应 +该是更专业的外部程序的工作而不应该在 \LaTeX 中设计这些功能。因此,\pkg{dbshow} +只提供了一个运行时的临时数据库,足够轻便且满足大部分正常需求。如果你想删除或修 +改数据库中某一条记录,请去对应的位置删除或修改掉对应的 \env{dbitem} 环境,而不 +是让宏包提供一个输出某一行记录的命令。某种意义上记录数据库的 \TeX 源文件本身就 +是数据的一种持久化。 + \section{接口文档} -\subsection{\cs{dbNewDatabase}} + +\subsection{创建、展示和清空数据库} \begin{function}{\dbNewDatabase, \dbNewDatabase*} \begin{syntax} \cs{dbNewDatabase} \oarg{base database} \marg{database} \{ \\ @@ -222,6 +247,23 @@ } \end{verbatim} +\begin{function}{\dbshow} + \begin{syntax} + \cs{dbshow} \marg{style} \marg{database} + \end{syntax} + + 使用 \meta{style} 样式来展示 \meta{database}。 +\end{function} + +\begin{function}{\dbclear} + \begin{syntax} + \cs{dbclear} \marg{database} + \end{syntax} + + 清空 \meta{database} 里的所有内容。 + +\end{function} + \subsection{\cs{dbNewStyle} 和样式选项} \begin{function}{\dbNewStyle} @@ -233,7 +275,7 @@ \meta{base styles},比如 |\dbNewStyle[base1, base2]{new-style}{ques}{}|。 \end{function} -\bigskip +\subsubsection{通用选项} \begin{option}{opt=filter, desc={= \meta{filter}}, init=-none-} 为当前样式设置由 \cs{dbCombineFilters} 所定义的过滤器 @@ -282,6 +324,68 @@ \end{verbatim} \begin{option}{ + opt = item-code, + desc = {= \meta{item code}} +} + 该选项用来设置展示数据库中每条记录的代码。你可以使用 \cs{dbuse} 来展示属性的 + 值。 +\end{option} + +\begin{option}{ + opt = {\meta{attr}/sep}, + desc = {= \meta{sep spec}}, + init = {,~\~} +} +\begin{Syntax} + \meta{attr}/sep = \meta{separator} \\ + \meta{attr}/sep = \{ \\ + ~~\meta{separator between two}, \\ + ~~\meta{separator between more than two}, \\ + ~~\meta{separator between final two} \\ + \} +\end{Syntax} + + 该选项只适用于类型为 |clist| 的属性,用来设置列表间元素的间隔。第一个版本接 + 受一个参数,将所有的元素间隔设置为 \meta{separator}。第二个版本接受逗号分隔 + 的三个参数,分别用来设置只有两个元素时的分隔符 \meta{separator between two}, + 超过两个元素时的分隔符 \meta{separator between more than two},和最后两个元 + 素之间的分隔符 \meta{separator between final two}。 + +\end{option} + +\subsubsection{装饰器} + +下面这些选项在不同层次上装饰原有的展示代码,有些其实不必通过选项的形式来装饰, +但这样做的好处是可以进一步使样式与内容分离。下面的例子中,\meta{style1} 和 +\meta{style2} 是相同的样式,都用 * 将 \meta{attr1} 包裹住了,但是如果你还想定 +义一个样式用 = 将 \meta{attr1} 包裹住,如果用 \meta{style1} 的方式,那就可能 +需要重复大片代码,用 \meta{style2} 的方式则可以很轻松的继承 \meta{style1} 中的 +代码。 + +\begin{verbatim} + \dbNewStyle{style1}{db}{ + item-code = {% + *\rvuse{attr1}*\rvuse{attr2} + % more code + } + } + \dbNewStyle{base-style}{db}{ + item-code = {% + \rvuse{attr1}\rvuse{attr2} + % more code + } + } + \dbNewStyle[base-style]{style2}{db}{ + attr1/before-code = { * }, + attr1/after-code = { * }, + } + \dbNewStyle[base-style]{style3}{db}{ + attr1/before-code = { = }, + attr1/after-code = { = }, + } +\end{verbatim} + +\begin{option}{ opt = before-code, desc = {= \meta{before code}} } @@ -296,11 +400,17 @@ \end{option} \begin{option}{ - opt = item-code, - desc = {= \meta{item code}} + opt = record-before-code, + desc = {= \meta{before code}} } - 该选项用来设置展示数据库中每条记录的代码。你可以使用 \cs{dbuse} 来展示属性的 - 值。 + 该选项用来设置在展示当前记录之前需要执行的代码。 +\end{option} + +\begin{option}{ + opt = record-after-code, + desc = {= \meta{after code}} +} + 该选项用来设置在展示当前记录之后需要执行的代码。 \end{option} \begin{option}{ @@ -320,29 +430,7 @@ \end{option} \begin{option}{ - opt = {\meta{attr}/sep}, - desc = {= \meta{sep spec}}, - init = {,~\~} -} -\begin{Syntax} - \meta{attr}/sep = \meta{separator} \\ - \meta{attr}/sep = \{ \\ - ~~\meta{separator between two}, \\ - ~~\meta{separator between more than two}, \\ - ~~\meta{separator between final two} \\ - \} -\end{Syntax} - - 该选项只适用于类型为 |clist| 的属性,用来设置列表间元素的间隔。第一个版本接 - 受一个参数,将所有的元素间隔设置为 \meta{separator}。第二个版本接受逗号分隔 - 的三个参数,分别用来设置只有两个元素时的分隔符 \meta{separator between two}, - 超过两个元素时的分隔符 \meta{separator between more than two},和最后两个元 - 素之间的分隔符 \meta{separator between final two}。 - -\end{option} - -\begin{option}{ - opt = item-before-code, + opt = {\meta{attr}/item-before-code}, desc = {= \meta{before code}} } 该选项只适用于类型为 |clist| 的属性,用来设置展示列表每个元素前需要执行的代 @@ -350,7 +438,7 @@ \end{option} \begin{option}{ - opt = item-after-code, + opt = {\meta{attr}/item-after-code}, desc = {= \meta{after code}} } 该选项只适用于类型为 |clist| 的属性,用来设置展示列表每个元素后需要执行的代 @@ -474,29 +562,26 @@ \subsection{\cs{dbsave} 和 \cs{dbuse}} -\begin{function}{\dbsave, \dbuse} +\begin{function}{\dbsave} \begin{syntax} - \cs{dbsave} \marg{attr} \marg{data} \\ - \cs{dbuse} \marg{attr} \\ + \cs{dbsave} \marg{attr} \marg{data} \end{syntax} - \cs{dbsave} 用来存储数据,只能在 \env{item} 环境中使用。\cs{dbuse} 用来使用 - 数据,只能在 \opt{item-code} 选项中使用。 + \cs{dbsave} 用来存储数据,只能在 \env{item} 环境中使用。 \end{function} -\subsection{使用 \cs{dbshow} 展示数据库} - -\begin{function}{\dbshow} +\begin{function}[EXP]{\dbuse} \begin{syntax} - \cs{dbshow} \marg{style} \marg{database} + \cs{dbuse} \marg{attr} \end{syntax} - 使用 \meta{style} 样式来展示 \meta{database}。 + \cs{dbuse} 用来使用数据,只能在 \opt{item-code} 选项中使用。\cs{dbuse} 是可 + 展开的。 \end{function} \subsection{条件判别式} -\begin{function}{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF} +\begin{function}[EXP]{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF} \begin{syntax} \cs{dbIfEmptyTF} \marg{true code} \marg{false code} \\ \cs{dbIfEmptyT} \marg{true code} \\ @@ -514,44 +599,6 @@ } \end{verbatim} -\begin{function}{\dbItemIfEmptyT, \dbItemIfEmptyF, \dbItemIfEmptyTF} - \begin{syntax} - \cs{dbItemIfEmptyTF} \marg{true code} \marg{false code} \\ - \cs{dbItemIfEmptyT} \marg{true code} \\ - \cs{dbItemIfEmptyF} \marg{false code} - \end{syntax} - - 该判别式用来判断当前元素是否为空。下面的示例展示了如何在展示 |database-test| - 数据库中 |text| 属性的元素时在元素非空的时候前后都加上 |*|。 -\end{function} - -\begin{verbatim} - \dbNewStyle{style-cond2}{database-test}{ - text/before-code = {\dbItemIfEmptyF{*}}, - text/after-code = {\dbItemIfEmptyF{*}}, - } -\end{verbatim} - -\begin{function}{\dbClistItemIfEmptyT, \dbClistItemIfEmptyF, \dbClistItemIfEmptyTF} - \begin{syntax} - \cs{dbClistItemIfEmptyTF} \marg{true code} \marg{false code} \\ - \cs{dbClistItemIfEmptyT} \marg{true code} \\ - \cs{dbClistItemIfEmptyF} \marg{false code} - \end{syntax} - - 该判别式用来判断列表属性中的元素是否为空。下面的示例展示了如何在展示 - |database-test| 数据库中 |labels| 属性(标签列表)的元素时在标签非空的时候前 - 后都加上 |*|。 -\end{function} - -\begin{verbatim} - \dbNewDatabase{database-test}{labels=clist} - \dbNewStyle{style-cond3}{database-test}{ - labels/item-before-code = {\dbClistItemIfEmptyF{*}}, - labels/item-after-code = {\dbClistItemIfEmptyF{*}}, - } -\end{verbatim} - \subsection{特殊命令} \pkg{dbshow} 定义了一些特殊的命令,会根据语境展开为不同的内容。 @@ -580,16 +627,17 @@ 见第 \ref{sec:example} 节。 \title{ - Package \pkg{dbshow} - \protect\footnote{\url{https://github.com/ZhiyuanLck/dbshow}} + Package \pkg{dbshow} \version% + \protect\footnote{% + Repository: \url{https://github.com/ZhiyuanLck/dbshow}, + Telegram Group: \url{https://t.me/latex_dbshow}} \rlap{\makebox[4cm][r]{ \normalsize $\Longrightarrow$ \color{red} - \protect\hyperlink{zh}{中文版本} - \protect\hypertarget{en}{} + \linktarget{zh}{en}{中文版本} }} } \author{Li Changkai \texttt{<lichangkai225@qq.com>}} -\date{2022/01/07} +\date{\endate} \maketitle \section{Introduction} @@ -605,6 +653,8 @@ The package provides four core functions: data storage and display, data filtering, data sorting and data display. All data is saved once and then you can display these data with custom filters, orders and styles. +\subsection{Data Types} + The package constructs 6 types based on the internal typed of \pkg{expl3}: \begin{Description}[\texttt{clist}] \item[\texttt{date}] @@ -622,9 +672,25 @@ The package constructs 6 types based on the internal typed of \pkg{expl3}: comma list, default empty. \end{Description} +\subsection{Comparison to \pkg{datatool}} + +\pkg{dbshow} and \pkg{datatool} implement the same core functions. But +\pkg{dbshow} is based on \pkg{expl3} and it supports string regex and +multi-level sorting. \pkg{dbshow} tries to divide style from the contents +(data in database): all styles are predefined and can be reused conveniently +so that there can be only codes to save data and one-line code to show the +database inside the \env{document} environment. You can hide the details in +the preamble and focus on the data you want to display. \pkg{dbshow} provides +a simple temporary runtime database, which means it can not input and output +data from/to extern files (they should be responsible by some professional +programming languages). When you need to delete or revise a record, just go to +where it is recorded in the source code rather than use a macro to manipulate +data after they are saved. In a sense, \TeX~file is also a kind of data +persistence. + \section{Interfaces} -\subsection{\cs{dbNewDatabase}} +\subsection{Create, Display and Clear Database} \begin{function}{\dbNewDatabase, \dbNewDatabase*} \begin{syntax} @@ -670,6 +736,23 @@ The example below define a database named |ques|. } \end{verbatim} +\begin{function}{\dbshow} + \begin{syntax} + \cs{dbshow} \marg{style} \marg{database} + \end{syntax} + + Show the \meta{database} with \meta{style}. +\end{function} + +\begin{function}{\dbclear} + \begin{syntax} + \cs{dbclear} \marg{database} + \end{syntax} + + Clear the content of \meta{database}. + +\end{function} + \subsection{\cs{dbNewStyle} and Style Options} \begin{function}{\dbNewStyle} @@ -682,7 +765,7 @@ from a list of \meta{base styles} such as |\dbNewStyle[base1, base2]{new-style}{ques}{}|. \end{function} -\bigskip +\subsubsection{General Options} \begin{option}{opt=filter, desc={= \meta{filter}}, init=-none-} Set the \meta{filter} defined by \cs{dbCombineFilters}. @@ -734,20 +817,6 @@ from a list of \meta{base styles} such as \end{verbatim} \begin{option}{ - opt = before-code, - desc = {= \meta{before code}} -} - Set the \meta{before code} that is executed before displaying the database. -\end{option} - -\begin{option}{ - opt = after-code, - desc = {= \meta{after code}} -} - Set the \meta{after code} that is executed after displaying the database. -\end{option} - -\begin{option}{ opt = item-code, desc = {= \meta{item code}} } @@ -756,22 +825,6 @@ from a list of \meta{base styles} such as \end{option} \begin{option}{ - opt = {\meta{attr}/before-code}, - desc = {= \meta{before code}} -} - Set the \meta{before code} that is executed by \cs{dbuse} before displaying - certain attribute. -\end{option} - -\begin{option}{ - opt = {\meta{attr}/after-code}, - desc = {= \meta{after code}} -} - Set the \meta{after code} that is executed by \cs{dbuse} after displaying - certain attribute. -\end{option} - -\begin{option}{ opt = {\meta{attr}/sep}, desc = {= \meta{sep spec}}, init = {,~\~} @@ -801,8 +854,87 @@ from a list of \meta{base styles} such as \end{option} +\subsubsection{Decorators} + +The options below serves as decorators. In some cases, decorator can also be +encoded directly into |item-code| or some other places, which is convenient +sometimes. The benefit of defining decorators with options is that styles step +further to be divided with contents. In the examples below, \meta{style1} and +\meta{style2} is the same style, which wrap \meta{attr1} with *. When you want +another style which wrap \meta{attr1} with =, if you choose the way of +\meta{style1}, \meta{item code} are repeated, otherwise if you choose the way +of \meta{style2}, \meta{item code} is inherited and you only need define the +decorators. + +\begin{verbatim} + \dbNewStyle{style1}{db}{ + item-code = {% + *\rvuse{attr1}*\rvuse{attr2} + % more code + } + } + \dbNewStyle{base-style}{db}{ + item-code = {% + \rvuse{attr1}\rvuse{attr2} + % more code + } + } + \dbNewStyle[base-style]{style2}{db}{ + attr1/before-code = { * }, + attr1/after-code = { * }, + } + \dbNewStyle[base-style]{style3}{db}{ + attr1/before-code = { = }, + attr1/after-code = { = }, + } +\end{verbatim} + \begin{option}{ - opt = item-before-code, + opt = before-code, + desc = {= \meta{before code}} +} + Set the \meta{before code} that is executed before displaying the database. +\end{option} + +\begin{option}{ + opt = after-code, + desc = {= \meta{after code}} +} + Set the \meta{after code} that is executed after displaying the database. +\end{option} + +\begin{option}{ + opt = record-before-code, + desc = {= \meta{before code}} +} + Set the \meta{before code} that is executed before displaying the record. +\end{option} + +\begin{option}{ + opt = record-after-code, + desc = {= \meta{after code}} +} + Set the \meta{after code} that is executed after displaying the record. +\end{option} + +\begin{option}{ + opt = {\meta{attr}/before-code}, + desc = {= \meta{before code}} +} + Set the \meta{before code} that is executed by \cs{dbuse} before displaying + certain attribute. +\end{option} + +\begin{option}{ + opt = {\meta{attr}/after-code}, + desc = {= \meta{after code}} +} + Set the \meta{after code} that is executed by \cs{dbuse} after displaying + certain attribute. +\end{option} + +\begin{option}{ + opt = {\meta{attr}/item-before-code}, desc = {= \meta{before code}} } Only for attributes of type |clist|. Set the \meta{after code} that is @@ -810,7 +942,7 @@ from a list of \meta{base styles} such as \end{option} \begin{option}{ - opt = item-after-code, + opt = {\meta{attr}/item-after-code}, desc = {= \meta{after code}} } Only for attributes of type |clist|. Set the \meta{after code} that is @@ -939,30 +1071,27 @@ code is showned below. \subsection{\cs{dbsave} and \cs{dbuse}} -\begin{function}{\dbsave, \dbuse} +\begin{function}{\dbsave} \begin{syntax} - \cs{dbsave} \marg{attr} \marg{data} \\ - \cs{dbuse} \marg{attr} \\ + \cs{dbsave} \marg{attr} \marg{data} \end{syntax} - Date is stored with \cs{dbsave} and is displayed with \cs{dbuse}. \cs{dbsave} - can be used only inside the \env{dbitem} environment and \cs{dbuse} can be - only used inside the option \opt{item-code}. + \cs{dbsave} save the \meta{data} to \meta{attr} of current record. + \cs{dbsave} can be used only inside the \env{dbitem} environment. \end{function} -\subsection{Use \cs{dbshow} to Display the Database} - -\begin{function}{\dbshow} +\begin{function}[EXP]{\dbuse} \begin{syntax} - \cs{dbshow} \marg{style} \marg{database} + \cs{dbuse} \marg{attr} \end{syntax} - Show the \meta{database} with \meta{style}. + Display the value of \meta{attr} of current record. \cs{dbuse} is + \textbf{expandable} and can be only used inside the option \opt{item-code}. \end{function} \subsection{Conditionals} -\begin{function}{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF} +\begin{function}[EXP]{\dbIfEmptyT, \dbIfEmptyF, \dbIfEmptyTF} \begin{syntax} \cs{dbIfEmptyTF} \marg{true code} \marg{false code} \\ \cs{dbIfEmptyT} \marg{true code} \\ @@ -981,43 +1110,6 @@ code is showned below. } \end{verbatim} -\begin{function}{\dbItemIfEmptyT, \dbItemIfEmptyF, \dbItemIfEmptyTF} - \begin{syntax} - \cs{dbItemIfEmptyTF} \marg{true code} \marg{false code} \\ - \cs{dbItemIfEmptyT} \marg{true code} \\ - \cs{dbItemIfEmptyF} \marg{false code} - \end{syntax} - - Test if the value of the attribute is empty. The example belows shows how to - surround the non-empty |text| attribute with the symbol *. -\end{function} - -\begin{verbatim} - \dbNewStyle{style-cond2}{database-test}{ - text/before-code = {\dbItemIfEmptyF{*}}, - text/after-code = {\dbItemIfEmptyF{*}}, - } -\end{verbatim} - -\begin{function}{\dbClistItemIfEmptyT, \dbClistItemIfEmptyF, \dbClistItemIfEmptyTF} - \begin{syntax} - \cs{dbClistItemIfEmptyTF} \marg{true code} \marg{false code} \\ - \cs{dbClistItemIfEmptyT} \marg{true code} \\ - \cs{dbClistItemIfEmptyF} \marg{false code} - \end{syntax} - - Test if the item of comma list is empty. The example belows shows how to - surround the non-empty label with the symbol *. -\end{function} - -\begin{verbatim} - \dbNewDatabase{database-test}{labels=clist} - \dbNewStyle{style-cond3}{database-test}{ - labels/item-before-code = {\dbClistItemIfEmptyF{*}}, - labels/item-after-code = {\dbClistItemIfEmptyF{*}}, - } -\end{verbatim} - \subsection{Special Macros} Some special macros are defined to expand to different contents according to context. @@ -1251,6 +1343,14 @@ run pdflatex Add style option: \opt{raw-filter} } \\ 2022-01-07 & 1.1 & Improve example \\ + 2022-01-07 & 1.1.1 & Add macro: \cmd{\dbclear} \\ + 2022-01-07 & 1.1.2 & Add documentation: comparison to \pkg{datatool} \\ + 2022-01-08 & 1.2 & { + Fix str sorting bug \\ + Remove macros: \cmd{\dbItemIfEmpty(TF)}, \cmd{\dbClistItemIfEmpty(TF)} \\ + Make \cs{dbuse} expandable \\ + Add option: \opt{record-before-code}, \opt{record-after-code} + } \\ \end{tblr} \end{documentation} |