格式化使用消息

Question

如果你看一下Combinatorica中 Mathematica8 中的(mathematicapath)/AddOns/LegacyPackages/DiscreteMath/Combinatorica.m包，你会发现函数的定义。我有兴趣知道的是Mathematica如何知道如何格式化使用信息。有些东西告诉我，我没有看正确的文件。无论如何，让我们尝试以下方法：

Cofactor::usage = "Cofactor[m, {i, j}] calculates the (i, j)th cofactor of matrix m."

这一行是上述文件中的682行。现在，如果我们在mathematica笔记本中运行它并使用?Cofactor，我们将看到完全相同的消息。但是如果我们得到包，那么消息就被格式化了。这是一个截图：

注意函数中的m，i和j是如何更改的，并且在消息中添加了一个双箭头。我认为箭头已添加到邮件中，因为它存在文档。有人可以解释这种行为吗？

---

编辑： 这是我的笔记本文件的屏幕截图，它自动保存到m文件。

如您所见，L和M以新罗马字体显示为斜体。现在我将加载包并查看用法。

到目前为止一切顺利。现在让我们看一下文档中心。我将查找函数LineDistance。

如您所见，它显示了一个奇怪的消息。在这种情况下，我们只想显示没有任何样式的消息。我仍然无法弄清楚Combinatorica包是如何做到这一点的。 我按照this制作了索引，以便文档中心可以显示摘要。摘要本质上是使用显示。如果我需要更具体，请告诉我。

Answer 1

我将回答如何生成Message中的链接。跟踪Message打印显示对未记录的Documentation`CreateMessageLink函数的调用，如果此页存在，则将URL返回到相应的文档页面：

Trace[Information[Sin], Documentation`CreateMessageLink]

In[32]:= Documentation`CreateMessageLink["System", "Sin", "argx", "English"]

Out[32]= "paclet:ref/message/General/argx"

在某些情况下，我们还可以看到Internal`MessageButtonHandler的来电，进一步调用Documentation`CreateMessageLink：

Trace[Message[Sin::argx, 1, 1], 
 Internal`MessageButtonHandler | Documentation`CreateMessageLink, 
 TraceInternal -> True]

Answer 2

在String表达式中嵌入样式信息的方法是使用线性语法。对于框表达式，例如：

StyleBox["foo", FontSlant->Italic]

您可以通过在其前面添加\*并转义任何特殊字符（例如引号）来将其嵌入字符串中：

"blah \*StyleBox[\"foo\", FontSlant->Italic] blah"

这适用于任何框表达式，无论多么复杂：

"blah \*RowBox[{SubsuperscriptBox[\"\[Integral]\",\"0\",\"1\"],RowBox[{FractionBox[\"1\",RowBox[{\"x\",\"+\",\"1\"}]],RowBox[{\"\[DifferentialD]\",\"x\"}]}]}] blah"

Answer 3

好的，这是解释。

挖掘Combinatorica来源揭示了这一点：

(* get formatted Combinatorica messages, except for special cases *)
If[FileType[ToFileName[{System`Private`$MessagesDir,$Language},"Usage.m"]]===File,
Select[FindList[ToFileName[{System`Private`$MessagesDir,$Language},"Usage.m"],"Combinatorica`"],
StringMatchQ[#,StartOfString~~"Combinatorica`*"]&&
!StringMatchQ[#,"Combinatorica`"~~("EdgeColor"|"Path"|"Thin"|"Thick"|"Star"|"RandomInteger")~~__]&]//ToExpression;
]

正在加载来自ToFileName[{System`Private`$MessagesDir,$Language},"Usage.m"]的邮件，该邮件在我的计算机上为SystemFiles\Kernel\TextResources\English\Usage.m。这就是为什么所有使用消息都是在Combinatorica.m中有条件地创建的（仅当它们尚不存在时）。如果你查看Usage.m，你会发现它有@ragfield提到的所有丑陋的盒子。

我想最简单的格式化消息的方法是在笔记本中的前端编辑它们，并创建一个自动保存包。这样您就可以使用所有前端的格式化工具，而不需要处理框。

Answer 4

我目前正在为更新的Mathematica-Versions重新编写ApplicationMaker并添加了更多功能，并在此处提出了完全相同的问题。

我的回答很简单：Mathematica不允许您为符号使用格式化摘要（甚至构建符号），因此我们必须取消格式化摘要的用法字符串。 usagestring本身仍然可以有格式，但是需要有一个函数可以从字符串中删除所有格式化框。

我有一个使用John Fultz描述的UndocumentedTestFEParserPacket的解决方案！在this问题中。

这个有趣的命名工具将字符串输入解析为真正未改变的Mathematica BoxForm。

这是我的示例代码：

str0 = Sum::usage

str1=StringJoin[ToString[StringReplace[#, "\\\"" -> "\""]]& /@
(Riffle[MathLink`CallFrontEnd[
FrontEnd`UndocumentedTestFEParserPacket[str0, True]]〚1〛
//. RowBox[{seq___}] :> seq /. BoxData -> List, " "]
/. SubscriptBox[a_, b_] :> a<>"_"<>b
/. Except[List, _Symbol][args__] :> Sequence@@Riffle[{args}, " "])];

str2 = Fold[StringReplace, str1, 
{((WhitespaceCharacter...)~~br:("["|"("|"=") ~~ (WhitespaceCharacter ...)) :> br,
((WhitespaceCharacter ...) ~~ br:("]"|"}"|","|".")) :> br, 
(br:("{") ~~ (WhitespaceCharacter ...)) :> br, 
". " ~~ Except[EndOfString] -> ". \n"}]

这就是输出的样子（第一个输出格式化的花式str0，第二个简单的平面str2）

代码说明：

str0 是带有所有StyleBox和其他格式框的格式化usagestring。

STR1 ：

UndocumentedTestFEParserPacket[str0, True]给出Box并剥离所有StyleBoxes，因为第二个参数为True。 First Replacement删除所有RowBoxes。外部BoxForm已更改为字符串列表。通过Riffle在这些字符串之间插入空格。 SubscriptBox得到了特殊处理。最后一行替换了每个剩余的FormatBox，例如UnderoverscriptBox，它通过在参数之间添加空格，并将参数作为平面序列返回来实现。

ToString[StringReplace[#, "\\\"" -> "\""]]& /@

添加了

以包含更多案例，例如StringReplace::usage。这种情况包括字符串表示""，其中样式在使用字符串中，当"args"必须作为字符串给出时。

STR2 ：

在此代码块中，我只从字符串str1中删除不需要的WhitespaceCharacter，然后在"/n"之后添加换行符"."，因为它们在解析过程中丢失了。有3种不同的情况可以删除WhitespaceCharacter。 1从WithespaceCharacter等字符中删除左侧和右侧"["。 2.和3.从左（2）或右（3）侧删除WithespaceCharacter。

<强>摘要

不论是summary-> mySymbol::usage，使用summary -> unformatString[mySymbol::usage] unformatString是一个适当的函数，可以执行上述描述的格式化。

或者，您可以手动定义另一个用法消息，如

f::usage = "fancy string with formating";
f::usage2 = "flat string without formating";

比使用摘要 - ＆gt; mySymbol :: usage2