☰

如何定制`l3doc`？

tag-icon • tag-icon doc l3doc
如何定制`l3doc`？

由于我目前正在编写一个包并开始使用dtx格式，我想知道是否有其他类可以使用doc，所以我开始使用l3doc（因为我使用 expl3 语法）。我对此非常满意，但以下几点有点烦人：

  1. 我用它variable来描述变量和macro描述宏（因为function应该在文档中使用而不是在代码中使用）。我怎样才能统一两者的样式（无论边距中有无条形，我都更喜欢有条形）？
  2. 是否可以将这种外观转移到使用\DescribeEnv（条形图也一样）实现的布局？
  3. 我应该如何标记该软件包使用的 Lua 代码？我应该\NewMacroEnvironment按照l3doc文档所述使用吗？

这个问题不是关于：

我实际使用过但不满意的内容（示例dtx文件，我已删除包调用以避免提供.ins文件）：

% \iffalse meta-comment
%<package>\RequirePackage{expl3}
%<package>\RequirePackage{xparse}
%<package>\ProvidesExplPackage{testpack}{2017/04/15}{0.1}{Test package}
%<*driver>
\documentclass{l3doc}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
    \DocInput{testpack.dtx}
\end{document}
%</driver>
% \fi
%
% \begin{documentation}
% \GetFileInfo{testpack.sty}
%
% \title{The \texttt{testpack} package\thanks{This document corresponds to \texttt{termdoc}~\fileversion, dated~\filedate.}}
% \author{TeXnician}
% \date{\today}
% \maketitle
% \tableofcontents
%
% \section{User interface}
%   \DescribeMacro{\justdoit} My test \cs{justdoit}: here would be the function call
% \begin{function}{\justdoit}
%   \begin{syntax}
        |\justdoit|
%   \end{syntax}
%   \meta{description}
% \end{function}
% \end{documentation}
% \begin{implementation}
% \section{Implementation}
%<*package>
%    \begin{macrocode}
\RequirePackage{iftex}
\RequireLuaTeX
\RequirePackage{luacode}
%    \end{macrocode}
% \begin{variable}{\mytl}
%   A variable
%    \begin{macrocode}
\tl_new:N \mytl
%    \end{macrocode}
% \end{variable}
% \begin{environment}{luacode}
%    \begin{macrocode}
\begin{luacode}
function justdoit()
    tex.print(1,[[Test]])
end
\end{luacode}
%    \end{macrocode}
% \end{environment}
% \begin{macro}{\justdoit}
%    \begin{macrocode}
\NewDocumentCommand{\justdoit}{}{
    \directlua{justdoit()}
}
%    \end{macrocode}
% \end{macro}
%</package>
% \end{implementation}
% \Finale
\endinput

更新：以下是示例输出：

预览

答案1

这里有一些建议，可以统一变量和宏的样式，将外观转移到使用实现的布局，并找到在文档中标记代码\DescribeEnv的方法。Lual3doc

  • 统一变量和宏的样式：

为了统一变量和宏的样式，您可以自定义环境。您可以通过修改包本身或基于 创建新的包（或类）来l3doc实现这一点。l3docl3doc

例如，您可以定义一个my_macro具有所需风格的新环境：

\ExplSyntaxOn
\NewDocumentEnvironment{my_macro}{m}
  {
    \cs_set_eq:NN \variable \meta
    \begin{macro}{#1}
  }
  {
    \end{macro}
    \cs_set_eq:NN \variable \gobble
  }
\ExplSyntaxOff

然后，你就可以在代码中使用该my_macro环境来代替环境了。这个新环境将具有与环境相同的样式。macrovariable

  • 将外观转移到通过以下方式实现的布局\DescribeEnv：

要将变量或宏的外观转移到使用 实现的布局\DescribeEnv，您可以重新定义\DescribeEnv命令以使用与变量或宏相同的样式：

\ExplSyntaxOn
\cs_set_eq:NN \original_describe_env: \DescribeEnv
\cs_new_protected:Npn \new_describe_env: #1
  {
    \cs_set_eq:NN \environment \meta
    \original_describe_env: { #1 }
    \cs_set_eq:NN \environment \gobble
  }
\cs_set_eq:NN \DescribeEnv \new_describe_env:
\ExplSyntaxOff

此代码将命令重新定义为具有与和环境\DescribeEnv相同的样式。variablemy_macro

  • 在文档中标记Lua代码l3doc：

要在文档中标记Lua代码l3doc，您可以使用文档\NewMacroEnvironment中提到的命令l3doc。

此外，您可以使用包提供的luacode或环境来正确格式化和突出显示代码。luaexecluacodeLua

\NewMacroEnvironment以下是与环境一起使用的示例luacode：

\NewMacroEnvironment{luacode} % or luaexec, depending on your preference

luacode现在您可以在文档中使用该环境，并且它将被正确格式化和突出显示。

这些变化应该可以帮助您自定义变量、宏和环境的外观，以及标记文档Lua中的代码l3doc。

相关内容