HintML

HintML is a DSL intended for formatting the contents of hints (tooltips) and compiler messages.

HintML is based on XML.

Currently the following tags are supported:

• hint - surround a hint text or an embedded hint.
• keyword — highlights the text with the color used for the keywords (the default is blue).
• symbol - describes the symbol. The span-class attribute allows you to specify the name of a span class (used to highlight symbols). The id attribute - allows you to set the symbol id (it is taken from the corresponding symbol property). If id is specified, the nested hint will be displayed for the symbol.
• ref - link (analog of url in HTML) allows you to display a link with some action. Currently two attributes are available: goto and goto line actions. They can be used to navigate through a piece of code. The handler attribute specifies the action, and the optional hint attribute is a tooltip.
• b — bold.
• i — italic.
• u — underline.
• font — font. Attributes: size, face, color.
• code — monospaced font to signify a code block.

To introduce the hint for your symbol you should override the MakeHint method:

declaration MyDeclaration
{
  symbol
  {
    MakeHint = "<keyword>my declaration</keyword> Some <b>text</b>.";
  }
}

You can use the HintML module to make hint code:

namespace Nitra
{
  /// <summary>Utility methods for Hint Markup language.</summary>
  public module HintML
  {
    public GetSymbolId(symbol : DeclarationSymbol) : int
    public XmlEscape(text : string) : string
    public HintMlEscape(this builder : StringBuilder, text : object) : StringBuilder
    public HintMlQuote(this builder : StringBuilder, text : string) : StringBuilder
    public JoinAnd[T](this builder : StringBuilder, elems : Seq[T], converter : StringBuilder * T -> StringBuilder) : StringBuilder
    public HintMlAttr(this builder : StringBuilder, name : string, text : string) : StringBuilder
    public SymbolToHintMlWithSubHint(this builder : StringBuilder, symbol : DeclarationSymbol) : StringBuilder
    public SymbolToHintMl(this builder : StringBuilder, symbol : DeclarationSymbol) : StringBuilder
    public IsRoot(symbol : DeclarationSymbol) : bool { symbol.DeclaredInOpt.IsNone }
    public MakeHintMlPath(this builder : StringBuilder, symbol : DeclarationSymbol, separator : string, needSubhint : bool) : StringBuilder
    public MakeLocations(this builder : StringBuilder, symbol : DeclarationSymbol) : StringBuilder
    public HintMlException(this builder : StringBuilder, exception : Exception) : StringBuilder
  }
}

Example of hint:

<hint><keyword>class</keyword> <symbol span-class="DotNetLang.Namespace" id="9943">Ns1</symbol>.<symbol span-class="Nitra.Language.Type">TypeA</symbol><br/><br/>Location: <ref handler="goto:c:\!\projects\consoleapplication6\consoleapplication6\program.ncs[143,23]" hint="c:\!\projects\consoleapplication6\consoleapplication6\program.ncs(9, 3)">program.ncs(9, 3)</ref>
</hint>

Example of compiler message:

<hint>'TypeA' is an ambiguous reference between <symbol span-class="DotNetLang.Namespace" id="9943">Ns1</symbol>.<symbol span-class="Nitra.Language.Type" id="9944">TypeA</symbol> and <symbol span-class="DotNetLang.Namespace" id="9945">Ns2</symbol>.<symbol span-class="Nitra.Language.Type" id="9946">TypeA</symbol></hint>

Previous examples make the following hint: