aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_docgen
diff options
context:
space:
mode:
authorLars Thorsen <[email protected]>2011-11-17 12:27:59 +0100
committerLars Thorsen <[email protected]>2011-11-18 14:28:44 +0100
commit4424b10d7054025eef3e721f64fb53ad7b357282 (patch)
tree3021ca22d285757cd63054e6925b7c56ec8724a7 /lib/erl_docgen
parentebaf44e2d10bdf6bca2fc83d10e75e144dcbde2d (diff)
downloadotp-4424b10d7054025eef3e721f64fb53ad7b357282.tar.gz
otp-4424b10d7054025eef3e721f64fb53ad7b357282.tar.bz2
otp-4424b10d7054025eef3e721f64fb53ad7b357282.zip
[erl_docgen] Tidy up the documentation moved from docbuilder to erl_docgen
Diffstat (limited to 'lib/erl_docgen')
-rw-r--r--lib/erl_docgen/Makefile2
-rw-r--r--lib/erl_docgen/doc/html/.gitignore0
-rw-r--r--lib/erl_docgen/doc/man3/.gitignore0
-rw-r--r--lib/erl_docgen/doc/pdf/.gitignore0
-rw-r--r--lib/erl_docgen/doc/src/Makefile135
-rw-r--r--lib/erl_docgen/doc/src/block_tags.xml16
-rw-r--r--lib/erl_docgen/doc/src/book.xml16
-rw-r--r--lib/erl_docgen/doc/src/character_entities.xml2
-rw-r--r--lib/erl_docgen/doc/src/convert.howto13
-rw-r--r--lib/erl_docgen/doc/src/docgen_xml_check.xml (renamed from lib/erl_docgen/doc/src/docb_xml_check.xml)6
-rw-r--r--lib/erl_docgen/doc/src/erl_docgen.txt6
-rw-r--r--lib/erl_docgen/doc/src/example.txt (renamed from lib/erl_docgen/doc/src/gazonk)2
-rw-r--r--lib/erl_docgen/doc/src/header_tags.xml16
-rw-r--r--lib/erl_docgen/doc/src/inline_tags.xml49
-rw-r--r--lib/erl_docgen/doc/src/notes.xml6
-rw-r--r--lib/erl_docgen/doc/src/overview.xml50
-rw-r--r--lib/erl_docgen/doc/src/part.xml9
-rw-r--r--lib/erl_docgen/doc/src/ref_man.xml36
-rw-r--r--lib/erl_docgen/doc/src/refman_dtds.xml6
-rw-r--r--lib/erl_docgen/vsn.mk2
20 files changed, 222 insertions, 150 deletions
diff --git a/lib/erl_docgen/Makefile b/lib/erl_docgen/Makefile
index 93a6353cac..a59351d53d 100644
--- a/lib/erl_docgen/Makefile
+++ b/lib/erl_docgen/Makefile
@@ -23,7 +23,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk
# Macros
#
-SUB_DIRECTORIES = src priv
+SUB_DIRECTORIES = src priv doc/src
#doc/src
include vsn.mk
diff --git a/lib/erl_docgen/doc/html/.gitignore b/lib/erl_docgen/doc/html/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/erl_docgen/doc/html/.gitignore
diff --git a/lib/erl_docgen/doc/man3/.gitignore b/lib/erl_docgen/doc/man3/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/erl_docgen/doc/man3/.gitignore
diff --git a/lib/erl_docgen/doc/pdf/.gitignore b/lib/erl_docgen/doc/pdf/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/erl_docgen/doc/pdf/.gitignore
diff --git a/lib/erl_docgen/doc/src/Makefile b/lib/erl_docgen/doc/src/Makefile
new file mode 100644
index 0000000000..1845f57fad
--- /dev/null
+++ b/lib/erl_docgen/doc/src/Makefile
@@ -0,0 +1,135 @@
+#
+# %CopyrightBegin%
+#
+# Copyright Ericsson AB 1997-2010. 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.
+#
+# %CopyrightEnd%
+#
+#
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+
+# ----------------------------------------------------
+# Application version
+# ----------------------------------------------------
+include ../../vsn.mk
+VSN=$(ERL_DOCGEN_VSN)
+APPLICATION=erl_docgen
+
+# ----------------------------------------------------
+# Release directory specification
+# ----------------------------------------------------
+RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+XML_APPLICATION_FILES = ref_man.xml
+XML_REF3_FILES = \
+ docgen_xml_check.xml
+
+XML_PART_FILES = \
+ part.xml
+
+XML_CHAPTER_FILES = \
+ overview.xml \
+ user_guide_dtds.xml \
+ refman_dtds.xml \
+ notes.xml \
+ inline_tags.xml \
+ header_tags.xml \
+ character_entities.xml \
+ block_tags.xml
+
+BOOK_FILES = book.xml
+
+XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \
+ $(XML_PART_FILES) $(XML_CHAPTER_FILES)
+
+TECHNICAL_DESCR_FILES =
+
+EXAMPLE_FILES = \
+ example.txt
+
+GIF_FILES = \
+ man.gif
+
+# ----------------------------------------------------
+
+HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+
+INFO_FILE = ../../info
+
+MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+
+HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
+
+TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+
+# ----------------------------------------------------
+# FLAGS
+# ----------------------------------------------------
+XML_FLAGS +=
+DVIPS_FLAGS +=
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+docs: pdf html man
+
+$(HTMLDIR)/%.gif: %.gif
+ $(INSTALL_DATA) $< $@
+
+$(HTMLDIR)/example.txt: example.txt
+ $(INSTALL_DATA) $< $@
+
+$(TOP_PDF_FILE): $(XML_FILES)
+
+pdf: $(TOP_PDF_FILE)
+
+html: gifs examples $(HTML_REF_MAN_FILE)
+
+clean clean_docs:
+ rm -rf $(HTMLDIR)/*
+ rm -f $(MAN3DIR)/*
+ rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+ rm -f errs core *~
+ rm -f $(JD_HTML) $(JD_PACK)
+
+man: $(MAN3_FILES)
+
+gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
+
+examples: $(GIF_FILES:%=$(HTMLDIR)/%)
+
+debug opt:
+
+# ----------------------------------------------------
+# Release Target
+# ----------------------------------------------------
+include $(ERL_TOP)/make/otp_release_targets.mk
+
+release_docs_spec: docs
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(HTMLDIR)/* \
+ $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+ $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3
+
+release_spec:
diff --git a/lib/erl_docgen/doc/src/block_tags.xml b/lib/erl_docgen/doc/src/block_tags.xml
index f5ba083f38..0900d7f008 100644
--- a/lib/erl_docgen/doc/src/block_tags.xml
+++ b/lib/erl_docgen/doc/src/block_tags.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -33,7 +33,7 @@
as a paragraph or a list.</p>
<p>The following subset of block tags are common for all DTDs in
- the DocBuilder DTD suite:
+ the OTP DTD suite:
<marker id="block_subset"></marker>
<seealso marker="#pTAG">&lt;p&gt;</seealso>,
<seealso marker="#preTAG">&lt;pre&gt;</seealso>,
@@ -81,7 +81,7 @@ sum([]) ->
</code>
<p>There is an attribute <c>type = "erl" | "c" | "none"</c>, but
- currently this attribute is ignored by DocBuilder. Default value
+ currently this attribute is ignored. Default value
is <c>"none"</c></p>
<note>
@@ -99,18 +99,18 @@ sum([]) ->
gives the file name and <c>tag</c> defines a string which
delimits the code snippet. Example:</p>
<pre>
-&lt;codeinclude file="gazonk" tag="%% Erlang example"/&gt;
+&lt;codeinclude file="example.txt" tag="%% Erlang example"/&gt;
</pre>
<p>results in:</p>
- <codeinclude file="gazonk" tag="%% Erlang example"/>
+ <codeinclude file="example.txt" tag="%% Erlang example"/>
- <p>provided there is a file named <c>gazonk</c> looking like this:
+ <p>provided there is a file named <c>examples.txt</c> looking like this:
</p>
<code>
...
%% Erlang example
--module(gazonk).
+-module(example).
start() ->
{error,"Pid required!"}.
@@ -125,7 +125,7 @@ start(Pid) ->
included.</p>
<p>There is also an attribute <c>type = "erl" | "c" | "none"</c>, but
- currently this attribute is ignored by DocBuilder. Default value
+ currently this attribute is ignored. Default value
is <c>"none"</c></p>
</section>
diff --git a/lib/erl_docgen/doc/src/book.xml b/lib/erl_docgen/doc/src/book.xml
index 9df5c39271..1eef9a621b 100644
--- a/lib/erl_docgen/doc/src/book.xml
+++ b/lib/erl_docgen/doc/src/book.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE book SYSTEM "book.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<header titlestyle="normal">
<copyright>
- <year>2004</year><year>2009</year>
+ <year>2004</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -21,27 +21,23 @@
</legalnotice>
- <title>erl_docgen</title>
+ <title>Erl_Docgen</title>
<prepared>Lars Thorsen</prepared>
<docno></docno>
- <date>2009-11-10</date>
- <rev>0.1</rev>
+ <date>2011-11-10</date>
+ <rev>0.3</rev>
<file>book.xml</file>
</header>
- <insidecover>
- </insidecover>
<pagetext>erl_docgen</pagetext>
<preamble>
<contents level="2"></contents>
</preamble>
<parts lift="no">
+ <xi:include href="part.xml"/>
</parts>
- <applications>
- </applications>
<releasenotes>
<xi:include href="notes.xml"/>
</releasenotes>
- <listofterms></listofterms>
<index></index>
</book>
diff --git a/lib/erl_docgen/doc/src/character_entities.xml b/lib/erl_docgen/doc/src/character_entities.xml
index 0a4ae17fb5..9f55b68d18 100644
--- a/lib/erl_docgen/doc/src/character_entities.xml
+++ b/lib/erl_docgen/doc/src/character_entities.xml
@@ -32,7 +32,7 @@
<section>
<title>Added Latin 1</title>
- <p>The DocBuilder DTD suite uses the same character entities as
+ <p>The OTP DTD suite uses the same character entities as
defined in HTML 3.2
(<c>ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML</c>). That is:
for an &amp; (ampersand), use the entity: <c>&amp;amp;</c>, for
diff --git a/lib/erl_docgen/doc/src/convert.howto b/lib/erl_docgen/doc/src/convert.howto
deleted file mode 100644
index 2c72de8c4c..0000000000
--- a/lib/erl_docgen/doc/src/convert.howto
+++ /dev/null
@@ -1,13 +0,0 @@
-
-- add xmlns:xi="http://www.w3.org/2001/XInclude" on top tag
- in files whith include directives
-
-- change <include file="notes"></include> <xi:include href="notes.xml"/>
-
-- change <image file="a"/> to <image file="a.gif"/>
-
-- remove chapers directly in the book and put them in the part instead
-
--change title to just the application name
-
-- fix codeinclude : xml --> xmlsrc \ No newline at end of file
diff --git a/lib/erl_docgen/doc/src/docb_xml_check.xml b/lib/erl_docgen/doc/src/docgen_xml_check.xml
index eff4fc4342..58cf069d81 100644
--- a/lib/erl_docgen/doc/src/docb_xml_check.xml
+++ b/lib/erl_docgen/doc/src/docgen_xml_check.xml
@@ -23,16 +23,16 @@
The Initial Developer of the Original Code is Ericsson AB.
</legalnotice>
- <title>docb_xml_check</title>
+ <title>docgen_xml_check</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
- <module>docb_xml_check</module>
+ <module>docgen_xml_check</module>
<modulesummary>Validate XML documentation source code</modulesummary>
<description>
- <p><c>docb_xml_check</c> contains functions for validating XML
+ <p><c>docgen_xml_check</c> contains functions for validating XML
documentation source code.</p>
</description>
diff --git a/lib/erl_docgen/doc/src/erl_docgen.txt b/lib/erl_docgen/doc/src/erl_docgen.txt
deleted file mode 100644
index 14a4dc8e10..0000000000
--- a/lib/erl_docgen/doc/src/erl_docgen.txt
+++ /dev/null
@@ -1,6 +0,0 @@
-
-
-
-/home/otptest/bin/otp_wrap_ssh boddington /home/otptest/bin/otp_build_doc -rel r13b02 -view otptest_r13_daily_doc2 -csfile /usr/local/otp/config-specs/r13_dev.cs -insdir /ldisk/daily_build
-_
- \ No newline at end of file
diff --git a/lib/erl_docgen/doc/src/gazonk b/lib/erl_docgen/doc/src/example.txt
index 1cf0b8f7bc..ad86165391 100644
--- a/lib/erl_docgen/doc/src/gazonk
+++ b/lib/erl_docgen/doc/src/example.txt
@@ -1,7 +1,7 @@
This example code is used in block_tags.xml.
%% Erlang example
--module(gazonk).
+-module(example).
start() ->
{error,"Pid required!"}.
diff --git a/lib/erl_docgen/doc/src/header_tags.xml b/lib/erl_docgen/doc/src/header_tags.xml
index b1456d679a..902bce4f68 100644
--- a/lib/erl_docgen/doc/src/header_tags.xml
+++ b/lib/erl_docgen/doc/src/header_tags.xml
@@ -104,7 +104,7 @@
<section>
<title>&lt;shorttitle&gt;</title>
- <p>This optional tag is ignored by DocBuilder. It will likely be
+ <p>This optional tag is ignored. It will likely be
removed in the future.</p>
</section>
@@ -112,8 +112,7 @@
<marker id="preparedTAG"></marker>
<title>&lt;prepared&gt;</title>
- <p>This tag is intended for administrative use and is ignored by
- DocBuilder.</p>
+ <p>This tag is intended for administrative use and is ignored.</p>
</section>
<section>
@@ -121,7 +120,7 @@
<title>&lt;responsible&gt;</title>
<p>This optional tag is intended for administrative use and is
- ignored by DocBuilder.</p>
+ ignored.</p>
</section>
<section>
@@ -141,7 +140,7 @@
<title>&lt;approved&gt;</title>
<p>This optional tag is intended for administrative use and is
- ignored by DocBuilder.</p>
+ ignored.</p>
</section>
<section>
@@ -149,15 +148,14 @@
<title>&lt;checked&gt;</title>
<p>This optional tag is intended for administrative use and is
- ignored by DocBuilder.</p>
+ ignored.</p>
</section>
<section>
<marker id="dateTAG"></marker>
<title>&lt;date&gt;</title>
- <p>This tag is intended for administrative use and is ignored by
- DocBuilder.</p>
+ <p>This tag is intended for administrative use and is ignored.</p>
</section>
<section>
@@ -177,7 +175,7 @@
<title>&lt;file&gt;</title>
<p>This optional tag is intended for administrative use and is
- ignored by DocBuilder.</p>
+ ignored.</p>
</section>
</chapter>
diff --git a/lib/erl_docgen/doc/src/inline_tags.xml b/lib/erl_docgen/doc/src/inline_tags.xml
index 5bcca54c05..9b27da659b 100644
--- a/lib/erl_docgen/doc/src/inline_tags.xml
+++ b/lib/erl_docgen/doc/src/inline_tags.xml
@@ -92,7 +92,7 @@
inline tag.</p>
</section>
- <section>
+ <!-- section>
<marker id="pathTAG"></marker>
<title>&lt;path&gt; - Path</title>
@@ -115,7 +115,7 @@
in:</p>
<p>"Look at the <path unix=".profile" windows="win.ini">start-up file</path>
if you intend to alter the initial behavior."</p>
- </section>
+ </section -->
<section>
<marker id="seealsoTAG"></marker>
@@ -150,16 +150,10 @@
<p>Note the use of "#" before the name of the marker. Note also
that the filename extension <c>.html</c> is omitted. This is
- because the default behavior of DocBuilder is to translate
+ because the default behavior is to translate
<c><![CDATA[<seealso marker="File#Marker">text</seealso>]]></c>
to <c><![CDATA[<A HREF="File.html#Marker">text</A>]]></c>.</p>
- <p>The default behaviour can be modified by using the callback
- module option to <c>docb_transform:file/1,2</c> and defining a
- callback function
- <seealso marker="docb_transform#Module:seealso-1">Module:seealso/1</seealso>.
- This possibility is for example used in OTP to resolve cross
- references between applications.</p>
</section>
<section>
@@ -192,28 +186,6 @@
<term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term>
]]></pre>
- <p>For a globally defined term, the tag is empty. Example:</p>
- <pre><![CDATA[
-<term id="HTML"/>
- ]]></pre>
-
- <p>Global definitions are given to DocBuilder in a file, using the
- <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>
- option <c>term_defs</c>. The file should contain a list of tuples,
- one for each term definition, on the format
- <c>{Id,Name,Definition,Owner}</c>. The <c>Owner</c> part is just
- for administration, if there are several people contributing to a
- term definition file. Example:</p>
- <pre>
-[...,
- {"HTML", "HTML", "Hyper-Text Markup Language", "Gunilla"},
- ...].
- </pre>
-
- <p>DocBuilder will collect both local and global definitions in a
- glossary, which can be reached from a link in the left frame of
- the HTML documentation.</p>
-
<p>In the generated HTML, it is the term name which will be visible.
For locally defined terms, the id and the name are the same.
The name has a hypertext link to the definition in the glossary.
@@ -237,21 +209,6 @@
<c>&lt;termdef&gt;</c>, but for a bibliography list rather than
a glossary.</p>
- <p>A global bibliography list is given to DocBuilder in a file,
- using the <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>
- option <c>cite_defs</c>. The file should contain a list of tuples,
- one for each cite, on the format
- <c>{Id,Title,Info,Owner}</c>. The <c>Owner</c> part is just
- for administration, if there are several people contributing to a
- bibliography file. Example:</p>
- <pre>
-[...,
- {"erlbook",
- "Concurrent Programming in ERLANG","J. Armstrong, R. Virding, C. Wikstr&ouml;m, "
- "M. Williams, Concurrent Programming in ERLANG, Prentice Hall, 1996, ISBN 0-13-508301-X",
- "jocke"},
- ...].
- </pre>
</section>
</chapter>
diff --git a/lib/erl_docgen/doc/src/notes.xml b/lib/erl_docgen/doc/src/notes.xml
index 6a0eece56d..9591b363f7 100644
--- a/lib/erl_docgen/doc/src/notes.xml
+++ b/lib/erl_docgen/doc/src/notes.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
@@ -21,14 +21,14 @@
</legalnotice>
- <title>erl_docgen Release Notes</title>
+ <title>Erl_Docgen Release Notes</title>
<prepared>otp_appnotes</prepared>
<docno>nil</docno>
<date>nil</date>
<rev>nil</rev>
<file>notes.xml</file>
</header>
- <p>This document describes the changes made to the erl_docgen application.</p>
+ <p>This document describes the changes made to the <em>erl_docgen</em> application.</p>
<section><title>Erl_Docgen 0.2.6</title>
diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml
index ca13c5d436..f0f97d8d45 100644
--- a/lib/erl_docgen/doc/src/overview.xml
+++ b/lib/erl_docgen/doc/src/overview.xml
@@ -29,28 +29,6 @@
</header>
<section>
- <title>Background</title>
-
- <p>DocBuilder has been used within the OTP project to generate
- documentation for Erlang/OTP itself for more than ten years.
- It has now been released as a regular Erlang/OTP application.</p>
-
- <p>The intention with DocBuilder is that it should be as easy to
- use and maintain as possible and generate adequate documentation
- for OTP's needs. It uses frames, which can probably be regarded as
- old-fashioned today. Hopefully, this should be improved in
- the future.</p>
-
- <p>Originally, DocBuilder input was SGML files and external tools
- was used for parsing. The internal version used in the OTP
- project can generate not only HTML code but also LaTeX (for PDF
- and PostScript) and nroff (for UNIX man pages). (Again, using
- external tools). Because of this, the parsed source code is
- transformed into a tree structure before being transformed again
- into the desired format.</p>
- </section>
-
- <section>
<title>DTD Suite</title>
<p>Input is written as XML according to one of the DTDs and output
@@ -94,10 +72,6 @@
the <c>application</c> or <c>part</c> DTD to write other types
of documentation for the application.</p>
- <p>A special kind of DTD,
- <seealso marker="fasc_dtds">fascicules</seealso>, can be used to
- specify the different parts of the documentation, and which one
- of those should be shown as default.</p>
</section>
<section>
@@ -120,7 +94,7 @@
<section>
<title>Basic Tags</title>
- <p>All DTDs in the DocBuilder DTD suite share a basic set of tags.
+ <p>All DTDs in the OTP DTD suite share a basic set of tags.
An author can easily switch from one DTD to another and still use
the same basic tags. It is furthermore easy to copy pieces of
information from one document to another, even though they do not
@@ -143,13 +117,13 @@
<p>For readability and simplicity, the examples have been kept as
short as possible. For an example of what the generated HTML
- will look like, it is recommended to look at the DocBuilder
- documentation itself:</p>
+ will look like, it is recommended to look at the documentation of
+ an OTP application.</p>
<list>
- <item>This User's Guide is written using the <c>part</c> and
+ <item>This User's Guides are written using the <c>part</c> and
<c>chapter</c> DTDs.</item>
- <item>The Reference Manual is written using
+ <item>The Reference Manuals are written using
the <c>application</c>, <c>appref</c> and <c>erlref</c> DTDs.
</item>
</list>
@@ -162,23 +136,19 @@
<item>
<p>Create the relevant XML files.</p>
- <p>If there are EDoc comments in a module, the function
- <seealso marker="docb_gen#module/1">docb_gen:module/1,2</seealso>
+ <p>If there are EDoc comments in a module, the escript
+ <!-- seealso marker="xml_from_edoc">xml_from_edoc</seealso -->
+ <c>xml_from_edoc</c>
can be used to generate an XML file according to
the <c>erlref</c> DTD for this module.</p>
</item>
- <item>
+ <!-- item>
<p>The XML files can be validated using
<seealso marker="docb_xml_check#validate/1">docb_xml_check:validate/1</seealso>.
</p>
- </item>
+ </item -->
- <item>
- <p>Generate HTML files by using
- <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>.
- </p>
- </item>
</list>
</section>
</chapter>
diff --git a/lib/erl_docgen/doc/src/part.xml b/lib/erl_docgen/doc/src/part.xml
index 546c6c612e..4594778a2f 100644
--- a/lib/erl_docgen/doc/src/part.xml
+++ b/lib/erl_docgen/doc/src/part.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE part SYSTEM "part.dtd">
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>2007</year><year>2009</year>
+ <year>2011</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -20,21 +20,20 @@
under the License.
</legalnotice>
- <title>DocBuilder User's Guide</title>
+ <title>Erl_Docgen User's Guide</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<description>
- <p><em>Docbuilder</em> provides functionality for generating HTML
+ <p><em>Erl_Docgen</em> provides functionality for generating HTML/PDF
documentation for Erlang modules and Erlang/OTP applications
from XML source code and/or EDoc comments in Erlang source code.</p>
</description>
<xi:include href="overview.xml"/>
<xi:include href="user_guide_dtds.xml"/>
<xi:include href="refman_dtds.xml"/>
- <xi:include href="fasc_dtds.xml"/>
<xi:include href="header_tags.xml"/>
<xi:include href="block_tags.xml"/>
<xi:include href="inline_tags.xml"/>
diff --git a/lib/erl_docgen/doc/src/ref_man.xml b/lib/erl_docgen/doc/src/ref_man.xml
new file mode 100644
index 0000000000..a92ab6c805
--- /dev/null
+++ b/lib/erl_docgen/doc/src/ref_man.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2011</year><year>2011</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.
+
+ </legalnotice>
+
+ <title>Erl_Docgen Reference Manual</title>
+ <prepared>OTP Team</prepared>
+ <docno></docno>
+ <date>2011-11-10</date>
+ <rev>0.3</rev>
+ <file>ref_man.xml</file>
+ </header>
+ <description>
+ <p>The <em>erl_docgen</em> supports the OTP documentation build.</p>
+ </description>
+ <xi:include href="docgen_xml_check.xml"/>
+</application>
+
diff --git a/lib/erl_docgen/doc/src/refman_dtds.xml b/lib/erl_docgen/doc/src/refman_dtds.xml
index a7beaed708..7b01c57db4 100644
--- a/lib/erl_docgen/doc/src/refman_dtds.xml
+++ b/lib/erl_docgen/doc/src/refman_dtds.xml
@@ -573,8 +573,8 @@
a <c><![CDATA[<nametext>]]></c> (function name and arguments,
plain text).</p>
- <p>In the case of an <c>erlref</c> DTD, DocBuilder will
- automatically try to add a
+ <p>In the case of an <c>erlref</c> DTD, it will
+ automatically be added a
<seealso marker="inline_tags#markerTAG">marker</seealso>,
<c><![CDATA[<marker id="Name/Arity">]]></c> or
<c><![CDATA[<marker id="Name">]]></c>, based on the contents of
@@ -585,7 +585,7 @@
<name>foo(Arg1, Arg2) -> ok | {error, Reason}</name>
]]></pre>
- <p>DocBuilder will create a marker
+ <p>Then a marker like this will be added
<c><![CDATA[<marker id="foo/2">]]></c> before the function
definition in the generated HTML. That is, referring to
the function using
diff --git a/lib/erl_docgen/vsn.mk b/lib/erl_docgen/vsn.mk
index 79c8c570bf..dbd7e017b0 100644
--- a/lib/erl_docgen/vsn.mk
+++ b/lib/erl_docgen/vsn.mk
@@ -1,2 +1,2 @@
-ERL_DOCGEN_VSN = 0.2.6
+ERL_DOCGEN_VSN = 0.3