# 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.

### AUTHORS

Gunilla Arendt - support@erlang.ericsson.se

docbuilder 0.9
Copyright © 1991-2007 Ericsson AB