Running the Help processor

To get the whole thing running, take a look at the HelpTest.exe.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="miktex-path" value="C:\Program Files (x86)\MiKTeX 2.9\miktex\"/>
    <add key="pandoc-path" value="C:\Projects\Help\Tools\"/>
    <add key="template-xml" value=".\template.xml"/>
    <add key="content-xml" value=".\NAV.xml" />
    <add key="structure-xml" value=".\structure.xml"/>
    <add key="projectname" value="Demo Help"/>
    <add key="helppage-html" value=".\HelpPage.html"/>
    <add key="input-toc" value=".\input-toc.xml"/>
    <add key="output-toc" value=".\output\output-toc.xml"/>
    <add key="output-path-helpserver" value=".\output"/>
    <add key="output-path-manual" value=".\output"/>
  </appSettings>
  <startup> 
      <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
  </startup>
</configuration>

You  need to install the following to be ready:

MikTex 2.9 http://miktex.org/download

Pandoc https://github.com/jgm/pandoc/releases

And update the paths in the config file

After this you need to update all the setup paths and xml files. These should point to the content from the ZIP file.

Running HelpTest.exe from a prompt should generate output that looks a bit like this: (This is the output from Foqus Finance)

Building manual
Generate Topic 6030550 (Table)
Generate SubTopic 6030551 (Table)
Generate SubTopic 6030553 (Table)
Generate SubTopic 6030554 (Table)
Generate SubTopic 6030555 (Table)
Generate SubTopic 6030556 (Table)
Generate SubTopic 6030569 (Table)
Generate SubTopic 6030558 (Table)
Generate SubTopic 6030559 (Table)
Generate SubTopic 6030568 (Table)
Generate SubTopic 6030567 (Table)
Generate SubTopic 6030581 (Table)
Generate Topic 6030562 (Table)
Generate Topic StageSales (Article)
Generate Topic StageEstab (Article)
Generate Topic StageAdmin (Article)
Generate Topic StageRearr (Article)
Generate Topic StageArchive (Article)
Generate Topic 6030560 (Table)
Generate Topic 6030561 (Table)
Generate Topic 6030582 (Table)
Generate Topic 6030695 (Table)
Generate Topic 6030696 (Table)
Generate Topic 6030740 (Table)
Generate Topic 6030741 (Table)
Generate Topic 6030650 (Table)
Generate Topic 6030666 (Table)
Generate Topic 6030563 (Table)
Generate Topic 6030565 (Table)
Generate Topic 6030651 (Table)
Generate Topic 6030700 (Table)
Generate Topic 6030557 (Table)
Generate Topic 6030703 (Table)
Generate Topic 6030652 (Table)
Generate Topic 6030680 (Table)
Generate Topic 6030653 (Table)
Generate Topic 6030654 (Table)
Generate Topic 6030655 (Table)
Generate Topic 6030656 (Table)
Generate Topic 6030677 (Table)
Generate Topic 6030679 (Table)
Generate Topic ContractFlow (Article)
Generate SubTopic 6030901 (Table)
Generate SubTopic 6030902 (Table)
Generate SubTopic 6030904 (Table)
Generate Topic 6031008 (Table)
Generate SubTopic 6031009 (Table)
Generate SubTopic 6031010 (Table)
Generate SubTopic 6031011 (Table)
Generate SubTopic 6031000 (Table)
Generate SubTopic 6031001 (Table)
Generate SubTopic 6031002 (Table)
Generate SubTopic 6031003 (Table)
Generate SubTopic 6031004 (Table)
Generate SubTopic 6031005 (Table)
Generate SubTopic 6031006 (Table)
Generate SubTopic 6031007 (Table)
Generate Topic CostSetup (Article)
Generate SubTopic 6030659 (Table)
Generate SubTopic 6030702 (Table)
Generate SubTopic 6030675 (Table)
Generate Topic TaskSetup (Article)
Generate SubTopic 6030658 (Table)
Generate SubTopic 6030701 (Table)
Generate SubTopic 6030676 (Table)
Generate SubTopic 6030571 (Table)
Generate SubTopic 6030572 (Table)
Generate Topic ServiceIns (Article)
Generate SubTopic 6030566 (Table)
Generate SubTopic 6030663 (Table)
Generate SubTopic 6030664 (Table)
Generate SubTopic 6030669 (Table)
Generate SubTopic 6030670 (Table)
Generate SubTopic 6030671 (Table)
Generate SubTopic 6030672 (Table)
Generate SubTopic 6030673 (Table)
Generate Topic CreditApprov (Article)
Generate SubTopic 6030950 (Table)
Generate SubTopic 6030951 (Table)
Generate SubTopic 6030952 (Table)
Generate SubTopic 6030953 (Table)
Generate SubTopic 6030954 (Table)
Generate SubTopic 6030955 (Table)
Generate Topic FoqusDocSetup (Article)
Generate SubTopic 6030910 (Table)
Generate SubTopic 6030911 (Table)
Generate SubTopic 6030912 (Table)
Generate SubTopic 6030913 (Table)
Generate SubTopic 6030914 (Table)
Generate SubTopic 6030915 (Table)
Generate SubTopic 6030916 (Table)
Generate SubTopic 6030920 (Table)
Building helpserver files
Generate Topic 6030550 (Table)
Generate Topic 6030562 (Table)
Generate Topic StageSales (Article)
Generate Topic StageEstab (Article)
Generate Topic StageAdmin (Article)
Generate Topic StageRearr (Article)
Generate Topic StageArchive (Article)
Generate Topic 6030560 (Table)
Generate Topic 6030561 (Table)
Generate Topic 6030582 (Table)
Generate Topic 6030695 (Table)
Generate Topic 6030696 (Table)
Generate Topic 6030740 (Table)
Generate Topic 6030741 (Table)
Generate Topic 6030650 (Table)
Generate Topic 6030666 (Table)
Generate Topic 6030563 (Table)
Generate Topic 6030565 (Table)
Generate Topic 6030651 (Table)
Generate Topic 6030700 (Table)
Generate Topic 6030557 (Table)
Generate Topic 6030703 (Table)
Generate Topic 6030652 (Table)
Generate Topic 6030680 (Table)
Generate Topic 6030653 (Table)
Generate Topic 6030654 (Table)
Generate Topic 6030655 (Table)
Generate Topic 6030656 (Table)
Generate Topic 6030677 (Table)
Generate Topic 6030679 (Table)
Generate Topic ContractFlow (Article)
Generate SubTopic 6030901 (Table)
Generate SubTopic 6030902 (Table)
Generate SubTopic 6030904 (Table)
Generate Topic 6031008 (Table)
Generate Topic CostSetup (Article)
Generate SubTopic 6030659 (Table)
Generate SubTopic 6030702 (Table)
Generate SubTopic 6030675 (Table)
Generate Topic TaskSetup (Article)
Generate SubTopic 6030658 (Table)
Generate SubTopic 6030701 (Table)
Generate SubTopic 6030676 (Table)
Generate SubTopic 6030571 (Table)
Generate SubTopic 6030572 (Table)
Generate Topic ServiceIns (Article)
Generate SubTopic 6030566 (Table)
Generate SubTopic 6030663 (Table)
Generate SubTopic 6030664 (Table)
Generate SubTopic 6030669 (Table)
Generate SubTopic 6030670 (Table)
Generate SubTopic 6030671 (Table)
Generate SubTopic 6030672 (Table)
Generate SubTopic 6030673 (Table)
Generate Topic CreditApprov (Article)
Generate SubTopic 6030950 (Table)
Generate SubTopic 6030951 (Table)
Generate SubTopic 6030952 (Table)
Generate SubTopic 6030953 (Table)
Generate SubTopic 6030954 (Table)
Generate SubTopic 6030955 (Table)
Generate Topic FoqusDocSetup (Article)
Generate SubTopic 6030910 (Table)
Generate SubTopic 6030911 (Table)
Generate SubTopic 6030912 (Table)
Generate SubTopic 6030913 (Table)
Generate SubTopic 6030914 (Table)
Generate SubTopic 6030915 (Table)
Generate SubTopic 6030916 (Table)
Generate SubTopic 6030920 (Table)
Done

MiKTex might show some warnings like this, ignore those 🙂

This is makeindex, version 2.15 [MiKTeX 2.9] (kpathsea + Thai support).
Scanning input file FoqusFinance.idx.....done (1271 entries accepted, 1 rejected).
Sorting entries.............done (14618 comparisons).
Generating output file FoqusFinance.ind.....done (925 lines written, 0 warnings)
.
Output written in FoqusFinance.ind.
Transcript written in FoqusFinance.ilg.

** WARNING ** Couldn't open font map file "kanjix.map".

After this, oyu should have a PDF, a new ToC.xml and a bunch of HTML Files.

 

 

Graphical Layout for manuals and Help Server

The only components missing now before we are ready to put all this together, is graphical layout. Both help pages and a manual needs a “look”.

On the help server, the layout is given by Microsoft. We cannot have “our” help pages look completely different from those supplied by Microsoft if we want our users to have consistent user experience across different parts of NAV.

So we grab one the pages from the help server and strip all text. We insert “markers” into the page where we want to add text.

Currently we are using the following markers:

$1$ = Title
$2$ = Body text

More can easily be added, but for now, it is sufficient for our need.

Next, we need layout for our book, this is a bit more complicated (typesetting is an art form for some people), so we have introduced another xml file to our setup, called template.xml.

Template.xml holds bits of Latex code that the manual will be contructed from, it has the following bits:

<ManualStart> = The code that define the book (or ebook) imports all needed latex modules
<ManualEnd> = The code that gets appended at the end of the book
<ChaperHead> = The code that starts a chapter in the book
<ChapterBetweenTopics> = Placed between topics within a chapter
<ArticleTopicHead> = Head of an article
<ArticleTopicText> = Body on an article
<TableTopicHead> = Head of a table
<TableTopicIntro> = Introduction to a table
<TableTopicFields> = Fields in the table
<Field> = A single field
…..
And more. All these building block combined with the raw text, converted from Markdown to Latex, will produce a manual in PDF.

** Now we want to create pages for the NAV Help server

This is done with the same content as the manual. We need to do two steps:

1. Create each piece of help content we have as a HTML help page

2. Add references for our new pages into the ToC.xml file

** Create HTML pages for content

Again we use a template (called helppage.html) to add our content into. This time we use pandoc to convert the markdown to HTML and insert the HTML into the page. And we actually only inserts two pieces of information into the page:

1. The body text
2. The title

A difference compared to the PDF manual, is that we don’t show the fields together with the table. Instead we’ll create a list of fields that links to the individual pages for each field.

Getting structure into the documentation

Putting our pieces together now, gives us a database for storing the help, an editor (MarkdownPad) for editing, and a converter (Pandoc) for performing conversion and a typesetting system XeTeX.

But there are still a few thing missing, the first thing we need a way to describe the structure of our help. Dynamics NAV is based on “objects” indexed with numbers. The catch is, that there is no “user understandable” logic to the numbering. So we cannot say that the content in the manual should be ordered by object numbers.

We created a XML description of the structure, called structure.xml, it look a bit like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Manual>
  <Info>
    <Title>Demo Documention</Title>
    <Author>E Foqus Documentation 2015 (c)</Author>
    <Preface Type="Article" ID="Introduction" />
  </Info>
  <Chapters>
    <Chapter No="1" Title="The First Chapter">
      <Preface Type="Article" ID="chapter1intro" />
      <Topics>
        <Topic Type="Table" ID="18">
          <SubTopics>
            <SubTopic Type="Table" ID="21" />
          </SubTopics>            
         </Topic>
      </Topics>
    </Chapter>
    <Chapter No="2" Title="A chapter to far..">
      <Preface Type="Article" ID="charpter2intro" />
      <Topics>
        <Topic Type="Table" ID="24" />
      </Topics>
    </Chapter>
  </Chapters>
</Manual>

If you look at the table of content (ToC) in a book, this closly resembles what we have in structure.xml. The other element called <Manual> has a <Info> section with setting for the frontpage and an preface article. Then follows the <Chapters> section with multiple <Chapters>.

Each <Chapter> has a title, a preface article and a series of topics with sub-topics embedded.

Every time we have a preface, a topic or a sub-topic, it can have the following types:

* Article – Points to an article
* Table – Points to a table
* Page – Points to a page
* Report – Points to a report
* XMLport – Points to a XML Port

Each of these can be found in our NAV database.

When we look at the NAV 2015 Help server, we see the collapsible menu on the left, this structure resembles the ToC of a manual, and is stored in a filed called ToC.xml on the server. We can use our structure.xml to fill out the Help Server ToC.xml file.