☰

Проблема с индексом при использовании l3doc для написания документов LaTeX

tag-icon • tag-icon indexing latex3 documentation
Проблема с индексом при использовании l3doc для написания документов LaTeX

Я использую l3docдля написания документа для своего пакета. В документе мне нужно описать макросы, окружения и опции пакета. Я начал использовать functionтолько окружение. После того, как @egreg дал мне совет (Спасибо!), я нашел окружение environment. Поскольку я не нашел документ для l3doc. Я столкнулся с еще большими проблемами. Вот пример:

\documentclass{l3doc}
\usepackage{lipsum} % to generate some text

\begin{document}

\lipsum

\begin{function}{\macro}
this is a macro.
\end{function}

\begin{environment}{env}
this is an env.
\end{environment}

\begin{function}{opt}
\begin{syntax}
    opt = \meta{a}
\end{syntax}
this is an opt.
\end{function}

\PrintIndex

\end{document}

Я компилирую его с помощью команды ниже:

pdflatex example
makeindex -s l3doc.ist example
pdflatex example
pdflatex example

Результат выглядит так: результат

Есть несколько проблем:

  1. Вы видите, что запись envповторяется дважды.
  2. Номер страницы записи envневерен.
  3. Запись optдолжна быть проиндексирована под , Oа не под P. Поскольку это опция, а не среда, я не могу использовать environment. Мне нужно syntax.

Спасибо за любую помощь.

решение1

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

Вы можете получить доступ к документации, которая там есть, набрав текст l3doc.dtx, но затем вы поймете, что я имею в виду: не все документировано в пользовательском интерфейсе, и код в основном без комментариев или дополнительной информации. Тем не менее, это может дать вам некоторую дополнительную информацию, но имейте в виду, что мы можем изменить или добавить эти интерфейсы.

Что касается ваших проблем выше: l3doc.istесть/была ошибка, так как он устанавливал levelchar в , #однако код все еще предполагает levelchar в >. Внутри себя мы прекратили использовать l3doc.istи вместо этого используем gind.istиз дистрибутива LaTeX2e. Если вы используете это или исправите levelchar в , l3doc.istвы увидите, что envзапись выходит правильно, все еще будет 2 записи, но одна из них будет подзаписью под основным заголовком "среды".

Что касается проблемы с opt: вы используете , functionно это только для команд, и он просто удаляет первый символ для сортировки, предполагая, что это обратная косая черта; таким образом, ваша запись сортируется по второму символу, который является "p". Вам не повезло, у нас нет среды для документирования опций.

На данный момент есть \DescribeOptionкоманда, но это все, и мы не уверены, что она переживет последующие релизы.

Обновлять

Я только что понял, что не ответил на второй вопрос: «Почему отображается envномер страницы «1», а не «2»?»

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

По сути, это недостаток (если не ошибка), который возвращает нас к мысли, что это на самом деле не готовый продукт... но становится ясно, что нам, вероятно, следует что-то с этим сделать.

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