☰

Wie passe ich „l3doc“ an?

tag-icon • tag-icon doc l3doc
Wie passe ich „l3doc“ an?

Da ich gerade ein Paket schreibe und angefangen habe, format zu verwenden, dtxhabe ich mich gefragt, ob es alternative Klassen gibt, die einfach verwenden doc, also habe ich angefangen, zu verwenden l3doc(da ich die Syntax von expl3 verwende). Ich bin ziemlich zufrieden damit, aber die folgenden Punkte sind irgendwie ärgerlich:

  1. Ich verwende es, variableum Variablen und macroMakros zu beschreiben (da es functionin der Dokumentation und nicht im Code verwendet werden sollte). Wie kann ich die Stile beider vereinheitlichen (entweder mit oder ohne die Balken am Rand, ich hätte sie lieber)?
  2. Ist es möglich, diese Optik auch auf das mit (auch Balken) erzielte Layout zu übertragen \DescribeEnv?
  3. Wie soll ich den Lua-Code markieren, der vom Paket verwendet wird? Soll ich es so machen, \NewMacroEnvironmentwie es in der l3docDokumentation steht?

Bei dieser Frage geht es nicht um:

  • Ändern der Dokumentklasse vonltxdocoder
  • Wechsel zu einer anderen Klasse, wodurch docdie Funktionalität beeinträchtigt wird, aber eventuell für die Dokumentation verwendet werden könnte.

Was ich tatsächlich verwende und womit ich unzufrieden bin (Beispieldatei dtx, ich habe den Paketaufruf entfernt, um die Bereitstellung .inseiner Datei zu vermeiden):

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

Aktualisieren:Hier ist eine Beispielausgabe:

Vorschau

Antwort1

Hier sind einige Vorschläge, wie Sie die Stile von Variablen und Makros vereinheitlichen, das Erscheinungsbild auf das mit erstellte Layout übertragen \DescribeEnvund eine Möglichkeit finden, LuaCode in Ihrer l3docDokumentation zu markieren.

  • Vereinheitlichung der Stile von Variablen und Makros:

Um die Stile von Variablen und Makros zu vereinheitlichen, können Sie die l3docUmgebungen anpassen. Sie können dies erreichen, indem Sie das l3docPaket selbst ändern oder ein neues Paket (oder eine neue Klasse) basierend auf erstellen l3doc.

Sie können beispielsweise eine neue Umgebung my_macromit dem gewünschten Stil definieren:

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

Anschließend können Sie in Ihrem Code die my_macroUmgebung anstelle der macroUmgebung verwenden. Diese neue Umgebung hat denselben Stil wie die variableUmgebung.

  • Die Übertragung der Optik auf das Layout erfolgt mit \DescribeEnv:

Um das Aussehen von Variablen oder Makros auf das mit erstellte Layout zu übertragen \DescribeEnv, können Sie den \DescribeEnvBefehl so umdefinieren, dass er denselben Stil wie Variablen oder Makros verwendet:

\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

Dieser Code definiert den \DescribeEnvBefehl neu, sodass er denselben Stil wie die Umgebungen variableund hat my_macro.

  • Markieren von LuaCode in der l3docDokumentation:

LuaUm Code in Ihrer Dokumentation zu markieren , können Sie den in der Dokumentation genannten Befehl l3docverwenden .\NewMacroEnvironmentl3doc

Darüber hinaus können Sie die vom Paket bereitgestellten luacodeoder Umgebungen verwenden, um Code richtig zu formatieren und hervorzuheben .luaexecluacodeLua

Hier ist ein Beispiel für die Verwendung \NewMacroEnvironmentmit der luacodeUmgebung:

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

Jetzt können Sie die Umgebung in Ihrer Dokumentation verwenden luacodeund sie wird richtig formatiert und hervorgehoben.

Diese Änderungen sollten Ihnen dabei helfen, das Erscheinungsbild von Variablen, Makros und Umgebungen anzupassen sowie LuaCode in Ihrer l3docDokumentation zu markieren.

verwandte Informationen