Adding LaTeX equations

Install the target version of SHFB

Each release of Novacta.Documentation.ShfbTools targets a specific version of SHFB. Such target version always matches the version of the tools.

Make sure that the SHFB version targeted by the tools is currently installed on your host machine.

You can download the required SHFB release here.

Install a full LaTeX distribution

You need a full TeX distribution installed on your host machine. You can find a list of TeX implementations here.

In particular, the Novacta SHFB Latex Tools have been tested using the MiKTeX distribution.

Add the Latex Tools to SHFB

Create a console application targeting the .NET Framework, version 4.6.2. In this tutorial, such application is represented by project LatexToolsInstaller.

Add to your console project a reference to the Novacta.Documentation.ShfbTools NuGet package. Remember that, at present, the tools are versioned as pre-release software. Follow these instructions to include pre-release versions when installing the tools.

Request full administration permissions for the console application: add to the project an app.manifest file as follows.

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <assemblyIdentity version="1.0.0.0" name="MyApplication.app"/>
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
    <security>
      <requestedPrivileges xmlns="urn:schemas-microsoft-com:asm.v3">
        <requestedExecutionLevel level="requireAdministrator" uiAccess="false" />
      </requestedPrivileges>
    </security>
  </trustInfo>

  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
    <application>
    </application>
  </compatibility>
</assembly>

In your Program class, the implementation of method Main should resemble what follows.

using Novacta.Documentation.ShfbTools;
using System;

namespace LatexToolsInstaller
{
    class Program
    {
        static void Main(string[] args)
        {
            // It is assumed that the version of SHFB
            // targeted by the SHFB Tools
            // is installed on the host machine.

            // To install the Latex Tools.
            LatexTools.Install();

            Console.ReadKey();
        }
    }
}

When the application is executed, its console output shows a report signaling if the installation was successful. If failure conditions are reported, please act to remove them and try again.

The Novacta Latex extensions for SHFB

The LatexTools enable the representation of LaTeX equations as images in SHFB documentation topics. Supported image formats are PNG and SVG.

The SVG image file format is not supported for presentation style OpenXml.

The LatexTools extend SHFB via ShfbLatexComponent, which is responsible to build the image representations of the specified equations, and ShfbLatexPlugIn, only needed to support the SVG image file format for the MSHelpViewer help output.

The SHFB LaTeX Component

The ShfbLatexComponent must be added to a documentation project in order to manage LaTeX content in documentation topics.

To such purpose, open the project properties and click on the Components tab. From the list of available components, select the one referred to as LaTeX Component and click the Add button. Now the Latex component is inserted in the list of the components executed during the build process of the documentation project. Such list is showed on the right side of the tab, as exemplified in the following figure.

Once the LaTeX component has been committed for execution, it must be configured. By clicking the Configure button, the following pop-up window will be displayed.

Through that window, configuration options can be set as follows.

The SHFB Latex Plug-In

The ShfbLatexPlugIn must be added to a documentation project only if the project needs to support the SVG image file format for the MSHelpViewer help output.

To do so, open the project properties and click on the Plug-Ins tab. From the list of available plug-ins, select the one referred to as LaTeX Support in MS Help Viewer files - SVG Fix and click the Add button. Now the Latex plug-in is inserted in the list of the plug-ins executed during the build process of the documentation project. The plug-ins committed for execution are listed on the right side of the tab, as exemplified in the following figure.

LaTeX equations can be added to the XML comments on your source code by inserting custom XML elements, referred to as the LaTeX elements.

The start-tag of such elements is <latex>. The basic form of a LaTeX element, i.e. a form with no XML attributes, is as follows.

<latex>X_{(0)}=2^{-1/3}</latex>

When LaTeX elements are processed, their content is interpreted as having document class article, with an option of 10pt for the size of the main font in the document, and the \pagestyle set to empty. You can also assume as available the packages amsmath and amsfonts.

When the default configuration is active and the latex element is in basic form, then its content is interpreted as inserted in a displayed mathematical environment (separated by the main text), and sized applying the \normalsize LaTeX command.

Such behavior can be overridden by adding attributes to the latex element or overriding the default configuration.

If you want a LaTeX formula displayed in-line, that is, within the body of text where it is declared, you can add a mode attribute having the "inline" value, as in the following example.

/// Let us assume that the random variable
/// <latex mode="inline">Y_{i}</latex> has distribution function
/// <latex mode="inline">F_{Y_{i}}</latex>.

If a LaTeX element has no mode attribute, then its mode is set, by default, according to the Default LaTeX mode configuration option.

The Novacta ShfbLatexComponent inserts images in help files to represent your equations. When a LaTeX element is in-lined, then the corresponding image depth is, by default, set according to the Image depth correction configuration option. However, the image depth for a given LaTeX element can be hard coded by adding a depth attribute, as in the following example.

<latex depth="10">F_{Y_{i}}</latex>

In a LaTeX element, the size of the text is controlled, by default, through the Image scale percentage configuration option. However, the size of a given LaTeX element can be overridden by adding to it a scale attribute. For example, if you want its size being the 70% of the basic size, you can write a LaTeX element as follows.

<latex scale="scriptsize">F_{Y_{i}}</latex>

More thoroughly, you can set the value of the scale attribute using any of the predefined values shown in the following table, where the corresponding percentages are also reported.

As an example, the following file printout shows the source code for type IntegerOperation, as defined in project SampleClassLibrary:

 1using System;
 2
 3namespace SampleClassLibrary
 4{
 5    /// <summary>
 6    /// Provides a method to operate on integers.
 7    /// </summary>
 8    public static class IntegerOperation
 9    {
10        /// <summary>
11        /// Applies the specified function to the given operand.
12        /// </summary>
13        /// <param name="func">The function.</param>
14        /// <param name="operand">The operand.</param>
15        /// <returns>The result of the operation.</returns>
16        /// <exception cref="ArgumentNullException">
17        /// <paramref name="func"/> is <b>null</b>.</exception>
18        /// <example>
19        /// <para>
20        /// In the following example, the applied function, say 
21        /// <latex mode='inline'>f:\mathbb{N}\rightarrow \mathbb{N},</latex> is defined as
22        /// <latex mode='display'>
23        /// \forall n \in \mathbb{N}: n \mapsto f\left(n\right)=n^2.
24        /// </latex>
25        /// A plot of such function is displayed in the following
26        /// figure.
27        /// <image>
28        /// <alt>A function.</alt>
29        /// <src>Function.png</src>
30        /// <width>100%</width>
31        /// </image>
32        /// An integer is thus squared 
33        /// executing the <see cref="Operate(Func{int, int}, int)"/> method.
34        /// In addition, input validation is also checked.
35        /// </para>
36        /// <para>
37        /// <code language="cs">
38        /// using System;
39        /// namespace SampleClassLibrary.CodeExamples
40        /// {
41        ///     public class IntegerOperationExample
42        ///     {
43        ///         public void Main()
44        ///         {
45        ///             // Define an operator that squares its operand
46        ///             Func<![CDATA[<]]>int, int> square = (int operand) => operand * operand;
47        /// 
48        ///             // Define an operand
49        ///             int integer = 2;
50        /// 
51        ///             // Operate on it
52        ///             Console.WriteLine("Squaring {0}...", integer);
53        ///             int result = IntegerOperation.Operate(square, integer);
54        ///             Console.WriteLine("...the result is {0}.", result);
55        /// 
56        ///             // Check that an operator cannot be null
57        ///             try
58        ///             {
59        ///                 IntegerOperation.Operate(null, 0);
60        ///             }
61        ///             catch (Exception e)
62        ///             {
63        ///                 Console.WriteLine();
64        ///                 Console.WriteLine("Cannot apply a null function:");
65        ///                 Console.WriteLine(e.Message);
66        ///             }
67        ///         }
68        ///     }
69        /// }
70        ///  
71        /// // Executing method Main() produces the following output:
72        /// // 
73        /// // Squaring 2...
74        /// // ...the result is 4.
75        /// // 
76        /// // Cannot apply a null function:
77        /// // Value cannot be null.
78        /// // Parameter name: func
79        /// </code>
80        /// </para>
81        /// </example>
82        public static int Operate(Func<int, int> func, int operand)
83        {
84            if (func==null)
85            {
86                throw new ArgumentNullException(nameof(func));
87            }
88            return func(operand);
89        }
90    }
91}

Note the LaTeX elements at line 21-24 in the XML comments on method Operate. You can check here how the corresponding documentation looks like.

Elements in MAML conceptual topics must be qualified using a namespace. To qualify LaTeX elements, add to the topic's document element a namespace attribute associated with prefix ltx, as shown in the following example.

<topic id="303c996a-2911-4c08-b492-6496c82b3edb" revisionNumber="1">
  <!-- This element name will change based on the document type -->
  <developerConceptualDocument
    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:ltx="http://www.novacta.net/2018/XSL/ShfbLatexTools">

    <!-- The content goes here -->

  </developerConceptualDocument>
</topic>

Now LaTeX elements can be added by prefixing their tags with ltx, as follows.

<ltx:latex scale="LARGE" mode="inline">X_{(0)}</ltx:latex>

As an example, the following file printout shows the source code for a conceptual topic about IntegerOperation, as defined in project SampleClassLibrary:

 1<?xml version="1.0" encoding="utf-8"?>
 2<topic id="b10d4d75-3729-4247-a58a-b9e5b6e4bb4d" revisionNumber="1">
 3  <developerConceptualDocument
 4    xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
 5    xmlns:xlink="http://www.w3.org/1999/xlink"
 6    xmlns:ltx="http://www.novacta.net/2018/XSL/ShfbLatexTools">
 7
 8    <introduction>
 9      <para>
10        Class <codeEntityReference qualifyHint="false">
11          T:SampleClassLibrary.IntegerOperation
12        </codeEntityReference> provides method
13        <codeEntityReference qualifyHint="false">
14          M:SampleClassLibrary.IntegerOperation.Operate(System.Func{System.Int32,System.Int32},System.Int32)
15        </codeEntityReference>
16        to manage operations on integer values.
17      </para>
18      <para>
19        In the following example, an integer is squared
20        executing the <codeEntityReference qualifyHint="false">
21          M:SampleClassLibrary.IntegerOperation.Operate(System.Func{System.Int32,System.Int32},System.Int32)
22        </codeEntityReference> method.
23        This is equivalent to define the applied function,
24        say <ltx:latex mode="inline">f:\mathbb{N}\rightarrow \mathbb{N},</ltx:latex>
25        as <ltx:latex>\forall n \in \mathbb{N}: n \mapsto f\left(n\right)=n^2.</ltx:latex>
26        In addition, input validation is also checked.
27      </para>
28      <code source="..\SampleClassLibrary\IntegerOperationExample.cs.txt"
29        language="cs" title="C#" />
30      <para>
31        A representation of the applied function is plotted as follows.
32      </para>
33      <mediaLink>
34        <image xlink:href="Function"/>
35      </mediaLink>
36    </introduction>
37
38    <relatedTopics>
39      <link xlink:href="4c3871a5-d7c6-477c-96ee-e71f0a67f7a8" />
40    </relatedTopics>
41
42  </developerConceptualDocument>
43</topic>

Note the LaTeX elements at lines 24-25. You can check here how such conceptual topic looks like.