☰

¿Cómo personalizar `l3doc`?

tag-icon • tag-icon doc l3doc
¿Cómo personalizar `l3doc`?

Como actualmente estoy escribiendo un paquete y comencé a usar dtxel formato, me preguntaba si hay clases alternativas que solo usan doc, así que comencé a usarlo l3doc(ya que uso la sintaxis expl3). Estoy bastante satisfecho con ello, pero los siguientes puntos son un poco molestos:

  1. Lo estoy usando variablepara describir variables y macromacros (ya que functiondebería usarse en la documentación, no en el código). ¿Cómo puedo unificar los estilos de ambos (ya sea con o sin las barras al margen, prefiero tenerlas)?
  2. ¿Es posible transferir este aspecto al diseño logrado con \DescribeEnv(barras también)?
  3. ¿Cómo debo marcar el código Lua, que utiliza el paquete? ¿Debo utilizar \NewMacroEnvironmentcomo l3docindica la documentación?

Esta pregunta no se trata de:

Lo que realmente uso y con lo que no estoy satisfecho ( dtxarchivo de muestra, eliminé la llamada del paquete para evitar proporcionar .insel archivo):

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

Actualizar:A continuación se muestra un resultado de ejemplo:

avance

Respuesta1

Aquí hay algunas sugerencias para unificar los estilos de variables y macros, transferir la apariencia al diseño logrado con \DescribeEnvy encontrar una manera de marcar Luael código en su l3docdocumentación.

  • Unificando los estilos de variables y macros:

Para unificar los estilos tanto de variables como de macros, puedes personalizar los l3docentornos. Puede lograr esto modificando el l3docpaquete en sí o creando un nuevo paquete (o clase) basado en l3doc.

Por ejemplo, puedes definir un nuevo entorno my_macrocon el estilo deseado:

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

Luego, puedes usar el my_macroentorno en lugar del macroentorno en tu código. Este nuevo entorno tendrá el mismo estilo que el variableentorno.

  • Transfiriendo la apariencia al diseño logrado con \DescribeEnv:

Para transferir el aspecto de las variables o macros al diseño logrado con \DescribeEnv, puede redefinir el \DescribeEnvcomando para usar el mismo estilo que las variables o 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 el \DescribeEnvcomando para que tenga el mismo estilo que los entornos variabley my_macro.

  • Código de marcado Luaen la l3docdocumentación:

Para marcar Luael código en su l3docdocumentación, puede usar el \NewMacroEnvironmentcomando como se menciona en la l3docdocumentación.

Además, puede utilizar los entornos luacodeo luaexecproporcionados por el luacodepaquete para formatear y resaltar Luael código correctamente.

A continuación se muestra un ejemplo de uso \NewMacroEnvironmentcon el luacodemedio ambiente:

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

Ahora puede utilizar el luacodeentorno en su documentación y se formateará y resaltará correctamente.

Estos cambios deberían ayudarle a personalizar la apariencia de variables, macros y entornos, así como a marcar Luael código en su l3docdocumentación.

información relacionada