From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/docbuilder/doc/src/docb_gen.xml | 213 ++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 lib/docbuilder/doc/src/docb_gen.xml (limited to 'lib/docbuilder/doc/src/docb_gen.xml') diff --git a/lib/docbuilder/doc/src/docb_gen.xml b/lib/docbuilder/doc/src/docb_gen.xml new file mode 100644 index 0000000000..49eb79ae24 --- /dev/null +++ b/lib/docbuilder/doc/src/docb_gen.xml @@ -0,0 +1,213 @@ + + + + +
+ + 1999 + 2007 + Ericsson AB, All Rights Reserved + + + 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. + + docb_gen + + + + +
+ docb_gen + Generate XML from EDoc comments in Erlang source code. + + + +

docb_gen contains functions for generating XML + documentation source code according to the erlref or + chapter DTD from + EDoc comments in Erlang + source code or an overview.edoc file, using EDoc.

+ + + + + module(File) -> ok | {error, Reason} + module(File, Options) -> ok | {error, Reason} + Generate XML from EDoc comments in Erlang source code. + + + File = string() + Options = [Opt] + Opt = {def,Defs} | {includes,Dirs} | {preprocess,Bool} + | {sort_functions,Bool} + Defs = [{atom(),string()}] + Dirs = [string()] + Bool = bool() + Reason = badfile | {badopt,term()} | term() + + +

Generates XML documentation source code according to + the erlref DTD from EDoc comments File, using + the EDoc application.

+ +

File is an Erlang source file, given with or without + the .erl extension as Name.erl or Name. + The resulting XML file is created in the current working + directory and named Name.xml.

+ +

Options is a list of options, see below.

+ +

Returns ok if successful, and an error tuple + otherwise.

+ + + + + users_guide(File) -> ok | {error, Reason} + users_guide(File, Options) -> ok | {error, Reason} + Generate XML from EDoc comments in Erlang source code + + + File -- see module/1,2 + Options -- see module/1,2 + Reason -- see module/1,2 + + +

Like module/1,2 but generates XML source code + according to the chapter DTD from an + overview.edoc or similar file.

+ +

The resulting file is named chapter.xml.

+ + + + +
+ Options + + {def, [{Name,Text}]} + Specifies EDoc macro definitions. See + edoc:get_doc/2. + + {includes, [Dir]} + Specifies directories where EDoc should search for include + files. See + edoc:read_source/2. + + {preprocess, true|false} + Specifies if EDoc should read the source file via the Erlang + preprocessor. Default is false. See + edoc:read_source/2. + + {sort_functions, true|false} + Specifies if the functions in the resulting XML file should + be sorted alphabetically. Default is true. + +
+ +
+ Limitations +

The mapping from the EDoc XHTML output to valid Erlang/OTP XML + is not complete. An attempt has been made to cover the most + commonly used XHTML constructs, but there will still be cases + where XML generation fails or where the resulting XML is + inadequate. This is especially true for users_guide/1,2. +

+ +

Known limitations for some XHTML tags:

+ + ]]> + +

All attributes except the first href or name + attribute are ignored.

+

A href attribute means the ]]> tag + will be transformed to a ]]> or + ]]> tag and an attempt is made to + resolve the reference if necessary.

+ +

A name attribute means the ]]> tag + will be transformed to a ]]> tag.

+ + + , , 
]]>
+      Cannot contain other tags in Erlang/OTP XML, content is
+	converted to plain text.
+      
+
+      ]]>
+      No corresponding Erlang/OTP XML tag, converted to plain
+	text.
+      
+
+      ]]>
+      No corresponding Erlang/OTP XML tag, converted to plain
+	text.
+      
+
+      , 
, ...]]>
+      There is no tag corresponding to a header in Erlang/OTP XML,
+	so these are converted to plain text instead, with
+	the exception of ]]> and
+	]]> tags within overview.edoc, see
+	part about "chapter DTD" below.
+      
+
+      ]]>
+      There is no tag corresponding to superscript in Erlang/OTP
+	XML, so this is converted to plain text within brackets "(..)".
+      
+
+      References
+      The markers automatically inserted by EDoc at each heading
+	and function will override the markers automatically inserted
+	by DocBuilder, with the unfortunate result that the links in
+	the left-hand frame of the User's Guide will not work, and
+	also that cross referencing a function in a module the usual
+	Erlang/OTP way
+	"]]>" does
+	not work. (But
+	"]]>" does.)
+      
+    
+
+    
erlref DTD

+    
+      Tables
+      Tables are not allowed. The contents of a table is
+	converted to text instead, each row corresponding to one line
+	of text.
+      
+    
+
+    
chapter DTD

+    
+      Sections
+      Only two levels of sections. ]]>
+	(equivalent to EDoc headings "== Heading ==") is
+	interpreted as start of top-level section, or if there is no
+	]]> tag, the entire document is made into
+	one top-level section. ]]> (equivalent to
+	EDoc sub-headings ("") is
+	interpreted as start of second-level section.
+      
+
+      Tables
+      Tables without borders are converted to text in the same
+	manner as for the erlref DTD.
+      
+    
+
+ + + -- cgit v1.2.3