24

As I'm currently writing a package and started to use dtx format I wondered if there are alternative classes just using doc, so I started to use l3doc (since I use expl3 syntax). I'm pretty satisfied with it, but the following points are some kind of annoying:

  1. I'm using variable to describe variables and macro to describe macros (since function should be used in documentation not in code). How can I unify the styles of both (either with or without the bars in the margin, I'd rather like to have them)?
  2. Is it possible to transfer this look to the layout achieved with \DescribeEnv (bars too)?
  3. How should I markup Lua code, which is used by the package? Should I use \NewMacroEnvironment as the l3doc documentation states?

This question is not about:

What I actually use and am unsatisfied with (sample dtx file, I have removed package call to avoid providing .ins file):

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

Update: Here's an example output:

preview

1 Answer 1

2

Here are some suggestions to unify the styles of variables and macros, transfer the look to the layout achieved with \DescribeEnv, and find a way to markup Lua code in your l3doc documentation.

  • Unifying the styles of variables and macros:

To unify the styles of both variables and macros, you can customize the l3doc environments. You can achieve this by modifying the l3doc package itself or creating a new package (or class) based on l3doc.

For example, you can define a new environment my_macro with the desired style:

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

Then, you can use the my_macro environment instead of the macro environment in your code. This new environment will have the same style as the variable environment.

  • Transferring the look to the layout achieved with \DescribeEnv:

To transfer the look of variables or macros to the layout achieved with \DescribeEnv, you can redefine the \DescribeEnv command to use the same style as variables or 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

This code redefines the \DescribeEnv command to have the same style as the variable and my_macro environments.

  • Marking up Lua code in the l3doc documentation:

To mark up Lua code in your l3doc documentation, you can use the \NewMacroEnvironment command as mentioned in the l3doc documentation.

Additionally, you can use the luacode or luaexec environments provided by the luacode package to properly format and highlight Lua code.

Here's an example of using \NewMacroEnvironment with the luacode environment:

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

Now you can use the luacode environment in your documentation, and it will be formatted and highlighted correctly.

These changes should help you customize the appearance of variables, macros, and environments, as well as mark up Lua code in your l3doc documentation.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .