我正在寻找一种方法来在源代码和输出文件中获得宏签名(可能不是正确的措辞,但我的意思是与函数签名相同)的可读文档。
可以使用例如\cmd
ltxdoc 包中的命令来打印宏签名,例如
\cmd{\myCommand[my optional argument]{my mandatory argument}}
源代码非常易读,但打印结果如下
\myCommand[my optional argument]my mandatory argument
在输出文件中。当然,这可以改为
\cmd{\myCommand[my optional argument]\{my mandatory argument\}}
打印为
\myCommand[my optional argument]{my mandatory argument}
但源代码的可读性会降低,特别是当强制参数过多时。ltxdoc 中定义了更多命令,但它们都会降低源代码的可读性,并且不能解决问题。
有没有办法定义一个宏,\command
使其既具有可读的源代码,又具有正确的输出?对于可读的源代码,我认为
\command{\myCommand[my optional argument]{my mandatory argument}}
是首选方法。但是,编写此类宏的所有简单方法都失败了,因为\command
调用时括号已经丢失。
有没有办法在本地更改一些 catcode 或其他内容,以便括号不会丢失?有没有其他巧妙的语法可以在没有有问题的括号的情况下实现可读性?理想情况下,使用 xparse 时,该命令将支持所有可能的定义。
答案1
预期用途ltxdoc
是
\cmd\myCommand\oarg{my optional argument}\marg{my mandatory argument}
还有\parg
图片模式()
参数。
如果您宁愿隐藏\marg
命令那么也许:
\documentclass{ltxdoc}
\def\xcmd#1{%
\cmd#1%
\futurelet\tmp\arglook}
\def\arglook{%
\let\next\relax
\ifx[\tmp\let\next\xoarg\fi
\ifx\bgroup\tmp\let\next\xmarg\fi
\ifx(\tmp\let\next\xparg\fi
\next
}
\def\xoarg[#1]{\oarg{#1}\futurelet\tmp\arglook}
\def\xmarg#1{\marg{#1}\futurelet\tmp\arglook}
\def\xparg(#1){\parg{#1}\futurelet\tmp\arglook}
\begin{document}
\xcmd\myCommand{my optional argument}[my mandatory argument]
\end{document}
这里的关键是使用\futurelet
我可以使用 LaTeX\@ifnextchar
宏,它是具有更多 LaTeX 类语法的包装器\futurelet
,并内置了空格跳过功能,但我担心这里的空格会被删除,因为没有明确的终止符。使用\futurelet
意味着在处理每个参数后,它只会查看下一个字符,看看它是否是,{
[
或者(
特别是换行符会停止扫描。
关键是
\futurelet\tmp\arglook
这定义 为\tmp
以下字符\arglook
\let\tmp=[
没有将其从 token 流中移除,例如,如果在扩展\xcmd
输入的下一位之后,{my arg}
那么 token 流就是
\futurelet\tmp\arglook{my arg}
所以这相当于
\let\tmp={
\arglook{myarg}
请注意如何{
仍然存在以形成一个论证组。
\arglook
不接受参数,但它测试\tmp
发现它等于\lbrace
,所以执行\xmarg
。所以最后
\xmarg{myarg}
被执行并且该组被作为标准参数并且被排版为强制参数。
如果\futurelet
看到了,[
那么类似的序列就会以执行结束
\xoarg[myarg]
就如同\tmp
一样。\let
[
最后,如果 Futurelet 看到任何不存在{
[
或(
\arglook
不执行任何操作的字符,而原始字符仍然在标记流中,则可以在\xcmd
标题之后执行任何需要执行的操作。
答案2
该ydoc-desc
包\Macro
为此提供了一个宏。它接受一个宏名,然后扫描可能的参数。
\Macro\myCommand[<my optional argument>]{<my mandatory argument>}
完整示例:
\documentclass{article}
\usepackage{ydoc-desc}
\optionaloff % otherwise the optional arguments are displayed lighter as the normal text
\begin{document}
My macro \Macro\myCommand[<my optional arguments>]{<my mandatory argument>}
is really nice.
\end{document}
此处添加了特殊角度,并且参数文本为tt
斜体(如果支持)。这基本上与 David 的答案相同,但默认为彩色:
如果您不使用 ,< >
参数描述将采用tt
直立字体,并且不会添加任何角度。\relax
当它后面跟有任何看起来像是进一步参数的东西时,您可能需要在其后添加 。
然而,整个ydoc
软件包仍然处于官方的 alpha 阶段,并且没有太多的用户文档。
答案3
嗯,你当然可以使用\verb|\myCommand[my optional argument]{my mandatory argument}|
,但是你不会得到任何语法高亮。
您还可以使用该minted
包(记得用 调用 (pdf)LaTeX [pdf]latex -shell-escape your-file.tex
)并执行以下操作:
\documentclass{article}
\usepackage{minted}
\begin{document}
This is my command: \mint{latex}|\myCommand[my optional argument]{my mandatory argument}|.
\end{document}
然而,这有一个缺点,就是\myCommand
在一行上进行排版(我猜即使跳过上面和下面)。