☰

Problema de índice al usar l3doc para escribir documentos LaTeX

tag-icon • tag-icon indexing latex3 documentation
Problema de índice al usar l3doc para escribir documentos LaTeX

Yo suelo l3docescribir documentos para mi paquete. En el documento necesito describir macros, entornos y opciones del paquete. Empecé a utilizar functionúnicamente el entorno. Después de que llegara el consejo de @egreg (¡Gracias!), encontré el entorno environment. Como no he encontrado el documento para l3doc. Me encuentro con más problemas. Aquí hay un ejemplo:

\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}

Lo compilo usando el siguiente comando:

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

El resultado se ve así: resultado

Hay varios problemas:

  1. Puedes ver que la entrada envse repite dos veces.
  2. El número de página de la entrada enves incorrecto.
  3. La entrada optdebe indexarse ​​en Olugar de P. Como es una opción, no un entorno, no puedo usarlo environment. Necesito syntax.

Gracias por cualquier ayuda.

Respuesta1

El problema es que l3docen realidad es algo interno al proyecto y no es realmente lo que consideramos estable o adecuadamente documentado. En resumen, es un montón de trucos y complementos para la documentación con los que experimentamos y encontramos útiles para nuestras propias cosas. pero nunca logré finalizar y redactar una documentación adecuada para ello.

Puede acceder a la documentación que está allí mediante composición tipográfica, l3doc.dtxpero luego verá lo que quiero decir: no todo está documentado en la interfaz de usuario y el código en gran medida no contiene comentarios ni información adicional. Sin embargo, podría brindarle información adicional, pero tenga en cuenta que podemos cambiar o agregar a estas interfaces.

En cuanto a sus problemas anteriores: l3doc.isttiene/tuvo un error al configurar el nivel de nivel, sin #embargo, el código todavía asume un nivel de nivel de >. Internamente hemos dejado de usarlo l3doc.isty en su lugar usamos gind.istla distribución LaTeX2e. Si usa esto, o corrige el nivel, l3doc.istverá que la enventrada sale correctamente, todavía habrá 2 entradas, pero una es una subentrada bajo el encabezado principal "entornos".

En cuanto al problema con opt: usas functionpero ese es solo para comandos y simplemente elimina el primer carácter para fines de clasificación, asumiendo que es una barra invertida; por lo tanto, su entrada se ordena bajo el segundo carácter, que es "p". No tienes suerte, no tenemos un entorno para documentar opciones.

Por el momento hay \DescribeOptionun comando, pero eso es todo y no estamos seguros de que éste sobreviva a versiones posteriores.

Actualizar

Me acabo de dar cuenta de que no respondí la segunda pregunta: "¿Por qué se envmuestra el número de página "1" en lugar de 2?"

Bueno, no lo es, muestra un número de línea de código de 1 (dígito vertical), no un número de página que utiliza la docconvención de paquete predeterminada. En otras palabras, esto fue pensado como un entorno de documentación de código y no como un entorno de descripción de interfaz de usuario.

Básicamente un defecto (si no un error) que nos lleva de vuelta al punto de que este no es realmente un producto terminado... pero queda claro que probablemente deberíamos hacer algo al respecto.

información relacionada