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.