l3doc добавляет нежелательный обратный слеш в поле поля {function}

Question

Я использую его l3docдля документирования некоторых пакетов (я знаю, что он официально нестабилен, но мне нравится…). Я столкнулся с проблемой, которая {function}{<list>}добавляет обратную косую черту для каждого элемента, <list>если один из элементов является макросом, начинающимся с обратной косой черты.

\documentclass{l3doc}

\begin{document}

\begin{function}{{environment}}
Description
\end{function}
\begin{function}{\command}
Description
\end{function}
\begin{variable}{counter}
Description
\end{variable}
\begin{function}{{environmentII}, counterII, \commandII}
Description for multiple items
\end{function}

\begin{macro}{{environment}}
Definition
\end{macro}
\begin{macro}{\command}
Definition
\end{macro}
\begin{macro}{counter}
Definition
\end{macro}
\begin{macro}{{environmentII}, counterII, \commandII}
Description for multiple items
\end{macro}

\end{document}

Пример показывает, что использование одного элемента <list>работает так, как и ожидалось, но как только я добавляю макрос в список, все элементыобратная косая черта. {macro}не демонстрирует такого поведения …

Есть ли способ предотвратить это?

Answer 1

Мне кажется, что вы просто неправильно используете окружение. Ожидаемый аргумент — это либо функция, либо список функций. Но ни один из элементов в списке, который вы передаете, не является функцией в смысле l3. (Но окружениеможетбыть предназначены также для команд уровня документа - см. ниже. В этом случае,некоторый(Из передаваемых вами вещей есть функции, но не другие.)

Обратите внимание, что даже в тех случаях, когда вы говорите, что это работает так, как и ожидалось, вы не получаете элементы, отформатированные последовательно. Например, вы получаете counterформатирование шрифтом serif, а не пишущей машинкой, потому что это не выглядит как переменная для парсера. ( \l_tobi_counter_intпредположительно, сработает здесь и является эквивалентом l3.)

Код, который определяет различные среды, предоставляемыеl3docобрабатывает аргументы в соответствии с ожидаемым синтаксисом для типов вещей, которые среда предназначена документировать.

Так, например, functionсреда ищет :в каждом элементе списка, разделенного запятыми, чтобы отделить имя от спецификации его аргументов. Затем эта информация автоматически обрабатывается и форматируется стандартным образом.

Например,

\begin{function}{\Tobi_function_one:nn, \Tobi_function_one:Vn, \Tobi_function_one:VV}
Description for multiple items
\end{function}

определит, что имеет дело с тремя вариантами одной и той же функции, т.е. случаями, когда варианты базовой функции были сгенерированы обычным способом. Затем он отформатирует первый вариант как базовый, а оставшиеся два как варианты, объединив их и выделив их различные спецификаторы аргументов.

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

Я не совсем уверен, macroдля чего его следует использовать. Я не могу найти достаточно документации дляl3docи я не смог понять из источника документации по l3, в чем именно заключается это различие.

Моя первая мысль была, что это macroможет быть предназначено для команд на уровне документа, но, несмотря на то, что я сказал выше,xparse's документация использует functionдля документирования команд уровня документа. Это сбивает меня с толку, потому что я не думал, что эти команды былифункциивообще. Я думал, что это часть идеи в различении вещей на уровне документа от вещей на более низком уровне l3, и что «функции» применяются только к последним. Но я, очевидно, ошибаюсь на этот счет. (И, конечно, это macroне обязательно будет иметь большой смысл, поскольку функции, безусловно, являются макросами.)

Вот пример кода, с которым я экспериментировал.

\documentclass{l3doc}
\begin{document}
\begin{function}{\Tobi_function_prior:n}
  Description
\end{function}
\begin{function}{\command:}
  Description
\end{function}
\begin{variable}{\l_Tobi_variable_tl}
  Description
\end{variable}
\begin{function}{\Tobi_function_one:nn, \Tobi_function_one:Vn, \Tobi_function_one:VV}
  Description for multiple items
\end{function}
\begin{function}{\TobiDocumentCommand}
  \begin{syntax}
    \cs{TobiDocumentCommand}\marg{mandatory argument}
  \end{syntax}
\end{function}
\end{document}