私は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
結果は次のようになります。
いくつか問題があります:
- エントリが
env2 回繰り返されていることがわかります。 - エントリのページ番号
envが間違っています。 - エントリはではなく で
optインデックス付けされる必要があります。これは環境ではなくオプションなので、 は使用できません。 が必要です。OPenvironmentsyntax
ご協力いただきありがとうございます。
答え1
問題は、それがl3doc実際にはプロジェクト内部的なものであり、私たちが安定している、または適切に文書化されていると考えるものではないということです。簡単に言うと、それは私たちが実験して自分たちのものに役立つと判断した、文書化のためのハックやアドオンの集まりですが、それを最終的に完成させて適切な文書を作成することには至りませんでした。
タイプセットによって、そこにあるドキュメントにアクセスできますl3doc.dtxが、その場合、私の言っていることがおわかりになるでしょう。ユーザー インターフェイスにすべてが文書化されているわけではなく、コードにはコメントや追加情報がほとんどありません。それでも、追加情報が得られる可能性がありますが、これらのインターフェイスは変更または追加される可能性があることに注意してください。
上記の問題については、l3doc.istlevelchar を に設定していたためバグがありましたが、#コードでは依然として levelchar が であると想定しています>。内部的には の使用を中止しl3doc.ist、代わりにgind.istLaTeX2e ディストリビューションの を使用しています。これを使用するか、 の levelchar を修正すると、エントリが正しく出力されるl3doc.istことがわかりますenv。エントリは 2 つ残っていますが、そのうちの 1 つはメインの見出し「環境」の下のサブエントリになります。
:の問題に関してはopt、 を使用していますfunctionが、これはコマンド専用であり、バックスラッシュであると想定して、ソートの目的で最初の文字を削除するだけです。したがって、エントリは 2 番目の文字である "p" でソートされます。残念ながら、オプションを文書化する環境はありません。
現時点では\DescribeOptionコマンドはありますが、それだけであり、これが後のリリースでも存続するかどうかはわかりません。
アップデート
env2 番目の質問「ページ番号が 2 ではなく「1」と表示されるのはなぜですか?」に答えていないことに気付きました。
いいえ、そうではありません。デフォルトのパッケージ規則を使用して、ページ番号ではなく、コード行番号 1 (縦の数字) が表示されていますdoc。つまり、これはコード ドキュメント環境として意図されており、ユーザー インターフェイスの説明環境として意図されているわけではありません。
基本的には欠陥（バグではないにしても）であり、これは実際には完成品ではないという点に戻りますが、おそらくこれについて何か対処する必要があることは明らかです。