☰

Как настроить `l3doc`?

tag-icon • tag-icon doc l3doc
Как настроить `l3doc`?

Поскольку я сейчас пишу пакет и начал использовать dtxformat, я задался вопросом, есть ли альтернативные классы, использующие только doc, поэтому я начал использовать l3doc(так как я использую синтаксис expl3). Я им вполне доволен, но следующие моменты немного раздражают:

  1. Я использую variableдля описания переменных и macroдля описания макросов (так как они functionдолжны использоваться в документации, а не в коде). Как мне унифицировать стили обоих (с полосами на полях или без них, я бы предпочел, чтобы они были)?
  2. Можно ли перенести этот вид на макет, достигнутый с помощью \DescribeEnv(в том числе и стержней)?
  3. Как мне разметить код Lua, который используется пакетом? Использовать \NewMacroEnvironmentтак, как l3docуказано в документации?

Этот вопрос не о:

  • Изменение класса документаltxdocили
  • переключение на другой класс, что нарушает docфункциональность, но в конечном итоге может быть использовано для документирования.

Что я на самом деле использую и чем не доволен (пример 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. Этого можно добиться, изменив l3docсам пакет или создав новый пакет (или класс) на основе l3doc.

Например, вы можете определить новую среду 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окружение вместо macroокружения в вашем коде. Это новое окружение будет иметь тот же стиль, что и variableокружение.

  • Перенос внешнего вида на макет, достигнутый с помощью \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команду так, чтобы она имела тот же стиль, что variableи my_macroсреды и .

  • Разметка Luaкода в l3docдокументации:

Чтобы разметить Luaкод в l3docдокументации, вы можете использовать \NewMacroEnvironmentкоманду, указанную в l3docдокументации.

Кроме того, вы можете использовать luacodeсреды luaexec, предоставляемые пакетом, luacodeдля правильного форматирования и выделения Luaкода.

Вот пример использования \NewMacroEnvironmentс luacodeокружением:

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

Теперь вы можете использовать luacodeсреду в своей документации, и она будет правильно отформатирована и выделена.

Эти изменения помогут вам настроить внешний вид переменных, макросов и сред, а также разметить Luaкод в вашей l3docдокументации.

Связанный контент