adding a new <code language="foo">

Topics: Developer Forum, User Forum
Oct 16, 2012 at 7:53 AM

I haven't been able to find any information on how to add a new language (custom DSL). Is this possible by editing the xslt transformations? Is there a good way to do this without having to move my modified xslt transformations to other machines?

Thanks for any help

Oct 16, 2012 at 3:10 PM

If it's just colorization, there is a rules file in the SHFB installation folder (Colorizer\highlight.xml) that defines how the languages are colorized.  If you didn't want to modify the default file, you could include a copy in your project, modify it to suit your needs, add the CodeBlockComponent to the project using the Component Configurations project property, and modify the configuration to tell it to use your custom rule file.

For deeper integration of the language into the presentation style such as adding language filter and syntax section support you'll need to modify the presentation style XSL transformations, modify the supporting script files, and write a syntax component that generates the XML for the syntax section.



Oct 17, 2012 at 8:20 AM

Great, thank you!

What would I have to do to get a header (like C# or XML) over the code example with a custom name? 

A related question, is there any support for automatically indenting the code examples, by running them through an external program? As mentioned I need to use CDATA, and I'd prefer not to have to worry about keeping indentation correct in the MAML source files.


Thanks for the swift answers!

Oct 17, 2012 at 7:26 PM
Edited Oct 17, 2012 at 7:27 PM

In the current relase, the CodeBlockComponent will use the information from the highlight.xml file to add a default title based on the language name if another title is not supplied.  I'm in the process of simplifying how the component works and pushing title support into the XSL transformations so that will change slightly in the next release.

The component will only colorize the code, it won't fix up the indentation for you apart from converting tabs to a given number of spaces based on the rules in the highlight.xml file and standardizing the common amount of leading whitespace across all lines.  How it appears in the XML comments or in the MAML topic is pretty much how it will appear in the rendered topic.  There are no components available for Sandcastle that will reformat the indentation but that's not to say you or someone else couldn't write one if so inclined.



Oct 18, 2012 at 7:28 AM
Edited Oct 18, 2012 at 7:32 AM

great, i now have basic syntax highlighting! however, i don't see a title, even though i have the name attribute set on my language in highlight.xml (and the highlighting colors for keywords etc. work fine). is there anything i can look at to find out why i don't get a title? edit: what i mean is the thing called CodeSnippetContainerTab in the html output

a related question, is there any support for inline code blocks? <codeInline> doesn't highlight anything, it would be nice to have a way to specify inline highlighting.

how would i go about adding basic auto-indentation support? there's no way to call an external tool from inside an xslt transform, is there?

for xml, setting the attribute INDENT="yes" on the xsl output might work nicely.

Oct 18, 2012 at 7:33 PM

Are you using the VS2010 style?  As I recall, it has it's own method of determining the language name for the tab so it may not work there without changes to the codeTemplates.xsl transformation.  Colorizing inline code has never come up before that I recall.  I suspect it's mostly used for single keywords and the default style applied to the content is sufficient enough that it hasn't bothered anyone before.  The existing CodeBlockComponent could probably be extended to support it or a derived version that handles inline elements could be created.

Regarding indentation, as I mentioned, you'd have to create a build component to do it.  Turning on indentation on the XSL output won't work as the content at that point is not in a state that could be indented properly.  For one, it's got the colorization elements mixed in and, even with colorization disabled, the content is encoded so it's effectively a text element, not XML by the time the topic is ready to be output.  Indentation would have to occur pre-colorization and pre-transformation.  The only way to do that is with another build component.  A simpler approach may be to manage the XML in an external file where an editor can enforce proper indentation and use the source and region attributes to import the approriate file or part of it into the code block if proper indentation is a concern.  For small blocks of a few lines, managing the indentation doesn't seem to be much of an issue and it may not be worth the effort of a build component.



Oct 24, 2012 at 10:38 AM

Thank you again, this worked very well! I now have most things we wanted, great to get so much help from you!

I found one more thing that seems to be a problem, I've been trying to add a language EBNF (for grammars), by defining the following keywords (to be highlighted in some colour) in highlight.xml:

= | { } [ ] * + .

These don't work so well, I don't get an error, but no content is generated either. I tried replacing them by &#nn; too, no luck. Is there a way to make this work, or are these just not "keywords" :)

Greetings, Peter

Oct 24, 2012 at 3:04 PM

Many of them are regular expression characters so you probably need to escape them in the expression.  For example:

<regexp id="EBNFChars" attribute="keyword" context="code" expression="[=\|{}\[\]\*\+\.]" />