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.

First Step – Organize the input text

Help text can either be content specific (help to a specific field) or general. With NAV the requirement for content specific help is mandatory, users can press F1 and expects to get content specific help.

We have created two tables in NAV – one for holding content specific help and one for holding general help. The content specific table can be pre-populated with references to all objects and fields.

So now, we have a organized database for our text. We created BLOB fields to hold the text. This will almost solve the 2nd problem – Putting the text in a database. We can reference object versions, languages etc.

But what do you put into the BLOB fields? How do we keep text in a “portable” way, that will let us create F1 help and manuals?

Our answer is a text format called Markdown

Markdown is a very simple format, it can be edited with Notepad, you can read the text in raw ASCII, yet it is possible to use a fair amount of formatting information, such as lists, tables, bold, italic etc.

Markdown has the advantage, that it is very “convertible”, there are many tools than can convert MD to HTML to DOC, to all sort of different text formats.

In order for our editing staff to have a more premium user experience, we are using MarkdownPad, a editor that will show both the MD text and a formatted version (Sort of What you see is what you get) side by side.

To create pages for the Dynamics NAV 2015 help server, we need HTML, so we need to convert the Markdown to HTML.

But a manual created with HTML does not really give that “book feeling”. We wanted to create the manual as a real book (at least in PDF, but also on physical paper if users wanted it).

Books are typical created with a type-setting software. One of the oldest, but still best, is called TeX. A typesetting system created by one of the computing fathers, Donald Knuth. TeX comes in many shapes and forms, we have chosen a variant called XeTeX. The primary reason for selecting XeTeX is the support for OpenType fonts that we use internally in other places (web, sales material etc.)

With TeX/LaTeX/XeTeX wee can describe, in text, how the book should be formatted, table of content, index etc. And the output is a PDF file that can be printed as a book. It is also possible to output a .epub ebook.

So we want to transform our Markdown text to both HTML and Latex format. Searching around, we found a tool that will both transformations perfectly, a tool called pandoc. It is even open source and written in Haskell, a language that has been on my todo list for a long time.