diff options
Diffstat (limited to 'lib/docbuilder/doc/src/docb_transform.xml')
| -rw-r--r-- | lib/docbuilder/doc/src/docb_transform.xml | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/lib/docbuilder/doc/src/docb_transform.xml b/lib/docbuilder/doc/src/docb_transform.xml new file mode 100644 index 0000000000..b8975e2698 --- /dev/null +++ b/lib/docbuilder/doc/src/docb_transform.xml @@ -0,0 +1,224 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2001</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>docb_transform</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>docb_transform</module> + <modulesummary>Transform XML to HTML</modulesummary> + <description> + <p><c>docb_transform</c> contains functions for transforming XML + documentation source code to HTML.</p> + </description> + + <funcs> + <func> + <name>file(File) -> ok | {error, Reason}</name> + <name>file(File, Options) -> ok | {error, Reason}</name> + <fsummary>Transform XML to HTML</fsummary> + <type> + <v>File = string()</v> + <v>Options = [Opt]</v> + <v>Opt -- see below</v> + </type> + <desc> + <p>Transforms XML documentation source code to HTML.</p> + + <p><c>File</c> is a documentation source file, given with or + without the <c>.xml</c> extension as <c>Name.xml</c> or + <c>Name</c>.</p> + + <p>If <c>File</c> contains XML code according to a basic DTD + (<c>chapter</c>, <c>erlref</c>, ...), the resulting HTML + file is named <c>Name.html</c>.</p> + + <p>If <c>File</c> contains XML code according to a compound DTD + (<c>application</c> or <c>part</c>), several files are + created:</p> + <list> + <item>A cover page for the application with two frames, + <c>Name_frame.html</c>.</item> + <item>The contents of the left frame and a front page, + <c>Name.html</c> and <c>Name_first.html</c>.</item> + <item>A bibliography and a glossary, <c>Name_cite.html</c> + and <c>Name_term.html</c>.</item> + <item>In the case of an <c>application</c> DTD an index + is created, <c>Name.kwc</c> and <c>Name_index.html</c>. + </item> + <item>One HTML file for each file included from <c>File</c>. + </item> + <item>Also, if there exists a <c>fascicules.xml</c> file where + the value of the <c>entry</c> attribute for <c>File</c> is + <c>"yes"</c>, the cover page is copied to <c>index.html</c>. + </item> + </list> + </desc> + </func> + </funcs> + + <section> + <title>Options</title> + <taglist> + <tag><c>{html_mod, Module}, Module=atom()</c></tag> + <item> + <p>A callback module can be used for specifying HTML snippets + that should be included in the generated HTML files, see + below.</p> + </item> + + <tag><c>{outdir, Dir}, Dir=string()</c></tag> + <item> + <p>Destination for generated files. Default is current working + directory.</p> + </item> + + <tag><c>{number, Number}, Number=int()</c></tag> + <item> + <p>First chapter number when transforming a <c>chapter</c> + file. Default is 1.</p> + </item> + + <tag><c>{ptype, unix|windows}</c></tag> + <item> + <p>For <c>path</c> elements, the specified file path should be + presented.</p> + </item> + + <tag><c>silent</c></tag> + <item> + <p>Silent - no warnings, only error information is printed.</p> + </item> + + <tag><c>{top, Index}, Index=string()</c></tag> + <item> + <p>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.</p> + </item> + + <tag><c>{vsn, Vsn}, Vsn=string()</c></tag> + <item> + <p>Application version number. Overrides a version number + defined in the XML document. Visible in the left frame and + on the front page.</p> + </item> + + <tag><c>{term_defs, File}, File=string()</c></tag> + <item> + <p>Use the global glossary definitions in <c>File</c>, which + should contain a list of tuples <c>{Id, Name, Definition, + Owner}</c>. See the section + <seealso marker="inline_tags#termTAG"><term>, + <termdef> - Glossary</seealso> in the User's Guide. + </p> + </item> + + <tag><c>{cite_defs, File}, File=string()</c></tag> + <item> + <p>Use the global bibliography definitions in <c>File</c>, which + should contain a list of tuples <c>{Id, Title, Info, + Owner}</c>. See the section + <seealso marker="inline_tags#citeTAG"><cite>, + <citedef> - Bibliography</seealso> in the User's + Guide.</p> + </item> + </taglist> + </section> + + <section> + <title>Callback Module</title> + + <p>A <c>html_mod</c> 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.</p> + </section> + + <funcs> + <func> + <name>Module:head() -> string()</name> + <fsummary>Snippet to be included in head of a document.</fsummary> + <desc> + <p>Defines a HTML snippet to be included in the head of + a document, after the <c><HEAD></c> start tag and + <c><TITLE></c> tag:</p> + <pre> +<HTML> +<HEAD> + <TITLE>...</TITLE> + - snippet is included here - + ... +</HEAD> +... +</HTML> + </pre> + </desc> + </func> + + <func> + <name>Module:top() -> string()</name> + <fsummary>Snippet to be included at the top of a document. + </fsummary> + <desc> + <p>Defines a HTML snippet to be included at the top of a + document, after the <c><BODY></c> start tag.</p> + </desc> + </func> + + <func> + <name>Module:bottom() -> string()</name> + <fsummary>Snippet to be included at the bottom of a document. + </fsummary> + <desc> + <p>Defines a HTML snippet to be included at the bottom of a + document, before the <c></BODY></c> end tag.</p> + </desc> + </func> + + <func> + <name>Module:seealso(SeeAlso) -> Href</name> + <fsummary></fsummary> + <type> + <v>SeeAlso = Href = string()</v> + </type> + <desc> + <p>When referring to another part of the document, or another + document, the XML tag <c><seealso></c> is used: + <c><![CDATA[<seealso marker="File#Marker">...text...</seealso>]]></c>. + By default, this is translated to + <c><![CDATA[<A HREF="File.html#Marker>...text...</A>]]></c>.</p> + + <p>This function makes it possible to specify an alternative + translation <c>Href</c> of the <c>marker</c> attribute value + <c>SeeAlso</c>. For example, in OTP this is used to resolve + cross references between applications.</p> + </desc> + </func> + </funcs> + +</erlref> + |