☰

Como personalizar o `l3doc`?

tag-icon • tag-icon doc l3doc
Como personalizar o `l3doc`?

Como atualmente estou escrevendo um pacote e comecei a usar dtxo formato me perguntei se existem classes alternativas apenas usando doc, então comecei a usar l3doc(já que uso a sintaxe expl3). Estou bastante satisfeito com isso, mas os seguintes pontos são meio irritantes:

  1. Estou usando variablepara descrever variáveis ​​e macropara descrever macros (já que functiondevem ser usadas na documentação e não no código). Como posso unificar os estilos de ambos (com ou sem barras na margem, prefiro tê-los)?
  2. É possível transferir esse visual para o layout obtido com \DescribeEnv(barras também)?
  3. Como devo marcar o código Lua, que é usado pelo pacote? Devo usar \NewMacroEnvironmentcomo l3docindica a documentação?

Esta questão não é sobre:

O que eu realmente uso e com o qual não estou satisfeito ( dtxarquivo de exemplo, removi a chamada do pacote para evitar fornecer .inso arquivo):

% \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

Atualizar:Aqui está um exemplo de saída:

visualização

Responder1

Aqui estão algumas sugestões para unificar os estilos de variáveis ​​e macros, transferir a aparência para o layout obtido com \DescribeEnve encontrar uma maneira de marcar Luao código em sua l3docdocumentação.

  • Unificando os estilos de variáveis ​​e macros:

Para unificar os estilos de variáveis ​​e macros, você pode personalizar os l3docambientes. Você pode conseguir isso modificando o l3docpróprio pacote ou criando um novo pacote (ou classe) baseado em l3doc.

Por exemplo, você pode definir um novo ambiente my_macrocom o estilo desejado:

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

Então, você pode usar o my_macroambiente em vez do macroambiente no seu código. Este novo ambiente terá o mesmo estilo do variableambiente.

  • Transferindo a aparência para o layout obtido com \DescribeEnv:

Para transferir a aparência das variáveis ​​ou macros para o layout obtido com \DescribeEnv, você pode redefinir o \DescribeEnvcomando para usar o mesmo estilo das variáveis ​​ou macros:

\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

Este código redefine o \DescribeEnvcomando para ter o mesmo estilo dos ambientes variablee my_macro.

  • Marcando Luacódigo na l3docdocumentação:

Para marcar Luao código em sua l3docdocumentação, você pode usar o \NewMacroEnvironmentcomando mencionado na l3docdocumentação.

Além disso, você pode usar os ambientes luacodeou luaexecfornecidos pelo luacodepacote para formatar e destacar Luao código adequadamente.

Aqui está um exemplo de uso \NewMacroEnvironmentcom o luacodemeio ambiente:

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

Agora você pode usar o luacodeambiente em sua documentação, e ele será formatado e destacado corretamente.

Essas alterações devem ajudá-lo a personalizar a aparência de variáveis, macros e ambientes, bem como marcar Luao código em sua l3docdocumentação.

informação relacionada