Форматирование сообщений об использовании

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 внутри функции и в сообщение была добавлена ​​двойная стрелка.Я думаю, что стрелка была добавлена ​​в сообщение, потому что есть документация для него.Может кто-нибудь объяснить это поведение?

---

РЕДАКТИРОВАТЬ: Это снимок экрана моего файла ноутбука, который автоматически сохраняет в файл м.

Как вы можетевидите, 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

ОК, вот объяснение.

Копания в источнике 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 3

Способ встраивания информации о стиле в строковое выражение заключается в использовании линейного синтаксиса. Для выражения блока, такого как:

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 4

В настоящее время я работаю над переписыванием вашего ApplicationMaker для более новых версий Mathematica с дополнительными функциями и пришел к тому же вопросу здесь.

Мой ответ прост: Mathematica не позволяет вамиспользуйте форматированные сводки для ваших символов (или даже встраивайте символы), поэтому мы должны отформатировать строки использования для сводок.Сама строка использования может по-прежнему иметь форматирование, но нужно иметь функцию, которая удаляет все форматирующие поля из строки.

У меня есть решение, которое использует UndocumentedTestFEParserPacket, как описано Джон Фульц !в этом вопросе.

Этот забавный инструмент с именем анализирует String Input в реальный неизмененный 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 - это форматированная строка использования со всеми стилями и другими полями форматирования.

str1 :

UndocumentedTestFEParserPacket[str0, True] даетУстанавливает и убирает все StyleBoxes, потому что второй аргумент - True.Первая замена удаляет все RowBoxes.Внешний BoxForm изменен на Список строк.Пробелы вставляются между этими строками на Riffle.SubscriptBox получает специальную обработку.Последняя строка заменяет все оставшиеся FormatBox, такие как UnderoverscriptBox, и делает это, добавляя пробелы между аргументами и возвращая аргументы в виде плоской последовательности.

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

было добавлено, чтобы включить больше случаев, таких как StringReplace::usage.К таким случаям относятся строковые представления "" со стилями внутри строки использования, когда "args" должно быть задано в виде строки.

str2 :

InВ этом блоке кода я удаляю только нежелательные WhitespaceCharacter из строки str1 и добавляю разрывы строк "/n" после ".", потому что они потерялись во время анализа.В 3 разных случаях WhitespaceCharacter можно удалить.1 удаление левой и правой стороны WithespaceCharacter от символа, подобного "[".2. и 3. удаление WithespaceCharacter с левой (2) или правой (3) стороны.

Сводка

Переход summary-> mySymbol::usage, используйте summary -> unformatString[mySymbol::usage] с unformatString является подходящей функцией, которая выполняет форматирование, как описано выше.

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

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

, чем использовать сводку -> mySymbol :: creation2