☰

如何自訂`l3doc`？

tag-icon • tag-icon doc l3doc
如何自訂`l3doc`？

由於我目前正在編寫一個套件並開始使用dtxformat 我想知道是否有替代類別僅使用doc，所以我開始使用l3doc（因為我使用 expl3 語法）。我對它很滿意，但以下幾點有點煩人：

  1. 我用來variable描述變數和macro描述巨集（因為function應該在文件中而不是在程式碼中使用）。我怎樣才能統一兩者的風格（無論邊距中有或沒有條形，我寧願有它們）？
  2. \DescribeEnv是否可以將這種外觀轉移到使用（也有條形）實現的佈局？
  3. 我應該如何標記包使用的 Lua 代碼？我應該\NewMacroEnvironment按照l3doc文件說明使用嗎？

這個問題不是關於：

  • 更改文檔類ltxdoc或者
  • 切換到另一個類，這會破壞doc功能，但最終可以用於文件。

我實際使用且不滿意的內容（範例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。您可以透過修改l3doc包本身或基於l3doc.

例如，您可以定義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環境來代替環境。macro這個新環境將具有與環境相同的風格variable。

  • 將外觀轉移到透過以下方式實現的佈局\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。

相關內容