☰

`l3doc` をカスタマイズするにはどうすればいいですか?

tag-icon • tag-icon doc l3doc
`l3doc` をカスタマイズするにはどうすればいいですか?

現在パッケージを書いていてdtxformat を使い始めたのですが、 を使うだけの代替クラスがあるのではないかと思い、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、ドキュメントLua内でコードをマークアップする方法を見つけるための提案をいくつか示しますl3doc。

  • 変数とマクロのスタイルを統一する:

変数とマクロの両方のスタイルを統一するには、環境をカスタマイズします。これは、パッケージ自体を変更するか、に基づいて新しいパッケージ (またはクラス) を作成すること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使用できます。\NewMacroEnvironmentl3doc

さらに、パッケージによって提供されるluacodeまたは環境を使用して、コードを適切にフォーマットおよび強調表示することもできます。luaexecluacodeLua

\NewMacroEnvironment環境で使用する例を次に示しますluacode。

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

luacodeこれで、ドキュメント内で環境を使用できるようになり、正しくフォーマットされ、強調表示されます。

これらの変更により、変数、マクロ、環境の外観をカスタマイズしたり、ドキュメントLua内のコードをマークアップしたりできるようになりますl3doc。

関連情報