☰

Как создать шаблонный файл dtx для пакета с использованием LaTeX3 (аналогично dtxgen для LaTeX2e)

tag-icon • tag-icon expl3 latex3 dtx
Как создать шаблонный файл dtx для пакета с использованием LaTeX3 (аналогично dtxgen для LaTeX2e)

Я заинтересован в создании пакета с использованием LaTeX3, но я не могу (а) найти документацию о том, как сгенерировать для него новый файл dtx или (б) найти шаблон для создания файла dtx для пакета с использованием LaTeX3 (вероятно, с использованием l3doc).

Есть ли утилита (например, dtxgenдля LaTeX2e) или шаблон для пакетов LaTeX3?

Пример того, что мне нужно.

При создании пакета LaTeX (например mynewpackage), мой первый шаг обычно заключается в запуске

$ dtxgen mynewpackage.sty

Что создает Makefileи mynewpackage.dtx(среди других файлов). По умолчанию это использует docstrip и использует класс ltxdocдля документации. Оба они хороши, но LaTeX3 вносит несколько изменений, включая:

  • Использование l3docstripдля введения новых функций, таких как @@замена на __<module name>(получено из expl3.pdfизhttps://www.ctan.org/pkg/l3kernel)
  • Использует \ProvidesExplPackageвместо \ProvidesPackage(получено отНаписать новый пакет с LaTeX2e или LaTeX3)
  • Использование l3docкласса вместо ltxdoc(кажется, это имеет смысл, поскольку он поддерживает четкое документирование функций LaTeX3)

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

Существует ли скрипт для создания исходного файла dtx со всеми рекомендуемыми изменениями для LaTeX3 и/или место, где задокументированы все необходимые изменения?

решение1

Я бы рекомендовал использовать простую структуру, в которой есть:

  • Один или несколько .dtxфайлов
  • Один .insфайл
  • README.md
  • Файл CHANGELOG.ms(см.https://keepachangelog.com/en/1.0.0/)
  • (Возможно) LICENSEкак копия LPPL (длянапримерGitHub)

и для больших пакетов

  • Отдельная .texдля пользователя документация
  • (При использовании нескольких .dtxфайлов) .texФайл для объединения всей документации по коду в один PDF-файл.

Взяв эту модель, .dtxя бы рекомендовал следующее:

% \iffalse meta-comment
%
% File: <NAME>.dtx Copyright (C) <YYYY> <AUTHOR>
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "<NAME> bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% The released version of this bundle is available from CTAN.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    <SOURCE REPO>
%
% for those people who are interested.
%
% -----------------------------------------------------------------------
%
%<*driver>
\documentclass{l3doc}
% The next line is needed so that \GetFileInfo will be able to pick up
% version data
\usepackage{<NAME>}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{<NAME>.sty}
%
% \title{^^A
%   \pkg{<NAME>} -- <DESCRIPTION>^^A
%   \thanks{This file describes \fileversion,
%     last revised \filedate.}^^A
% }
%
% \author{^^A
% <AUTHOR>^^A
%  \thanks{^^A
%    E-mail:
%    \href{mailto:<EMAIL>}
%      {<EMAIL>}^^A
%   }^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
% \begin{documentation}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{<NAME>} implementation}
%
% Start the \pkg{DocStrip} guards.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
%    \begin{macrocode}
%<@@=<PREFIX>>
%    \end{macrocode}
%
% \subsection{Initial set up}
%
% Load the essential support (\pkg{expl3}) \enquote{up-front}.
%    \begin{macrocode}
\RequirePackage{expl3}
%    \end{macrocode}
%
% Make sure that the version of \pkg{l3kernel} in use is sufficiently new.
%    \begin{macrocode}
\@ifpackagelater {expl3}{<MINIMUM DATE>}
  {}
  {%
    \PackageError {<NAME>} {Support package expl3 too old}
      {%
        You need to update your installation of the bundles 'l3kernel' and
        'l3packages'.\MessageBreak
        Loading~<NAME>~will~abort!%
      }%
    \endinput
  }%
%    \end{macrocode}
%
% Identify the package and give the over all version information.
%    \begin{macrocode}
\ProvidesExplPackage {<NAME>} {<DATE>} {<VERSION>}
  {<DESCRIPTION>}
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex

Выше я предположил, что у нас есть один исходный файл (пакет меньшего размера): более крупный пакет будет загружен expl3только один раз.

Опять же, для более крупных источников я бы разделил @@соглашение на подчасти, так чтобы каждая .dtxбыла самодостаточной. См. напримерhttps://github.com/josephwright/siunitxдля примера.

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