Formateo de mensajes de uso

Question

Si echa un vistazo al paquete Combinatorica en Mathematica8 en (mathematicapath)/AddOns/LegacyPackages/DiscreteMath/Combinatorica.m, encontrará las definiciones de funciones. Lo que me interesa saber es cómo Mathematica sabe cómo formatear los mensajes de uso. Algo me dice que no estoy mirando el archivo correcto. En cualquier caso, intentemos lo siguiente:

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

Esta línea es la línea 682 en el archivo mencionado anteriormente. Ahora si lo ejecutamos en un cuaderno matemático y usamos ?Cofactor, veremos exactamente el mismo mensaje. Pero si obtenemos el paquete, entonces el mensaje está formateado. Aquí es una captura de pantalla:

Aviso cómo el m, i y j dentro de la función cambiado y una flecha doble se añadió al mensaje. Creo que la flecha se agregó al mensaje porque existe documentación para ello. ¿Alguien puede explicar este comportamiento?

---

EDIT: Esta es una captura de pantalla de mi archivo de cuaderno que autosaves a un archivo m.

Como se puede ver, el L y M son en tiempos cursiva romana nueva. Ahora cargaré el paquete y veré el uso.

Hasta aquí todo bien. Ahora veamos el centro de documentación. Buscaré la función LineDistance.

Como se puede ver, se muestra un mensaje extraño. En este caso, solo queremos mostrar el mensaje sin ningún estilo. Todavía no puedo entender cómo lo hace el paquete Combinatorica. Seguí this para hacer el índice para que el centro de documentación pueda mostrar el resumen. El resumen es esencialmente la pantalla de uso. Avíseme si necesito ser más específico.

Answer 1

OK, aquí está la explicación.

de excavación en la fuente Combinatorica revela esto: mensajes

(* 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; 
] 

Se carga desde ToFileName[{System`Private`$MessagesDir,$Language},"Usage.m"], que en mi máquina es SystemFiles\Kernel\TextResources\English\Usage.m.Esta es la razón por la cual todos los mensajes de uso se crean condicionalmente en Combinatorica.m (solo si aún no existen). Si miras en Usage.m verás que tiene todas las cosas feas que @ragfield mencionó.

Supongo que la forma más sencilla de tener mensajes formateados es editarlos en el anverso de un cuaderno y crear un paquete de guardado automático. De esta forma puede usar todas las herramientas de formateo del front-end, y no necesitará lidiar con cuadros.

Answer 2

La forma de incrustar información de estilo en una expresión String es usar sintaxis lineal. Para una expresión cuadro tales como:

StyleBox["foo", FontSlant->Italic] 

puede incrustar esto dentro de una cadena mediante la adición de \* al frente de ella y escapar caracteres especiales tales como cotizaciones:

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

Esto debería funcionar para cualquier expresión de cuadro, sin importar lo complicado:

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

Answer 3

Voy a responder sobre cómo se genera el enlace en el Message. Trazando Message impresión muestra una llamada a indocumentado función Documentation`CreateMessageLink que devuelve la URL de la página de documentación correspondiente si existe esta página:

Trace[Information[Sin], Documentation`CreateMessageLink] 

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

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

En algunos casos también podemos ver las llamadas a Internal`MessageButtonHandler que más llamadas Documentation`CreateMessageLink:

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

Answer 4

Actualmente estoy trabajando en la reescritura de su ApplicationMaker para nuevas versiones de Mathematica con funcionalidades adicionales y llegué exactamente a la misma pregunta aquí.

Mi respuesta es simple: Mathematica no te permite usar resúmenes formateados para tus símbolos (o incluso construir en símbolos), así que tenemos que dar formato a las cadenas de uso para los resúmenes. La propia cadena de datos puede tener formato, pero se necesita una función que elimine todas las cajas de formateo de una cadena.

Tengo una solución que utiliza el UndocumentedTestFEParserPacket según lo descrito por John Fultz! en this pregunta.

Esta herramienta con nombre divertido analiza una entrada de cadena en el cuadro de cuadro de Mathematica real sin cambios.

Este es mi código de ejemplo:

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"}] 

y esta es la forma en la salida se parece a (primera salida con formato de lujo str0, segundo plano simple str2)

Código Explicación:

str0 es la cadena de caracteres formateada con todos los StyleBoxes y otros cuadros de formato.

str1:

UndocumentedTestFEParserPacket[str0, True] da Cajas y se despoja de todas StyleBoxes, eso es debido a que el segundo argumento es verdadera. First Replacement elimina todos RowBoxes. El BoxForm externo cambió a una lista de cadenas. Los espacios en blanco se insertan entre estas cadenas por Riffle. SubscriptBox recibe un tratamiento especial. La última línea reemplaza a todos los FormatBox restantes, como UnderoverscriptBox y lo hace al agregar espacios en blanco entre los argumentos, y devolver los argumentos como una secuencia plana.

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

se añadió para incluir más casos, como StringReplace::usage.Estos casos incluyen representaciones de cadena "" con Estilos dentro de una serie de uso, cuando "args" se debe dar como cadenas.

str2:

En este bloque de código que sólo quitar indeseado WhitespaceCharacter de la cadena str1 y añadir saltos de línea después de la "/n"".", ya que se perdieron durante el análisis. Hay 3 casos diferentes en los que se puede eliminar WhitespaceCharacter. 1 eliminando los lados izquierdo y derecho WithespaceCharacter de un carácter como "[". 2. y 3. eliminar WithespaceCharacter del lado izquierdo (2) o derecho (3).

Resumen

Istead de summary-> mySymbol::usage, utilice summary -> unformatString[mySymbol::usage] con unformatString ser una función apropiada que performes la unformating como descriped anteriormente.

alternativa, se puede definir otro mensaje de uso manual como

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

de uso Resumen -> MySymbol :: usage2