Module rstgen

This module implements a generator of HTML/Latex from reStructuredText (see http://docutils.sourceforge.net/rst.html for information on this markup syntax). You can generate HTML output through the convenience proc rstToHtml, which provided an input string with rst markup returns a string with the generated HTML. The final output is meant to be embedded inside a full document you provide yourself, so it won't contain the usual <header> or <body> parts.

You can also create a TRstGenerator structure and populate it with the other lower level methods to finally build complete documents. This requires many options and tweaking, but you are not limited to snippets and can generate LaTeX documents too.

Types

TOutputTarget = enum 
  outHtml, 
  outLatex
which document type to generate 
TMetaEnum = enum 
  metaNone, metaTitle, metaSubtitle, metaAuthor, metaVersion
TRstGenerator = object of TObject
  target*: TOutputTarget
  config*: PStringTable
  splitAfter*: int
  tocPart*: seq[TTocEntry]
  hasToc*: bool
  theIndex: string
  options*: TRstParseOptions
  findFile*: TFindFileHandler
  msgHandler*: TMsgHandler
  filename*: string
  meta*: array[TMetaEnum, string]

Vars

splitter: string = "<wbr />"

Consts

IndexExt = ".idx"

Procs

proc initRstGenerator(g: var TRstGenerator; target: TOutputTarget; 
                      config: PStringTable; filename: string; 
                      options: TRstParseOptions; findFile: TFindFileHandler; 
                      msgHandler: TMsgHandler) {.
    raises: [EOverflow, EInvalidValue], tags: [].}

Initializes a TRstGenerator.

You need to call this before using a TRstGenerator with any other procs in this module. Pass a non nil PStringTable value as config with parameters used by the HTML output generator. If you don't know what to use, pass the results of the defaultConfig() proc. The filename is symbolic and used only for error reporting, you can pass any non nil string here.

The TRstParseOptions, TFindFileHandler and TMsgHandler types are defined in the the packages/docutils/rst module. options selects the behaviour of the rst parser.

findFile is a proc used by the rst include directive among others. The purpose of this proc is to mangle or filter paths. It receives paths specified in the rst document and has to return a valid path to existing files or the empty string otherwise. If you pass nil, a default proc will be used which given a path returns the input path only if the file exists. One use for this proc is to transform relative paths found in the document to absolute path, useful if the rst file and the resources it references are not in the same directory as the current working directory.

The msgHandler is a proc used for user error reporting. It will be called with the filename, line, col, and type of any error found during parsing. If you pass nil, a default message handler will be used which writes the messages to the standard output.

Example:

import packages/docutils/rstgen

var gen: TRstGenerator

gen.initRstGenerator(outHtml, defaultConfig(),
  "filename", {}, nil, nil)
proc writeIndexFile(g: var TRstGenerator; outfile: string) {.
    raises: [E_Base, EIO], tags: [FWriteIO].}

Writes the current index buffer to the specified output file.

You previously need to add entries to the index with the setIndexTerm proc. If the index is empty the file won't be created.

proc escChar(target: TOutputTarget; dest: var string; c: char) {.inline, 
    raises: [], tags: [].}
proc nextSplitPoint(s: string; start: int): int {.raises: [], tags: [].}
proc esc(target: TOutputTarget; s: string; splitAfter = - 1): string {.
    raises: [], tags: [].}
proc setIndexTerm(d: var TRstGenerator; id, term: string) {.raises: [], tags: [].}

Adds a term to the index using the specified hyperlink identifier.

The d.theIndex string will be used to append the term in the format term<tab>file#id. The anchor will be the based on the name of the file currently being parsed plus the id, which will be appended after a hash.

The index won't be written to disk unless you call writeIndexFile.

proc mergeIndexes(dir: string): string {.raises: [E_Base, EIO, EInvalidValue], 
    tags: [FReadIO].}
merges all index files in dir and returns the generated index as HTML. The result is no full HTML for flexibility. 
proc renderTocEntries(d: var TRstGenerator; j: var int; lvl: int; 
                      result: var string) {.raises: [EInvalidValue], tags: [].}
proc renderRstToOut(d: var TRstGenerator; n: PRstNode; result: var string) {.
    raises: [E_Base, EInvalidValue, EAssertionFailed], tags: [TEffect].}

Writes into result the rst ast n using the d configuration.

Before using this proc you need to initialise a TRstGenerator with initRstGenerator and parse a rst file with rstParse from the packages/docutils/rst module. Example:

# ...configure gen and rst vars...
var generatedHTML = ""
renderRstToOut(gen, rst, generatedHTML)
echo generatedHTML
proc formatNamedVars(frmt: string; varnames: openArray[string]; 
                     varvalues: openArray[string]): string {.raises: [
    EInvalidValue, EInvalidValue, EInvalidValue, EInvalidValue, EInvalidValue], 
    tags: [].}
proc defaultConfig(): PStringTable {.raises: [], tags: [].}

Returns a default configuration for embedded HTML generation.

The returned PStringTable contains the paramters used by the HTML engine to build the final output. For information on what these parameters are and their purpose, please look up the file config/nimdoc.cfg bundled with the compiler.

The only difference between the contents of that file and the values provided by this proc is the doc.file variable. The doc.file variable of the configuration file contains HTML to build standalone pages, while this proc returns just the content for procs like rstToHtml to generate the bare minimum HTML.

proc rstToHtml(s: string; options: TRstParseOptions; config: PStringTable): string {.raises: [
    EOverflow, EInvalidValue, E_Base, EParseError, EIO, EAssertionFailed], 
    tags: [TEffect, FWriteIO, FReadEnv].}

Converts an input rst string into embeddable HTML.

This convenience proc parses any input string using rst markup (it doesn't have to be a full document!) and returns an embeddable piece of HTML. The proc is meant to be used in online environments without access to a meaningful filesystem, and therefore rst include like directives won't work. For an explanation of the config parameter see the initRstGenerator proc. Example:

import packages/docutils/rstgen, strtabs

echo rstToHtml("*Hello* **world**!", {},
  newStringTable(modeStyleInsensitive))
# --> <em>Hello</em> <strong>world</strong>!

If you need to allow the rst include directive or tweak the generated output you have to create your own TRstGenerator with initRstGenerator and related procs.

Generated: 2014-03-11 21:26:55 UTC