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.
