The manuals are written in the pandoc version of Markdown. See the pandoc site for tool and syntax information:
The single-file manuals (PDF and HTML) are combined by a script which looks at the file in the appropriate subdirectory: contents.md
To add a new file, just add it to contents.md and specify the output manpages in Makefile.am under MANUALMAN_GENERATED.
If synonym manpages are needed, add them to Makefile.am under the variable MANUALMAN_GENERATED_INDIRECT and create a comment block in the .md file:
<!--
extra-manpage: firehol-accept.5
extra-manpage: firehol-reject.5
extra-manpage: firehol-drop.5
extra-manpage: firehol-deny.5
extra-manpage: firehol-return.5
extra-manpage: firehol-tarpit.5
-->
See the pandoc website and manpage for details and options. To quickly process this file, try:
pandoc -f markdown -o README.pdf README.md
pandoc -f markdown -o README.html README.md
Use #, ##, ### rather than underlining titles, since some of the scripts rely on them when combining files. The exception is introduction.md which should use ==== etc. These conventions are relied on whilst combining files to ensure sections wind up at the correct heirachy in the output.
In order to make links across multiple formats as simple as possible, follow these conventions:
Keywords + Services Links : Always write links to these as:
[your text][keyword-product-name]
Keyword link definitions should be included in `link-keywords-firehol`
or `links-keywords-fireqos`, and should be of the form:
`file.md#anchor-in-single-html`
the build scripts will take care of excluding or replacing the file.md
according to the output format.
Services links are generated automatically as part of the build process
and will be put in the `service-links` file.
Internal Links : Always write links to these as:
[title name][] or [your text][title name]
Internal link definitions should be included in `links-internal` and
written in the form:
`filename.md#markdown-anchor`
these will be processed appropriately for each format.
External Links : External links can be written in-line as:
[whatever](http://host/path/#id)
they are not subject to special processing.
For the single-page HTML output, the anchors which are referenced must be globally unique, not just within a file. This means whenever an internal link is created, the section to which it refers must be uniquely named.
The check-links script ensures this is the case whilst building the HTML output.
Pandoc creates anchors automatically for most headers etc. but it is possible to manually create an anchor with standard HTML syntax e.g.
<a id="myid"></a>
This can be used as normal and should be included in internal-links
if it will be used from within the document or referred to from the
website.
Best will be to install specific pandoc highlighting, such as that available in the vim-pandoc plugin.
If you need a simple way to install the plugin, first install pathogen, which is simple and makes adding the syntax highlighter simple too.
An alternative quick way to ensure .md files are recognised as markdowm, not Modula2 by editing your .vimrc
Note that vim markdown syntax highlighting does not match pandoc perfectly, so you may get some occasional artifacts.
Pandoc output has a few quirks, depending on version. Versions earlier than 1.9.4.2 are known to have problems, so FireHOL checks for that as a minimum.
Some post-processing of output is performed by a script to tidy up some artifacts.