From 2da3a1fb06caf0c7fc53a8efdfbc769278b4323f Mon Sep 17 00:00:00 2001 From: Lars Thorsen Date: Wed, 16 Nov 2011 15:10:18 +0100 Subject: [erl_docgen] Move files from docbuilder to erl_docgen --- lib/erl_docgen/doc/src/block_tags.xml | 431 +++++++ lib/erl_docgen/doc/src/character_entities.xml | 546 +++++++++ lib/erl_docgen/doc/src/docb_xml_check.xml | 59 + lib/erl_docgen/doc/src/fasc_dtds.xml | 115 ++ lib/erl_docgen/doc/src/fascicules.xml | 15 + lib/erl_docgen/doc/src/gazonk | 17 + lib/erl_docgen/doc/src/header_tags.xml | 183 +++ lib/erl_docgen/doc/src/inline_tags.xml | 257 ++++ lib/erl_docgen/doc/src/man.gif | Bin 0 -> 6048 bytes lib/erl_docgen/doc/src/overview.xml | 185 +++ lib/erl_docgen/doc/src/part.xml | 43 + lib/erl_docgen/doc/src/refman_dtds.xml | 667 +++++++++++ lib/erl_docgen/doc/src/user_guide_dtds.xml | 181 +++ lib/erl_docgen/priv/docbuilder_dtd/Makefile | 99 -- lib/erl_docgen/priv/docbuilder_dtd/application.dtd | 29 - lib/erl_docgen/priv/docbuilder_dtd/appref.dtd | 33 - lib/erl_docgen/priv/docbuilder_dtd/book.dtd | 73 -- .../priv/docbuilder_dtd/bookinsidecover.dtd | 36 - lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd | 36 - lib/erl_docgen/priv/docbuilder_dtd/cites.dtd | 35 - lib/erl_docgen/priv/docbuilder_dtd/common.dtd | 87 -- .../priv/docbuilder_dtd/common.entities.dtd | 24 - .../priv/docbuilder_dtd/common.header.dtd | 42 - .../priv/docbuilder_dtd/common.image.dtd | 21 - lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd | 43 - .../priv/docbuilder_dtd/common.table.dtd | 25 - lib/erl_docgen/priv/docbuilder_dtd/comref.dtd | 31 - lib/erl_docgen/priv/docbuilder_dtd/cref.dtd | 34 - lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd | 31 - lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd | 35 - lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd | 31 - lib/erl_docgen/priv/docbuilder_dtd/part.dtd | 29 - lib/erl_docgen/priv/docbuilder_dtd/report.dtd | 138 --- lib/erl_docgen/priv/docbuilder_dtd/terms.dtd | 36 - .../priv/docbuilder_dtd/xhtml1-frameset.dtd | 1235 -------------------- .../priv/docbuilder_dtd/xhtml1-strict.dtd | 978 ---------------- .../priv/docbuilder_dtd/xhtml1-transitional.dtd | 1201 ------------------- lib/erl_docgen/priv/dtd/Makefile | 99 ++ lib/erl_docgen/priv/dtd/application.dtd | 29 + lib/erl_docgen/priv/dtd/appref.dtd | 33 + lib/erl_docgen/priv/dtd/book.dtd | 73 ++ lib/erl_docgen/priv/dtd/bookinsidecover.dtd | 36 + lib/erl_docgen/priv/dtd/chapter.dtd | 36 + lib/erl_docgen/priv/dtd/cites.dtd | 35 + lib/erl_docgen/priv/dtd/common.dtd | 87 ++ lib/erl_docgen/priv/dtd/common.entities.dtd | 24 + lib/erl_docgen/priv/dtd/common.header.dtd | 42 + lib/erl_docgen/priv/dtd/common.image.dtd | 21 + lib/erl_docgen/priv/dtd/common.refs.dtd | 43 + lib/erl_docgen/priv/dtd/common.table.dtd | 25 + lib/erl_docgen/priv/dtd/comref.dtd | 31 + lib/erl_docgen/priv/dtd/cref.dtd | 34 + lib/erl_docgen/priv/dtd/erlref.dtd | 31 + lib/erl_docgen/priv/dtd/fascicules.dtd | 35 + lib/erl_docgen/priv/dtd/fileref.dtd | 31 + lib/erl_docgen/priv/dtd/part.dtd | 29 + lib/erl_docgen/priv/dtd/report.dtd | 138 +++ lib/erl_docgen/priv/dtd/terms.dtd | 36 + lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd | 1235 ++++++++++++++++++++ lib/erl_docgen/priv/dtd/xhtml1-strict.dtd | 978 ++++++++++++++++ lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd | 1201 +++++++++++++++++++ lib/erl_docgen/src/docgen_edoc_xml_cb.erl | 1154 ++++++++++++++++++ lib/erl_docgen/src/docgen_otp_specs.erl | 713 +++++++++++ lib/erl_docgen/src/docgen_xmerl_xml_cb.erl | 88 ++ lib/erl_docgen/src/docgen_xml_check.erl | 45 + lib/erl_docgen/src/otp_specs.erl | 713 ----------- 66 files changed, 9061 insertions(+), 5075 deletions(-) create mode 100644 lib/erl_docgen/doc/src/block_tags.xml create mode 100644 lib/erl_docgen/doc/src/character_entities.xml create mode 100644 lib/erl_docgen/doc/src/docb_xml_check.xml create mode 100644 lib/erl_docgen/doc/src/fasc_dtds.xml create mode 100644 lib/erl_docgen/doc/src/fascicules.xml create mode 100644 lib/erl_docgen/doc/src/gazonk create mode 100644 lib/erl_docgen/doc/src/header_tags.xml create mode 100644 lib/erl_docgen/doc/src/inline_tags.xml create mode 100644 lib/erl_docgen/doc/src/man.gif create mode 100644 lib/erl_docgen/doc/src/overview.xml create mode 100644 lib/erl_docgen/doc/src/part.xml create mode 100644 lib/erl_docgen/doc/src/refman_dtds.xml create mode 100644 lib/erl_docgen/doc/src/user_guide_dtds.xml delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/Makefile delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/application.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/appref.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/book.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/cites.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/common.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/comref.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/cref.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/part.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/report.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/terms.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd delete mode 100644 lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd create mode 100644 lib/erl_docgen/priv/dtd/Makefile create mode 100644 lib/erl_docgen/priv/dtd/application.dtd create mode 100644 lib/erl_docgen/priv/dtd/appref.dtd create mode 100644 lib/erl_docgen/priv/dtd/book.dtd create mode 100644 lib/erl_docgen/priv/dtd/bookinsidecover.dtd create mode 100644 lib/erl_docgen/priv/dtd/chapter.dtd create mode 100644 lib/erl_docgen/priv/dtd/cites.dtd create mode 100644 lib/erl_docgen/priv/dtd/common.dtd create mode 100644 lib/erl_docgen/priv/dtd/common.entities.dtd create mode 100644 lib/erl_docgen/priv/dtd/common.header.dtd create mode 100644 lib/erl_docgen/priv/dtd/common.image.dtd create mode 100644 lib/erl_docgen/priv/dtd/common.refs.dtd create mode 100644 lib/erl_docgen/priv/dtd/common.table.dtd create mode 100644 lib/erl_docgen/priv/dtd/comref.dtd create mode 100644 lib/erl_docgen/priv/dtd/cref.dtd create mode 100644 lib/erl_docgen/priv/dtd/erlref.dtd create mode 100644 lib/erl_docgen/priv/dtd/fascicules.dtd create mode 100644 lib/erl_docgen/priv/dtd/fileref.dtd create mode 100644 lib/erl_docgen/priv/dtd/part.dtd create mode 100644 lib/erl_docgen/priv/dtd/report.dtd create mode 100644 lib/erl_docgen/priv/dtd/terms.dtd create mode 100644 lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd create mode 100644 lib/erl_docgen/priv/dtd/xhtml1-strict.dtd create mode 100644 lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd create mode 100644 lib/erl_docgen/src/docgen_edoc_xml_cb.erl create mode 100644 lib/erl_docgen/src/docgen_otp_specs.erl create mode 100644 lib/erl_docgen/src/docgen_xmerl_xml_cb.erl create mode 100644 lib/erl_docgen/src/docgen_xml_check.erl delete mode 100644 lib/erl_docgen/src/otp_specs.erl (limited to 'lib/erl_docgen') diff --git a/lib/erl_docgen/doc/src/block_tags.xml b/lib/erl_docgen/doc/src/block_tags.xml new file mode 100644 index 0000000000..f5ba083f38 --- /dev/null +++ b/lib/erl_docgen/doc/src/block_tags.xml @@ -0,0 +1,431 @@ + + + + +
+ + 19972009 + 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. + + + + Block Tags + + + + + block_tags.xml +
+ +

Block tags typically define a separate block of information, such + as a paragraph or a list.

+ +

The following subset of block tags are common for all DTDs in + the DocBuilder DTD suite: + + <p>, + <pre>, + <code>, + <list>, + <taglist>, + <codeinclude> and + <erleval>. +

+ +
+ + <br> - Line Break + +

Forces a newline. Example:

+ 
+Eat yourself<br/>senseless!
+
+

results in:

+

Eat yourself
senseless!

+ +

The ]]> tag is both a block- and an inline + tag.

+
+ +
+ + <code> - Code Example + +

Highlight code examples. Example:

+ 
+<code>
+sum([H|T]) ->
+    H + sum(T);
+sum([]) ->
+    0.
+</code>
+
+

results in:

+ +sum([H|T]) -> + H + sum(T); +sum([]) -> + 0. + + +

There is an attribute type = "erl" | "c" | "none", but + currently this attribute is ignored by DocBuilder. Default value + is "none"

+ + +

No tags are allowed within the tag and no + character + entities are expanded.

+ +
+ +
+ + <codeinclude> - Code Inclusion + +

Include external code snippets. The attribute file + gives the file name and tag defines a string which + delimits the code snippet. Example:

+ 
+<codeinclude file="gazonk" tag="%% Erlang example"/>
+
+

results in:

+ + +

provided there is a file named gazonk looking like this: +

+ +... + +%% Erlang example +-module(gazonk). + +start() -> + {error,"Pid required!"}. +start(Pid) -> + spawn(fun() -> init(Pid) end). +%% Erlang example + +... + + +

If the tag attribute is omitted, the whole file is + included.

+ +

There is also an attribute type = "erl" | "c" | "none", but + currently this attribute is ignored by DocBuilder. Default value + is "none"

+
+ +
+ + <erleval> - Erlang Evaluation + +

Include the result from evaluating an Erlang expression. Example: +

+ + ]]> +

results in:

+ + +

Note the '.' and space after the expression.

+
+ +
+ + <list> - List + +

The attribute type = "ordered"|"bulleted" decides if + the list is numbered or bulleted. Default is "bulleted". +

+ +

Lists contains list items, tag ]]>, which + can contain plain text, + the common subset of block + tags and inline + tags. Example:

+ 
+<list type="ordered">
+  <item>Askosal:
+    <list>
+      <item>Nullalisis</item>
+      <item>Facilisis</item>
+    </list>
+  </item>
+  <item>Ankara</item>
+</list>
+
+

results in:

+ + +

Askosal:

+ + Nullalisis + Facilisis + + + Ankara + +
+ +
+ + <marker> - Marker + +

Used as an anchor for hypertext references. The + ]]> tag is both a block- and an inline + tag and is described in + the Inline Tags + section.

+
+ +
+ + <p> - Paragraph + +

Paragraphs contain plain text and + inline tags. Example:

+ 
+<p>I call specific attention to
+  the authority given by the <em>21st Amendment</em>
+  to the Constitution to prohibit transportation
+  or importation of intoxicating liquors into
+  any State in violation of the laws of such
+  State.</p>
+
+

results in:

+

I call specific attention to + the authority given by the 21st Amendment + to the Constitution to prohibit transportation + or importation of intoxicating liquors into + any State in violation of the laws of such + State.

+
+ +
+ + <note> - Note + +

Highlights a note. Can contain block tags except + ]]>, ]]>, + ]]> and ]]>. + Example:

+
+<note>
+  <p>This function is mainly intended for debugging.</p>
+</note>
+
+

results in:

+ +

This function is mainly intended for debugging.

+ +
+ +
+ + <pre> - Pre-formatted Text + +

Used for documentation of system interaction. Can contain text, + seealso, + url and + ]]> tags.

+ +

The ]]> tag is used to highlight user + input. Example:

+ 
+<pre>
+$ <input>erl</input>
+Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false]
+
+Eshell V5.5.3  (abort with ^G)
+1> <input>pwd().</input>
+/home/user
+2> <input>halt().</input>
+</pre>
+
+

results in:

+ 
+$ erl
+Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false]
+
+Eshell V5.5.3  (abort with ^G)
+1> pwd().
+/home/user
+2> halt().
+
+ +

All character + entities are expanded.

+
+ +
+ + <quote> - Quotation + +

Highlight quotations from other works, or dialog spoken by + characters in a narrative. Contains one or more + <p> tags. Example:

+ 
+<p>Whereas Section 217(a) of the Act of Congress entitled
+"An Act ..." approved June 16, 1933, provides as follows:</p>
+<quote>
+  <p>Section 217(a) The President shall proclaim the law.</p>
+</quote>
+
+

results in:

+

Whereas Section 217(a) of the Act of Congress entitled + "An Act ..." approved June 16, 1933, provides as follows:

+ +

Section 217(a) The President shall proclaim the law.

+ +
+ +
+ + + <taglist> - Definition List + +

Definition lists contains pairs of tags, + ]]>, and list items, + ]]>.

+ +

]]> can contain plain text, + <c>, + <em>, + <seealso> + and <url> + tags.

+ +

]]> can contain plain text, + the common subset of block + tags and inline + tags. Example:

+ 
+<taglist>
+  <tag><c>eacces</c></tag>
+  <item>Permission denied.</item>
+  <tag><c>enoent</c></tag>
+  <item>No such file or directory.</item>
+</taglist>
+
+

results in:

+ + eacces + Permission denied. + enoent + No such file or directory. + +
+ +
+ + <warning> - Warning + +

Highlights a warning. Can contain block tags except + ]]>, ]]>, + ]]> and ]]>. + Example:

+
+<warning>
+  <p>This function might be removed in a future version without
+    prior warning.</p>
+</warning>
+
+

results in:

+ +

This function might be removed in a future version without + prior warning.

+ +
+ +
+ + + <image> - Image + +

Graphics is imported using the ]]> tag. + An image caption ]]>, containing plain + text, must be supplied. Example:

+ 
+<image file="man">
+  <icaption>A Silly Man</icaption>
+</image>
+
+

results in:

+ + A Silly Man + + +

This assumes that man.gif exists in the current directory. +

+
+ +
+ + + + + <table> - Table + +

The table format is similar to how tables are described in HTML + 3.2. A table contains one or more rows, ]]>, + and a table caption ]]>, containing + plain text.

+ +

Each row contains one or more cells, ]]>. + The attributes align = "left"|"center"|"right" and + valign = "top"|"middle"|"bottom" decides how text is + aligned in the cell horizontally and vertically. Default is + "left" and "middle".

+ +

Each cell contains plain text and + inline tags. Example:

+ 

+      
+        Boys
+        Girls
+      
+      
+        Juda
+        Susy
+      
+      
+        Anders
+        Victoria
+      
+      A table caption
+    
+    ]]>
+

results in:

+ + + Boys + Girls + + + Juda + Susy + + + Anders + Victoria + + A table caption +
+
+ + diff --git a/lib/erl_docgen/doc/src/character_entities.xml b/lib/erl_docgen/doc/src/character_entities.xml new file mode 100644 index 0000000000..0a4ae17fb5 --- /dev/null +++ b/lib/erl_docgen/doc/src/character_entities.xml @@ -0,0 +1,546 @@ + + + + +
+ + 19972011 + 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. + + + + Character Entities + + + + + character_entities.xml +
+ +
+ Added Latin 1 + +

The DocBuilder DTD suite uses the same character entities as + defined in HTML 3.2 + (ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML). That is: + for an & (ampersand), use the entity: &amp;, for + ö use the entity &ouml; and so on.

+ + + + Character + Entity + Description + + + & + &amp; + ampersand + + + > + &gt; + greater than + + + < + &lt; + less than + + +   + &nbsp; + no-break space + + + ¡ + &iexcl; + inverted exclamation mark + + + ¢ + &cent; + cent sign + + + £ + &pound; + pound sterling sign + + + ¤ + &curren; + general currency sign + + + ¥ + &yen; + yen sign + + + ¦ + &brvbar; + broken (vertical) bar + + + § + &sect; + section sign + + + ¨ + &uml; + umlaut (dieresis) + + + © + &copy; + copyright sign + + + ª + &ordf; + ordinal indicator, feminine + + + « + &laquo; + angle quotation mark, left + + + ¬ + &not; + not sign + + + + &shy; + soft hyphen + + + ® + &reg; + registered sign + + + ¯ + &macr; + macron + + + ° + &deg; + degree sign + + + ± + &plusmn; + plus-or-minus + + + ² + &sup2; + superscript two + + + ³ + &sup3; + superscript three + + + ´ + &acute; + acute accent + + + µ + &micro; + micro sign + + + + &para; + pilcrow (paragraph sign) + + + · + &middot; + middle dot + + + ¸ + &cedil; + cedilla + + + ¹ + &sup1; + superscript one + + + º + &ordm; + ordinal indicator, masculine + + + » + &raquo; + angle quotation mark, right + + + ¼ + &frac14; + fraction one-quarter + + + ½ + &frac12; + fraction one-half + + + ¾ + &frac34; + fraction three-quarters + + + ¿ + &iquest; + inverted question mark + + + À + &Agrave; + capital A, grave accent + + + Á + &Aacute; + capital A, acute accent + + + Â + &Acirc; + capital A, circumflex accent + + + Ã + &Atilde; + capital A, tilde + + + Ä + &Auml; + capital A, dieresis or umlaut mark + + + Å + &Aring; + capital A, ring + + + Æ + &AElig; + capital AE diphthong (ligature) + + + Ç + &Ccedil; + capital C, cedilla + + + È + &Egrave; + capital E, grave accent + + + É + &Eacute; + capital E, acute accen + + + Ê + &Ecirc; + capital E, circumflex accent + + + Ë + &Euml; + capital E, dieresis or umlaut mark + + + Ì + &Igrave; + capital I, grave accent + + + Í + &Iacute; + capital I, acute accent + + + Î + &Icirc; + capital I, circumflex accent + + + Ï + &Iuml; + capital I, dieresis or umlaut mark + + + Ð + &ETH; + capital Eth, Icelandic + + + Ñ + &Ntilde; + capital N, tilde + + + Ò + &Ograve; + capital O, grave accent + + + Ó + &Oacute; + capital O, acute accent + + + Ô + &Ocirc; + capital O, circumflex accent + + + Õ + &Otilde; + capital O, tilde + + + Ö + &Ouml; + capital O, dieresis or umlaut mark + + + × + &times; + multiply sign + + + Ø + &Oslash; + capital O, slash + + + Ù + &Ugrave; + capital U, grave accent + + + Ú + &Uacute; + capital U, acute accent + + + Û + &Ucirc; + capital U, circumflex accent + + + Ü + &Uuml; + capital U, dieresis or umlaut mark + + + Ý + &Yacute; + capital Y, acute accent + + + Þ + &THORN; + capital THORN, Icelandic + + + ß + &szlig; + small sharp s, German (sz ligature) + + + à + &agrave; + small a, grave accent + + + á + &aacute; + small a, acute accent + + + â + &acirc; + small a, circumflex accent + + + ã + &atilde; + small a, tilde + + + ä + &auml; + small a, dieresis or umlaut mark + + + å + &aring; + small a, ring + + + æ + &aelig; + small ae diphthong (ligature) + + + ç + &ccedil; + small c, cedilla + + + è + &egrave; + small e, grave accent + + + é + &eacute; + small e, acute accent + + + ê + &ecirc; + small e, circumflex accent + + + ë + &euml; + small e, dieresis or umlaut mark + + + ì + &igrave; + small i, grave accent + + + í + &iacute; + small i, acute accent + + + î + &icirc; + small i, circumflex accent + + + ï + &iuml; + small i, dieresis or umlaut mark + + + ð + &eth; + small eth, Icelandic + + + ñ + &ntilde; + small n, tilde + + + ò + &ograve; + small o, grave accent + + + ó + &oacute; + small o, acute accent + + + ô + &ocirc; + small o, circumflex accent + + + õ + &otilde; + small o, tilde + + + ö + &ouml; + small o, dieresis or umlaut mark + + + ÷ + &divide; + divide sign + + + ø + &oslash; + small o, slash + + + ù + &ugrave; + small u, grave accent + + + ú + &uacute; + small u, acute accent + + + û + &ucirc; + small u, circumflex accent + + + ü + &uuml; + small u, dieresis or umlaut mark + + + ý + &yacute; + small y, acute accent + + + þ + &thorn; + small thorn, Icelandic + + + ÿ + &yuml; + small y, dieresis or umlaut mark + + Accented Latin-1 alphabetic characters. +
+
+ + diff --git a/lib/erl_docgen/doc/src/docb_xml_check.xml b/lib/erl_docgen/doc/src/docb_xml_check.xml new file mode 100644 index 0000000000..eff4fc4342 --- /dev/null +++ b/lib/erl_docgen/doc/src/docb_xml_check.xml @@ -0,0 +1,59 @@ + + + + +
+ + 2007 + 2011 + 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_xml_check + + + + +
+ docb_xml_check + Validate XML documentation source code + +

docb_xml_check contains functions for validating XML + documentation source code.

+ + + + + validate(File) -> ok | error | {error, badfile} + Validate XML source code. + + File = string() + + +

Validates the XML documentation source code in File. + The .xml extension can be omitted.

+ +

Returns ok if successful, otherwise error information + is printed and the function returns error. + If File does not exist, {error, badfile} is + returned.

+ + + + + + diff --git a/lib/erl_docgen/doc/src/fasc_dtds.xml b/lib/erl_docgen/doc/src/fasc_dtds.xml new file mode 100644 index 0000000000..dec8189b55 --- /dev/null +++ b/lib/erl_docgen/doc/src/fasc_dtds.xml @@ -0,0 +1,115 @@ + + + + +
+ + 20072009 + 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. + + + + Fascicules DTDs + + + + + fasc_dtds.xml +
+ +
+ The fascicules DTD + +

The fascicules DTD is a special kind of DTD which can be + used to specify the different parts of the documentation, and + which one of those should be shown as default.

+ +

Example:

+ + 

+
+
+  
+    User's Guide
+  
+  
+    Reference Manual
+  
+  
+    Release Notes
+  
+
+    ]]>
+ +

In the example, it is specified that the documentation for this + application consists of three parts: User's Guide, where + the "cover page" (with the two frames) is located in + part_frame.html, Reference Manual with the cover page + ref_man_frame.html and Release Notes with the cover page + part_notes_frame.html.

+ +

As a result, at the top of the left frame in the generated HTML + documentation, there will be corresponding links to User's Guide, + Reference Manual and Release Notes.

+ +

The attribute entry="yes" specifies that it is + the Reference Manual which should be shown as default. This means + that when generating the HTML files, application_frame.html + will be copied to index.html.

+ + +

DocBuilder assumes that the XML file written according to + the fascicules DTD is called fascicules.xml.

+ + +

This file is optional. If it does not exist, there are no links + to other parts of the documentation (as they are not known) in + the left frame, and no index.html is created.

+
+ +
+ + <fascicules> + +

Top level tag for the fascicules DTD.

+ +

Contains one or more + <fascicule>.

+
+ +
+ + <fascicule> + +

Specifies properties for one "part" of the documentation for an + application.

+ +

Contains plain text, the name of this part.

+ +

The file attribute should specify the file name for + the corresponding part or application, without + the .xml extension.

+ +

The href attribute should specify the file name for + the corresponding HTML cover page file, without the .html + extension.

+ +

The optional entry="yes"|"no" attribute specifies if + the HTML cover page should be copied to index.html or + not. Default is "no".

+
+ + diff --git a/lib/erl_docgen/doc/src/fascicules.xml b/lib/erl_docgen/doc/src/fascicules.xml new file mode 100644 index 0000000000..1b9d6bc94d --- /dev/null +++ b/lib/erl_docgen/doc/src/fascicules.xml @@ -0,0 +1,15 @@ + + + + + + User's Guide + + + Reference Manual + + + Release Notes + + + diff --git a/lib/erl_docgen/doc/src/gazonk b/lib/erl_docgen/doc/src/gazonk new file mode 100644 index 0000000000..1cf0b8f7bc --- /dev/null +++ b/lib/erl_docgen/doc/src/gazonk @@ -0,0 +1,17 @@ +This example code is used in block_tags.xml. + +%% Erlang example +-module(gazonk). + +start() -> + {error,"Pid required!"}. + +start(Pid) -> + spawn(smalltalk,main,[]). +%% Erlang example + +// A little C example +int main() { + for(;;); +} +// A little C example diff --git a/lib/erl_docgen/doc/src/header_tags.xml b/lib/erl_docgen/doc/src/header_tags.xml new file mode 100644 index 0000000000..b1456d679a --- /dev/null +++ b/lib/erl_docgen/doc/src/header_tags.xml @@ -0,0 +1,183 @@ + + + + +
+ + 19972009 + 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. + + + + Header Tags + + + + + header_tags.xml +
+ +

Each document begins with a header part, which looks the same for + all DTDs. Here the title of the document is specified, as well as + administrative data like who is responsible for the document, which + version is it, when was it last changed and such.

+ +

An full header looks like:

+ 
+<header>
+  <copyright>...</copyright>
+  <legalnotice>...</legalnotice>
+  <title>...</title>
+  <prepared>...</prepared>
+  <responsible>...</responsible>
+  <docno>...</docno>
+  <approved>...</approved>
+  <checked>...</checked>
+  <date>...</date>
+  <rev>...</rev>
+  <file>...</file>
+</header>
+
+ +
+ + <header> + +

Top level tag for the header part.

+
+ +
+ + <copyright> + +

The copyright element holds information about date(s) and holder(s) of + a document copyright. The copyright element is optional. + The copyright element has an inner structure containing one or + more + year elements followed by zero of more holder elements.
+ See example below: +

+ + 1997 + 2007 + Ericsson AB + + ]]> +
+ +
+ + <legalnotice> + +

The legalnotice element is used to express copyright, trademark, + license, and other legal formalities of a document. The element contains + only PCDATA in the same manner as code and pre. +

+
+ +
+ + <title> + +

For part and application documents, this will be + the title of the document, visible in the left frame and on + the front page.

+ +

For chapter documents, this will be the chapter name.

+ +

For reference manual documents, this tag is ignored.

+
+ +
+ <shorttitle> + +

This optional tag is ignored by DocBuilder. It will likely be + removed in the future.

+
+ +
+ + <prepared> + +

This tag is intended for administrative use and is ignored by + DocBuilder.

+
+ +
+ + <responsible> + +

This optional tag is intended for administrative use and is + ignored by DocBuilder.

+
+ +
+ + <docno> + +

Document number.

+ +

For part and application documents, the document + number is visible in the left frame and on the front page.

+ +

For other types of documents, this tag is ignored.

+
+ +
+ + <approved> + +

This optional tag is intended for administrative use and is + ignored by DocBuilder.

+
+ +
+ + <checked> + +

This optional tag is intended for administrative use and is + ignored by DocBuilder.

+
+ +
+ + <date> + +

This tag is intended for administrative use and is ignored by + DocBuilder.

+
+ +
+ + <rev> + +

Document version.

+ +

For part and application documents, the document + version is visible in the left frame and on the front page.

+ +

For other types of documents, this tag is ignored.

+
+ +
+ + <file> + +

This optional tag is intended for administrative use and is + ignored by DocBuilder.

+
+ + diff --git a/lib/erl_docgen/doc/src/inline_tags.xml b/lib/erl_docgen/doc/src/inline_tags.xml new file mode 100644 index 0000000000..5bcca54c05 --- /dev/null +++ b/lib/erl_docgen/doc/src/inline_tags.xml @@ -0,0 +1,257 @@ + + + + +
+ + 19972011 + 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. + + + + Inline Tags + + + + + inline_tags.xml +
+ +

Inline tags are typically used within block tags, for example to + highlight a word within a paragraph.

+ +
+ + <br> - Line Break + +

Forces a newline. The ]]> tag is both a + block- and an inline tag and is described in + the Block Tags + section.

+
+ +
+ + <c> - Code + +

Highlights things like variables and file names in a text flow. + Can contain plain text only. Newlines and tabs are ignored as + opposed to the code + tag. All character + entities are expanded. Example:

+ 
+<p>Returns <c>true</c> if <c>Term</c> is an integer.</p>
+
+

results in:

+

Returns true if Term is an integer.

+
+ +
+ + <em> - Emphasis + +

Highlights words which are important within a text flow. Example: +

+ 
+<p>The application <em>must</em> be up and running.</p>
+
+

results in:

+

The application must be up and running.

+ +

Contains plain text or a + <c> tag.

+
+ +
+ + <marker> - Marker + +

Used as an anchor for hypertext references. The id + attribute defines the name of the marker. Example:

+ + 
+<marker id="marker_example"/>
+
+ +

The <seealso> tag + is used to refer to the marker.

+ +

The ]]> tag is both a block- and an + inline tag.

+
+ +
+ + <path> - Path + +

Highlights file paths. The attributes unix and + windows makes it possible to specify different paths for + different file path notations. Default for both are "". + Example:

+ 
+<p>Look at the <path unix=".profile" windows="win.ini">start-up file</path>
+  if you intend to alter the initial behavior.</p>
+
+

If no ptype option is specified when calling + docb_transform:file/1,2, + this simply results in:

+

"Look at the start-up file + if you intend to alter the initial behavior."

+ +

If both the options {ptype,unix} and + {ptype,windows} are specified, the example instead results + in:

+

"Look at the start-up file + if you intend to alter the initial behavior."

+
+ +
+ + <seealso> - Local Cross Reference + +

A cross reference (hypertext link) to a marker in the same file, + a marker in another file, or (the top of) another file, given by + the marker attribute. Must contain plain text. Examples: +

+ + 
marker example
+    ]]>
+

results in: + marker example + (a hypertext link to the marker example above).

+ + 
marker tag
+    ]]>
+

results in: + marker tag + (a hypertext link to the marker section in the Block Tags + chapter).

+ + 
Overview
+    ]]>
+

results in: + Overview + (a hypertext link to the Overview chapter).

+ +

Note the use of "#" before the name of the marker. Note also + that the filename extension .html is omitted. This is + because the default behavior of DocBuilder is to translate + text]]> + to text]]>.

+ +

The default behaviour can be modified by using the callback + module option to docb_transform:file/1,2 and defining a + callback function + Module:seealso/1. + This possibility is for example used in OTP to resolve cross + references between applications.

+
+ +
+ + <url> - Non-Local Cross Reference + +

A reference to a file outside the documentation, a web address or + similar, given by the href attribute. Must contain plain + text. Example:

+ 
erlang.org
+    ]]>
+

results in: erlang.org +

+
+ +
+ + + <term>, <termdef> - Glossary + +

Used to highlight a term with a local (for this document only) or + global definition. The identity of the term is given by + the id attribute.

+ +

For a locally defined term, the tag contains a + <termdef>, which in turn contains an explanation of + the term as plain text. Example:

+ 
Hyper-Text Markup Language
+      ]]>
+ +

For a globally defined term, the tag is empty. Example:

+ 

+      ]]>
+ +

Global definitions are given to DocBuilder in a file, using the + docb_transform:file/1,2 + option term_defs. The file should contain a list of tuples, + one for each term definition, on the format + {Id,Name,Definition,Owner}. The Owner part is just + for administration, if there are several people contributing to a + term definition file. Example:

+ 
+[...,
+ {"HTML", "HTML", "Hyper-Text Markup Language", "Gunilla"},
+ ...].
+
+ +

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.

+ +

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. + Example:

+ 
Hyper-Text Markup Language
+      ]]>
+

results in: Hyper-Text Markup Language +

+ +

If a term is defined both locally and globally, the global + definition takes precedence.

+
+ +
+ + + <cite>, <citedef> - Bibliography + +

Works the same way as <term> and + <termdef>, but for a bibliography list rather than + a glossary.

+ +

A global bibliography list is given to DocBuilder in a file, + using the docb_transform:file/1,2 + option cite_defs. The file should contain a list of tuples, + one for each cite, on the format + {Id,Title,Info,Owner}. The Owner part is just + for administration, if there are several people contributing to a + bibliography file. Example:

+ 
+[...,
+ {"erlbook",
+  "Concurrent Programming in ERLANG","J. Armstrong, R. Virding, C. Wikström, "
+  "M. Williams, Concurrent Programming in ERLANG, Prentice Hall, 1996, ISBN 0-13-508301-X",
+  "jocke"},
+ ...].
+
+
+ + diff --git a/lib/erl_docgen/doc/src/man.gif b/lib/erl_docgen/doc/src/man.gif new file mode 100644 index 0000000000..8656c7443d Binary files /dev/null and b/lib/erl_docgen/doc/src/man.gif differ diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml new file mode 100644 index 0000000000..ca13c5d436 --- /dev/null +++ b/lib/erl_docgen/doc/src/overview.xml @@ -0,0 +1,185 @@ + + + + +
+ + 19972009 + 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. + + + Overview + + + + + overview.xml +
+ +
+ Background + +

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.

+ +

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.

+ +

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.

+
+ +
+ DTD Suite + +

Input is written as XML according to one of the DTDs and output + is corresponding HTML. Documentation for an Erlang/OTP application + is usually organized as follows:

+ + User's Guide + +

(DTD: + part) + A collection of chapters + (chapter). +

+ + + Reference Manual + +

(DTD: + application + A collection of manual pages for modules + (erlref), + applications + (appref), + commands + (comref), + C libraries + (cref) and + files + (fileref). +

+ + + Release Notes + +

Same structure as the User's Guide.

+ + + +

In some cases, one or more of the User's Guide, Reference Manual + and Release Notes are omitted. Also, it is possible to use either + the application or part DTD to write other types + of documentation for the application.

+ +

A special kind of DTD, + fascicules, can be used to + specify the different parts of the documentation, and which one + of those should be shown as default.

+
+ +
+ Structure of Generated HTML + +

The generated HTML corresponding to a part or + application document is split into a left frame and a right + frame. The left frame contains information about the document + and links to the included files, that is chapters or manual pages. + The right frame is used to display either the front page for + the document, or the selected chapter/manual page.

+ +

The left frame also contains links to a bibliography and a + glossary, which are automatically generated.

+ +

In the case of an application document, the left frame + also contains a link to an automatically generated index.

+
+ +
+ Basic Tags + +

All DTDs in the DocBuilder 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 + use the same DTD.

+ +

The basic set of tags are divided into two categories: + block tags and + inline tags. Block tags + typically define a separate block of information, like a + paragraph or a list. Inline tags are typically used within block + tags, for example a highlighted word within a paragraph.

+
+ +
+ About This Document + +

In this User's Guide, the structure of the different documents + and the meaning of the tags are explained. There are numerous + examples of documentation source code.

+ +

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:

+ + This User's Guide is written using the part and + chapter DTDs. + + The Reference Manual is written using + the application, appref and erlref DTDs. + + +
+ +
+ Usage + + + +

Create the relevant XML files.

+ +

If there are EDoc comments in a module, the function + docb_gen:module/1,2 + can be used to generate an XML file according to + the erlref DTD for this module.

+ + + +

The XML files can be validated using + docb_xml_check:validate/1. +

+ + + +

Generate HTML files by using + docb_transform:file/1,2. +

+ + +
+ + diff --git a/lib/erl_docgen/doc/src/part.xml b/lib/erl_docgen/doc/src/part.xml new file mode 100644 index 0000000000..546c6c612e --- /dev/null +++ b/lib/erl_docgen/doc/src/part.xml @@ -0,0 +1,43 @@ + + + + +
+ + 20072009 + 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. + + + DocBuilder User's Guide + + + + +
+ +

Docbuilder provides functionality for generating HTML + documentation for Erlang modules and Erlang/OTP applications + from XML source code and/or EDoc comments in Erlang source code.

+ + + + + + + + + + + diff --git a/lib/erl_docgen/doc/src/refman_dtds.xml b/lib/erl_docgen/doc/src/refman_dtds.xml new file mode 100644 index 0000000000..a7beaed708 --- /dev/null +++ b/lib/erl_docgen/doc/src/refman_dtds.xml @@ -0,0 +1,667 @@ + + + + +
+ + 19972009 + 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. + + + + Reference Manual DTDs + + + + + refman_dtds.xml +
+ +

There are five DTDs for writing manual pages about applications, + shell commands, C libraries, Erlang modules and files, all with a + similar structure:

+ + + A header. + Name of the application/command/library/module/file. + Short summary (one line). + A longer description. + "Formal" definitions of functions or commands. + Optional sections of free text. + Optional section with the name(s) and email(s) of the author(s). + + +

The differences between the DTDs are the tags for the name, + the short summary and some tags inside the "formal" definitions.

+ +
+ + The application DTD + +

The application DTD is intended for a Reference Manual and + groups a set of manual pages into one unit. The structure is + similar to the part DTD: first an introduction and then the manual + pages, written in separate files with the + appref, + comref, + cref, + erlref, or + fileref DTD.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+<application>
+  <header>
+    <title>Application name</title>
+    <prepared/>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+
+  <description>
+    <p>Application description...</p>
+  </description>
+  
+  <include file="module1">
+  <include file="module2">
+</application>
+
+
+ +
+ + <application> + +

The top level tag of an application DTD.

+ +

Contains a + <header>, + an optional + <description>, + followed by one or more + <include>. +

+
+ +
+ + The appref DTD + +

This is the DTD for writing an application manual page.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE appref SYSTEM "appref.dtd">
+<appref>
+  <header>
+    <title>Application name</title>
+    <prepared/>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+
+  <app>Application name</app>
+
+  <appsummary>A short application summary.</appsummary>
+
+  <description>
+    <p>A longer description of the application.</p>
+  </description>
+  
+  <section>
+    <title>Configuration</title>
+
+      <p>...</p>
+  </section>
+
+  ...
+  
+  <authors>
+    <aname>Name of author</aname>
+    <email>Email of author</email>
+  </authors>
+</appref>
+
+ +
+ + <appref> + +

The top level tag of an appref DTD.

+ +

Contains + <header>, + <app>, + <appsummary>, + <description>, + zero or more + <section> and + <funcs>, + followed by zero or more + <authors>.

+
+ +
+ + <app> + +

The application name. Contains plain text.

+
+ +
+ + <appsummary> + +

Short summary. Contains plain text.

+
+
+ +
+ + The comref DTD + +

This is the DTD for writing a command manual page.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE comref SYSTEM "comref.dtd">
+<comref>
+  <header>
+    <title>Command name</title>
+    <prepared/>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+
+  <com>Command name</com>
+
+  <comsummary>A short command summary.</comsummary>
+
+  <description>
+    <p>A long description of the command.</p>
+  </description>
+  
+  <funcs>
+    <func>
+      <name>command</name>
+      <name>command -flag <arg></name>
+      <fsummary>A short command summary (max 40 characters).</fsummary>
+      <desc>
+        <p>An extended command description.
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Options</title>
+
+    <p>...</p>
+  </section>
+  
+  <authors>
+    <aname>Name of author</aname>
+    <email>Email of author</email>
+  </authors>
+</comref>
+
+ +
+ + <comref> + +

The top level tag for a comref DTD.

+ +

Contains + <header>, + <com>, + <comsummary>, + <description>, + zero or more + <section> and + <funcs>, + followed by zero or more + <authors>.

+
+ +
+ + <com> + +

The command name. Contains plain text.

+
+ +
+ + + <comsummary> + +

Short summary. Contains plain text.

+
+
+ +
+ + The cref DTD + +

This is the DTD for writing a C library manual page.

+ +

Example:

+ 

+
+
+  

+    C library name
+    
+    
+    
+    
+  

+
+  C library name
+
+  A short C library summary.
+
+  
+    
A longer description of the C library.

+  
+  
+  
+    
+      voidstart(bar)
+      voidstart(foo)
+      A short function summary (max 40 characters).
+      
+        char bar
+        int foo
+      
+      
+        
An extended function description.

+      
+    
+
+    ...
+  
+
+  

+    A title
+
+    
Some text...

+  

+  
+  
+
+    ]]>
+ +
+ + <cref> + +

The top level tag for a cref DTD.

+ +

Contains + <header>, + <lib>, + <libsummary>, + <description>, + zero or more + <section> and + <funcs>, followed by + zero or more + <authors>.

+
+ +
+ + <lib> + +

The C library name or acronym. Contains plain text.

+
+ +
+ + <libsummary> + +

Short summary. Contains plain text.

+
+
+ +
+ + The erlref DTD + +

This is the DTD for writing Erlang module manual pages.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+<erlref>
+  <header>
+    <title>Module name</title>
+    <prepared/>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+
+  <module>Module name</module>
+
+  <modulesummary>A short module summary.</modulesummary>
+
+  <description>
+    <p>A longer description of the module.</p>
+  </description>
+  
+  <funcs>
+    <func>
+      <name>start() -> Result</name>
+      <name>start(N) -> Result</name>
+      <fsummary>A short function summary (max 40 characters).</fsummary>
+      <type>
+        <v>Pid = pid()</v>
+        <v>N = int()</v>
+        <v>Result = {ok, Pid} | {error, Reason}</v>
+        <v>Reason = term()</v>
+        <d>A parameter description.</d>
+      </type>
+      <desc>
+        <p>An extended function description.</p>
+      </desc>
+    </func>
+
+    ...
+  </funcs>
+
+  <section>
+    <title>Some Title</title>
+    <p>Some text...</p>
+  </section>
+  
+  <authors>
+    <aname>Name of author</aname>
+    <email>Email of author</email>
+  </authors>
+</erlref>
+
+ +
+ + <erlref> + +

The top level tag for an erlref DTD.

+ +

Contains + <header>, + <module>, + <modulesummary>, + <description>, + zero or more + <section> and + <funcs>, + followed by zero or more + <authors>.

+
+ +
+ + <module> + +

The module name. Contains plain text.

+
+ +
+ + <modulesummary> + +

Short summary. Contains plain text.

+
+
+ +
+ + The fileref DTD + +

This is the DTD for writing file manual pages. In OTP, this DTD + is used for defining the format of for example .rel and + .app files.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+<fileref>
+  <header>
+    <title>File name</title>
+    <prepared/>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+
+  <file>fileref</file>
+
+  <filesummary>A short file summary.</filesummary>
+
+  <description>
+    <p>A longer description of the file.</p>
+  </description>
+  
+  <section>
+    <title>File format</title>
+
+    <p>...</p>
+  </section>
+  
+  <authors>
+    <aname>Name of author</aname>
+    <email>Email of author</email>
+  </authors>
+</fileref>
+
+ +

The file reference manual can also contain function definitions, + similar to the erlref DTD.

+ +
+ + <fileref> + +

The top level tag for a fileref DTD.

+ +

Contains + <header>, + <file>, + <filesummary>, + <description>, + zero or more + <section> and + <funcs>, + followed by zero or more + <authors>.

+
+ +
+ + <file> + +

The name of the file or file type. Contains plain text.

+
+ +
+ + <filesummary> + +

Short summary. Contains plain text.

+
+
+ +
+ + <description> + +

The introduction after the title and before sections and + "formal" definitions.

+ +

Contains any combination and any number of + block tags except + ]]> and ]]>.

+
+ +
+ + <section> + +

Subdivisions of the document. Contains an optional + <marker>, + a <title>, + + followed by any combination and any number of + block tags except + ]]> and ]]>.

+
+ +
+ + <funcs> + +

A group of "formal" function definitions.

+ +

Contains one or more + <func>.

+
+ +
+ + <func> + +

A "formal" function definition.

+ +

Contains one or more + <name>, followed by + <fsummary>, + <type> (optional) and + <desc> (optional).

+
+ +
+ + <name> + +

Function/command signature with name, arguments and return value. + Contains plain text, except for the cref DTD where it + contains a ]]> (return type, plain text) and + a ]]> (function name and arguments, + plain text).

+ +

In the case of an erlref DTD, DocBuilder will + automatically try to add a + marker, + ]]> or + ]]>, based on the contents of + this tag before the function definition.

+ +

Example: Consider the following name definition

+ 
foo(Arg1, Arg2) -> ok | {error, Reason}
+    ]]>
+ +

DocBuilder will create a marker + ]]> before the function + definition in the generated HTML. That is, referring to + the function using + foo/2]]> will + automatically work.

+
+ +
+ + <fsummary> + +

Function/command summary. Contains plain text, + <c> and + <em>.

+
+ +
+ + <type> + +

Type declarations for the function/command.

+ +

Contains one or more pairs of + <v> and + <d> (optional).

+
+ +
+ + <v> + +

Type declaration for an argument or return value. Contains plain + text.

+
+ +
+ + <d> + +

Description for an argument or return value. Contains plain text, + <c> and + <em>.

+
+ +
+ + <desc> + +

Function/command description. Contains + block tags except + <image> and <table>.

+
+ +
+ + <authors> + +

Authors of the manual page. The authors element is optional.

+ +

Contains one or more pairs of + <aname> and + <email>.

+
+ +
+ + <aname> + +

Author name. Contains plain text.

+
+ +
+ + <email> + +

Author email address. Contains plain text.

+
+ + diff --git a/lib/erl_docgen/doc/src/user_guide_dtds.xml b/lib/erl_docgen/doc/src/user_guide_dtds.xml new file mode 100644 index 0000000000..a2db44f830 --- /dev/null +++ b/lib/erl_docgen/doc/src/user_guide_dtds.xml @@ -0,0 +1,181 @@ + + + + +
+ + 19972009 + 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. + + + + User's Guide DTDs + + + + + user_guide_dtds.xml +
+ +
+ + The part DTD + +

The part DTD is intended for a "normal" document, like + the User's Guide or Release Notes. First are some paragraphs + introducing the main contents. After that follows chapters, + written in separate files with + the chapter DTD.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+<part>
+  <header>
+    <title>The chapter title</title>
+    <prepared>The author</prepared>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+
+  <description>
+    <p>Some text..</p>
+  </description>
+
+  <include file="file1"></include>
+  <include file="file2"></include>
+</part>
+
+
+ +
+ + <part> + +

The top level tag of a part DTD.

+ +

Contains a + <header>, + an optional + <description>, + followed by one or more + <include>.

+
+ +
+ + <description> + +

The introduction after the title and before the bulk of + included chapters/manual pages.

+ +

Contains any combination and any number + of block tags except + ]]> and ]]>.

+
+ +
+ + <include> + +

An empty tag. The attribute file specifies a file to + include. The .xml file extension should be omitted.

+ +

Example:

+ 
+<include file="notes"></include>
+
+
+ +
+ + The chapter DTD + +

The chapter DTD is intended for a chapter in a User's + Guide or similar with text divided into sections, which can be + nested.

+ +

Example:

+ 
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+<chapter>
+  <header>
+    <title>Title on first level</title>
+    <prepared/>
+    <docno/>
+    <date/>
+    <rev/>
+  </header>
+  
+  <p>Introduction...</p>
+
+  <section>
+    <title>Title on second level</title>
+
+    <p>First paragraph.</p>
+
+    <p>Second paragraph etc.</p>
+
+    <section>
+      <title>Title on third level</title>
+
+      <p>...</p>
+    </section>
+  </section>
+
+  ...
+</chapter>
+
+
+ +
+ + <chapter> + +

The top level tag of a chapter DTD.

+ +

Contains a + <header>, + an optional introduction consisting of any combination of + block tags, + followed by one or more + <section>.

+
+ +
+ + <section> + +

Subdivision of a chapter.

+ +

Contains an optional + <marker>, + a <title>, + followed by any combination and any number of + block tags and + ]]>.

+
+ +
+ + <title> + +

Section title, contains plain text.

+
+ + diff --git a/lib/erl_docgen/priv/docbuilder_dtd/Makefile b/lib/erl_docgen/priv/docbuilder_dtd/Makefile deleted file mode 100644 index e2214107cb..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/Makefile +++ /dev/null @@ -1,99 +0,0 @@ -# -# %CopyrightBegin% -# -# Copyright Ericsson AB 2009. 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) - -# ---------------------------------------------------- -# Release directory specification -# ---------------------------------------------------- -RELSYSDIR = $(RELEASE_PATH)/lib/erl_docgen-$(VSN) - - -# ---------------------------------------------------- -# Target Specs -# ---------------------------------------------------- - - -DTD_FILES = \ - application.dtd \ - chapter.dtd \ - common.header.dtd \ - comref.dtd \ - fileref.dtd \ - xhtml1-frameset.dtd \ - appref.dtd \ - cites.dtd \ - common.image.dtd \ - cref.dtd \ - part.dtd \ - xhtml1-strict.dtd \ - book.dtd \ - common.dtd \ - common.refs.dtd \ - erlref.dtd \ - report.dtd \ - xhtml1-transitional.dtd \ - bookinsidecover.dtd \ - common.entities.dtd \ - common.table.dtd \ - fascicules.dtd \ - terms.dtd - - - -# ---------------------------------------------------- -# FLAGS -# ---------------------------------------------------- - - -# ---------------------------------------------------- -# Targets -# ---------------------------------------------------- -debug opt: - -docs: - -clean: - $(RM) $(TARGET_FILES) - - -# ---------------------------------------------------- -# Release Target -# ---------------------------------------------------- -include $(ERL_TOP)/make/otp_release_targets.mk - - -release_spec: opt - $(INSTALL_DIR) $(RELSYSDIR)/priv/docbuilder_dtd - $(INSTALL_DATA) $(DTD_FILES) $(RELSYSDIR)/priv/docbuilder_dtd - - -release_docs_spec: - - -release_tests_spec: - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/application.dtd b/lib/erl_docgen/priv/docbuilder_dtd/application.dtd deleted file mode 100644 index 8a1e8832ec..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/application.dtd +++ /dev/null @@ -1,29 +0,0 @@ - - - - -%common; - -%common.header; - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/appref.dtd b/lib/erl_docgen/priv/docbuilder_dtd/appref.dtd deleted file mode 100644 index 70a5ff37af..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/appref.dtd +++ /dev/null @@ -1,33 +0,0 @@ - - - - -%common.refs; - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/book.dtd b/lib/erl_docgen/priv/docbuilder_dtd/book.dtd deleted file mode 100644 index bb89a6d255..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/book.dtd +++ /dev/null @@ -1,73 +0,0 @@ - - - - -%common; - -%common.header; - -%common.table; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd b/lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd deleted file mode 100644 index d6efbef6a4..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd +++ /dev/null @@ -1,36 +0,0 @@ - - -%ISOlat1; - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd b/lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd deleted file mode 100644 index eb2c96b04f..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd +++ /dev/null @@ -1,36 +0,0 @@ - - - - -%common; - -%common.header; - -%common.table; - -%common.image; - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/cites.dtd b/lib/erl_docgen/priv/docbuilder_dtd/cites.dtd deleted file mode 100644 index 334574bff9..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/cites.dtd +++ /dev/null @@ -1,35 +0,0 @@ - - -%ISOlat1; - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.dtd b/lib/erl_docgen/priv/docbuilder_dtd/common.dtd deleted file mode 100644 index fdc02c55a1..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.dtd +++ /dev/null @@ -1,87 +0,0 @@ - - - - -%common.entities; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd b/lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd deleted file mode 100644 index f893ecd070..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd +++ /dev/null @@ -1,24 +0,0 @@ - - -%ISOlat1; - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd b/lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd deleted file mode 100644 index d422a89693..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd +++ /dev/null @@ -1,42 +0,0 @@ - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd b/lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd deleted file mode 100644 index fc95a669dd..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd +++ /dev/null @@ -1,21 +0,0 @@ - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd b/lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd deleted file mode 100644 index c1237766e1..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd +++ /dev/null @@ -1,43 +0,0 @@ - - - - -%common; - -%common.header; - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd b/lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd deleted file mode 100644 index 7741da1018..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/comref.dtd b/lib/erl_docgen/priv/docbuilder_dtd/comref.dtd deleted file mode 100644 index fcdea625d5..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/comref.dtd +++ /dev/null @@ -1,31 +0,0 @@ - - - - -%common.refs; - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/cref.dtd b/lib/erl_docgen/priv/docbuilder_dtd/cref.dtd deleted file mode 100644 index e43bb2bf51..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/cref.dtd +++ /dev/null @@ -1,34 +0,0 @@ - - - - -%common.refs; - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd b/lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd deleted file mode 100644 index 9905086ff4..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd +++ /dev/null @@ -1,31 +0,0 @@ - - - - -%common.refs; - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd b/lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd deleted file mode 100644 index b14276a2c0..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd +++ /dev/null @@ -1,35 +0,0 @@ - - - - -%ISOlat1; - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd b/lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd deleted file mode 100644 index 5a1cc54afe..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd +++ /dev/null @@ -1,31 +0,0 @@ - - - - -%common.refs; - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/part.dtd b/lib/erl_docgen/priv/docbuilder_dtd/part.dtd deleted file mode 100644 index 3f97199042..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/part.dtd +++ /dev/null @@ -1,29 +0,0 @@ - - - - -%common; - -%common.header; - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/report.dtd b/lib/erl_docgen/priv/docbuilder_dtd/report.dtd deleted file mode 100644 index 3d07e6e5a7..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/report.dtd +++ /dev/null @@ -1,138 +0,0 @@ - - - - -%ISOlat1; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/terms.dtd b/lib/erl_docgen/priv/docbuilder_dtd/terms.dtd deleted file mode 100644 index 6105ec593e..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/terms.dtd +++ /dev/null @@ -1,36 +0,0 @@ - - -%ISOlat1; - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd b/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd deleted file mode 100644 index d128f2eb7c..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd +++ /dev/null @@ -1,1235 +0,0 @@ - - - - - -%HTMLlat1; - - -%HTMLsymbol; - - -%HTMLspecial; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd b/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd deleted file mode 100644 index 2927b9ece7..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd +++ /dev/null @@ -1,978 +0,0 @@ - - - - - -%HTMLlat1; - - -%HTMLsymbol; - - -%HTMLspecial; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd b/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd deleted file mode 100644 index 628f27ac50..0000000000 --- a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd +++ /dev/null @@ -1,1201 +0,0 @@ - - - - - -%HTMLlat1; - - -%HTMLsymbol; - - -%HTMLspecial; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/lib/erl_docgen/priv/dtd/Makefile b/lib/erl_docgen/priv/dtd/Makefile new file mode 100644 index 0000000000..e2214107cb --- /dev/null +++ b/lib/erl_docgen/priv/dtd/Makefile @@ -0,0 +1,99 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2009. 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) + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/erl_docgen-$(VSN) + + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- + + +DTD_FILES = \ + application.dtd \ + chapter.dtd \ + common.header.dtd \ + comref.dtd \ + fileref.dtd \ + xhtml1-frameset.dtd \ + appref.dtd \ + cites.dtd \ + common.image.dtd \ + cref.dtd \ + part.dtd \ + xhtml1-strict.dtd \ + book.dtd \ + common.dtd \ + common.refs.dtd \ + erlref.dtd \ + report.dtd \ + xhtml1-transitional.dtd \ + bookinsidecover.dtd \ + common.entities.dtd \ + common.table.dtd \ + fascicules.dtd \ + terms.dtd + + + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +debug opt: + +docs: + +clean: + $(RM) $(TARGET_FILES) + + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + + +release_spec: opt + $(INSTALL_DIR) $(RELSYSDIR)/priv/docbuilder_dtd + $(INSTALL_DATA) $(DTD_FILES) $(RELSYSDIR)/priv/docbuilder_dtd + + +release_docs_spec: + + +release_tests_spec: + + diff --git a/lib/erl_docgen/priv/dtd/application.dtd b/lib/erl_docgen/priv/dtd/application.dtd new file mode 100644 index 0000000000..8a1e8832ec --- /dev/null +++ b/lib/erl_docgen/priv/dtd/application.dtd @@ -0,0 +1,29 @@ + + + + +%common; + +%common.header; + + + + + diff --git a/lib/erl_docgen/priv/dtd/appref.dtd b/lib/erl_docgen/priv/dtd/appref.dtd new file mode 100644 index 0000000000..70a5ff37af --- /dev/null +++ b/lib/erl_docgen/priv/dtd/appref.dtd @@ -0,0 +1,33 @@ + + + + +%common.refs; + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/book.dtd b/lib/erl_docgen/priv/dtd/book.dtd new file mode 100644 index 0000000000..bb89a6d255 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/book.dtd @@ -0,0 +1,73 @@ + + + + +%common; + +%common.header; + +%common.table; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/bookinsidecover.dtd b/lib/erl_docgen/priv/dtd/bookinsidecover.dtd new file mode 100644 index 0000000000..d6efbef6a4 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/bookinsidecover.dtd @@ -0,0 +1,36 @@ + + +%ISOlat1; + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/chapter.dtd b/lib/erl_docgen/priv/dtd/chapter.dtd new file mode 100644 index 0000000000..eb2c96b04f --- /dev/null +++ b/lib/erl_docgen/priv/dtd/chapter.dtd @@ -0,0 +1,36 @@ + + + + +%common; + +%common.header; + +%common.table; + +%common.image; + + + + + diff --git a/lib/erl_docgen/priv/dtd/cites.dtd b/lib/erl_docgen/priv/dtd/cites.dtd new file mode 100644 index 0000000000..334574bff9 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/cites.dtd @@ -0,0 +1,35 @@ + + +%ISOlat1; + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/common.dtd b/lib/erl_docgen/priv/dtd/common.dtd new file mode 100644 index 0000000000..fdc02c55a1 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/common.dtd @@ -0,0 +1,87 @@ + + + + +%common.entities; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/common.entities.dtd b/lib/erl_docgen/priv/dtd/common.entities.dtd new file mode 100644 index 0000000000..f893ecd070 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/common.entities.dtd @@ -0,0 +1,24 @@ + + +%ISOlat1; + + + + diff --git a/lib/erl_docgen/priv/dtd/common.header.dtd b/lib/erl_docgen/priv/dtd/common.header.dtd new file mode 100644 index 0000000000..d422a89693 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/common.header.dtd @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/common.image.dtd b/lib/erl_docgen/priv/dtd/common.image.dtd new file mode 100644 index 0000000000..fc95a669dd --- /dev/null +++ b/lib/erl_docgen/priv/dtd/common.image.dtd @@ -0,0 +1,21 @@ + + + + diff --git a/lib/erl_docgen/priv/dtd/common.refs.dtd b/lib/erl_docgen/priv/dtd/common.refs.dtd new file mode 100644 index 0000000000..c1237766e1 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/common.refs.dtd @@ -0,0 +1,43 @@ + + + + +%common; + +%common.header; + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/common.table.dtd b/lib/erl_docgen/priv/dtd/common.table.dtd new file mode 100644 index 0000000000..7741da1018 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/common.table.dtd @@ -0,0 +1,25 @@ + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/comref.dtd b/lib/erl_docgen/priv/dtd/comref.dtd new file mode 100644 index 0000000000..fcdea625d5 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/comref.dtd @@ -0,0 +1,31 @@ + + + + +%common.refs; + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/cref.dtd b/lib/erl_docgen/priv/dtd/cref.dtd new file mode 100644 index 0000000000..e43bb2bf51 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/cref.dtd @@ -0,0 +1,34 @@ + + + + +%common.refs; + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/erlref.dtd b/lib/erl_docgen/priv/dtd/erlref.dtd new file mode 100644 index 0000000000..9905086ff4 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/erlref.dtd @@ -0,0 +1,31 @@ + + + + +%common.refs; + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/fascicules.dtd b/lib/erl_docgen/priv/dtd/fascicules.dtd new file mode 100644 index 0000000000..b14276a2c0 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/fascicules.dtd @@ -0,0 +1,35 @@ + + + + +%ISOlat1; + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/fileref.dtd b/lib/erl_docgen/priv/dtd/fileref.dtd new file mode 100644 index 0000000000..5a1cc54afe --- /dev/null +++ b/lib/erl_docgen/priv/dtd/fileref.dtd @@ -0,0 +1,31 @@ + + + + +%common.refs; + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/part.dtd b/lib/erl_docgen/priv/dtd/part.dtd new file mode 100644 index 0000000000..3f97199042 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/part.dtd @@ -0,0 +1,29 @@ + + + + +%common; + +%common.header; + + + + + diff --git a/lib/erl_docgen/priv/dtd/report.dtd b/lib/erl_docgen/priv/dtd/report.dtd new file mode 100644 index 0000000000..3d07e6e5a7 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/report.dtd @@ -0,0 +1,138 @@ + + + + +%ISOlat1; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/terms.dtd b/lib/erl_docgen/priv/dtd/terms.dtd new file mode 100644 index 0000000000..6105ec593e --- /dev/null +++ b/lib/erl_docgen/priv/dtd/terms.dtd @@ -0,0 +1,36 @@ + + +%ISOlat1; + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd b/lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd new file mode 100644 index 0000000000..d128f2eb7c --- /dev/null +++ b/lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd @@ -0,0 +1,1235 @@ + + + + + +%HTMLlat1; + + +%HTMLsymbol; + + +%HTMLspecial; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/xhtml1-strict.dtd b/lib/erl_docgen/priv/dtd/xhtml1-strict.dtd new file mode 100644 index 0000000000..2927b9ece7 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/xhtml1-strict.dtd @@ -0,0 +1,978 @@ + + + + + +%HTMLlat1; + + +%HTMLsymbol; + + +%HTMLspecial; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd b/lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd new file mode 100644 index 0000000000..628f27ac50 --- /dev/null +++ b/lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd @@ -0,0 +1,1201 @@ + + + + + +%HTMLlat1; + + +%HTMLsymbol; + + +%HTMLspecial; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl new file mode 100644 index 0000000000..90491bc007 --- /dev/null +++ b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl @@ -0,0 +1,1154 @@ +%% ``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 via the world wide web at http://www.erlang.org/. +%% +%% Software distributed under the License is distributed on an "AS IS" +%% basis, WITHOUT WARRANTY OF ANY KIND, either expressed or implied. See +%% the Licence for the specific language governing rights and limitations +%% under the License. +%% +%% The Initial Developer of the Original Code is Ericsson AB. +%% Portions created by Ericsson are Copyright 1999-2006, Ericsson AB. +%% All Rights Reserved.´´ +%% +%% $Id$ +%% +-module(docb_edoc_xml_cb). + +%% This is the EDoc callback module for creating DocBuilder erlref +%% documents (man pages) in XML format, and also a DocBuilder chapter +%% document based on "overview.edoc". +%% +%% Usage examples: +%% docb_gen File +%% docb_gen -chapter overview.edoc +%% or (from an Erlang shell) +%% edoc:file(File, [{layout,docb_edoc_xml_cb},{file_suffix,".xml"}, +%% {preprocess,true}]). +%% +%% The origin of this file is the edoc module otpsgml_layout.erl +%% written by Richard Carlsson. + +-export([module/2, overview/2]). + +-include("xmerl.hrl"). + +-define(NL, "\n"). + +%%-User interface------------------------------------------------------- + +%% ERLREF +module(Element, Opts) -> + SortP = proplists:get_value(sort_functions, Opts, true), + XML = layout_module(Element, SortP), + xmerl:export_simple([XML], docb_xmerl_xml_cb, []). + +%% CHAPTER +overview(Element, _Opts) -> + XML = layout_chapter(Element), + xmerl:export_simple([XML], docb_xmerl_xml_cb, []). + +%%--Internal functions-------------------------------------------------- + +layout_module(#xmlElement{name = module, content = Es}=E, SortP) -> + Name = get_attrval(name, E), + Desc = get_content(description, Es), + ShortDesc = text_only(get_content(briefDescription, Desc)), + FullDesc = otp_xmlify(get_content(fullDescription, Desc)), + Types0 = get_content(typedecls, Es), + Types1 = lists:sort([{type_name(Et), Et} || Et <- Types0]), + Functions = + case SortP of + true -> + lists:sort([{function_name(Ef), Ef} || + Ef <- get_content(functions, Es)]); + false -> + [{function_name(Ef), Ef} || + Ef <- get_content(functions, Es)] + end, + Header = {header, [ + ?NL,{title, [Name]}, + ?NL,{prepared, [""]}, + ?NL,{responsible, [""]}, + ?NL,{docno, ["1"]}, + ?NL,{approved, [""]}, + ?NL,{checked, [""]}, + ?NL,{date, [""]}, + ?NL,{rev, ["A"]}, + ?NL,{file, [Name++".xml"]} + ]}, + Module = {module, [Name]}, + ModuleSummary = {modulesummary, ShortDesc}, + Description = {description, [?NL|FullDesc]}, + Types = case Types1 of + [] -> []; + _ -> + [?NL, {section,[{title,["DATA TYPES"]}, + {marker,[{id,"types"}],[]}, + ?NL|types(Types1)]}] + end, + Funcs = functions(Functions), + See = seealso_module(Es), + Authors = {authors, authors(Es)}, + {erlref, + [?NL,Header, + ?NL,Module, + ?NL,ModuleSummary, + ?NL,Description] + ++ Types ++ + [?NL,Funcs, + ?NL,See, + ?NL,Authors] + }. + +layout_chapter(#xmlElement{name=overview, content=Es}) -> + Title = get_text(title, Es), + Header = {header, [ + ?NL,{title,[Title]}, + ?NL,{prepared,[""]}, + ?NL,{docno,[""]}, + ?NL,{date,[""]}, + ?NL,{rev,[""]}, + ?NL,{file, ["chapter.xml"]} + ]}, + DescEs = get_content(description, Es), + FullDescEs = get_content(fullDescription, DescEs), + Sections = chapter_ify(FullDescEs, first), + {chapter, [?NL, Header, ?NL | Sections]}. + +chapter_ify([], _) -> + []; +chapter_ify(Es, first) -> + %% Everything up to the first section should be made into + %% plain paragraphs -- or if no first section is found, everything + %% should be made into one + case find_next(h3, Es) of + {Es, []} -> + SubSections = subchapter_ify(Es, first), + [{section, [?NL,{title,["Overview"]}, + ?NL | SubSections]}]; + {FirstEs, RestEs} -> + otp_xmlify(FirstEs) ++ chapter_ify(RestEs, next) + end; +chapter_ify([#xmlElement{name=h3} = E | Es], next) -> + {SectionEs, RestEs} = find_next(h3, Es), + SubSections = subchapter_ify(SectionEs, first), + {Marker, Title} = chapter_title(E), + [{section, [?NL,{marker,[{id,Marker}],[]}, + ?NL,{title,[Title]}, + ?NL | SubSections]} | chapter_ify(RestEs, next)]. + +subchapter_ify([], _) -> + []; +subchapter_ify(Es, first) -> + %% Everything up to the (possible) first subsection should be + %% made into plain paragraphs + {FirstEs, RestEs} = find_next(h4, Es), + otp_xmlify(FirstEs) ++ subchapter_ify(RestEs, next); +subchapter_ify([#xmlElement{name=h4} = E | Es], next) -> + {SectionEs, RestEs} = find_next(h4, Es), + Elements = otp_xmlify(SectionEs), + {Marker, Title} = chapter_title(E), + [{section, [?NL,{marker,[{id,Marker}],[]}, + ?NL,{title,[Title]}, + ?NL | Elements]} | subchapter_ify(RestEs, next)]. + +chapter_title(#xmlElement{content=Es}) -> % name = h3 | h4 + case Es of + [#xmlElement{name=a} = E] -> + {get_attrval(name, E), get_text(E)} + end. + +%%--XHTML->XML transformation------------------------------------------- + +%% otp_xmlify(Es1) -> Es2 +%% Es1 = Es2 = [#xmlElement{} | #xmlText{}] +%% Fix things that are allowed in XHTML but not in chapter/erlref DTDs. +%% 1) lists (