Erlang -- docb_transform

User's Guide
Reference Manual
Release Notes
PDF
Top

DocBuilder
Reference Manual
Version 0.9.8.9

Expand All
Contract All

Table of Contents

- docbuilder (App)
- docb_gen
  - Top of manual page
  - module/1
  - module/2
  - users_guide/1
  - users_guide/2
- docb_transform
  - Top of manual page
  - file/1
  - file/2
  - Module:head/0
  - Module:top/0
  - Module:bottom/0
  - Module:seealso/1
- docb_xml_check
  - Top of manual page
  - validate/1

# docb_transform

### MODULE

docb_transform

### MODULE SUMMARY

Transform XML to HTML

### DESCRIPTION

docb_transform contains functions for transforming XML documentation source code to HTML.

### EXPORTS

file(File) -> ok | {error, Reason}
file(File, Options) -> ok | {error, Reason}

Types:

File = string()
Options = [Opt]
Opt -- see below

Transforms XML documentation source code to HTML.

File is a documentation source file, given with or without the .xml extension as Name.xml or Name.

If File contains XML code according to a basic DTD (chapter, erlref, ...), the resulting HTML file is named Name.html.

If File contains XML code according to a compound DTD (application or part), several files are created:

- A cover page for the application with two frames, Name_frame.html.
- The contents of the left frame and a front page, Name.html and Name_first.html.
- A bibliography and a glossary, Name_cite.html and Name_term.html.
- In the case of an application DTD an index is created, Name.kwc and Name_index.html.
- One HTML file for each file included from File.
- Also, if there exists a fascicules.xml file where the value of the entry attribute for File is "yes", the cover page is copied to index.html.

### Options

{html_mod, Module}, Module=atom()

  A callback module can be used for specifying HTML snippets that should be included in the generated HTML files, see below.

{outdir, Dir}, Dir=string()

  Destination for generated files. Default is current working directory.

{number, Number}, Number=int()

  First chapter number when transforming a chapter file. Default is 1.

{ptype, unix|windows}

  For path elements, the specified file path should be presented.

silent

  Silent - no warnings, only error information is printed.

{top, Index}, Index=string()

  Specifies the value of "Top" in the left frame of a front page, which normally should be some kind of top index file for the documentation.

{vsn, Vsn}, Vsn=string()

  Application version number. Overrides a version number defined in the XML document. Visible in the left frame and on the front page.

{term_defs, File}, File=string()

  Use the global glossary definitions in File, which should contain a list of tuples {Id, Name, Definition, Owner}. See the section <term>, <termdef> - Glossary in the User's Guide.

{cite_defs, File}, File=string()

  Use the global bibliography definitions in File, which should contain a list of tuples {Id, Title, Info, Owner}. See the section <cite>, <citedef> - Bibliography in the User's Guide.

### Callback Module

A html_mod callback module can include the functions specified below. Note that there is no check that the resulting HTML code is valid. All functions are optional.

### EXPORTS

Module:head() -> string()

Defines a HTML snippet to be included in the head of a document, after the <HEAD> start tag and <TITLE> tag:

    <HTML>
    <HEAD>
      <TITLE>...</TITLE>
      - snippet is included here -
      ...
    </HEAD>
    ...
    </HTML>

Module:top() -> string()

Defines a HTML snippet to be included at the top of a document, after the <BODY> start tag.

Module:bottom() -> string()

Defines a HTML snippet to be included at the bottom of a document, before the </BODY> end tag.

Module:seealso(SeeAlso) -> Href

Types:

SeeAlso = Href = string()

When referring to another part of the document, or another document, the XML tag <seealso> is used: <seealso marker="File#Marker">...text...</seealso>. By default, this is translated to <A HREF="File.html#Marker>...text...</A>.

This function makes it possible to specify an alternative translation Href of the marker attribute value SeeAlso. For example, in OTP this is used to resolve cross references between applications.