docb_transform
(docbuilder)Transform XML to HTML
docb_transform
contains functions for transforming XML
documentation source code to HTML.
Functions
file(File) -> ok | {error, Reason}
file(File, Options) -> ok | {error, Reason}
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
andName_first.html
. - A bibliography and a glossary,
Name_cite.html
andName_term.html
. - In the case of an
application
DTD an index is created,Name.kwc
andName_index.html
. - One HTML file for each file included from
File
. - Also, if there exists a
fascicules.xml
file where the value of theentry
attribute forFile
is"yes"
, the cover page is copied toindex.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.
Functions
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
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.