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 +++++++ 13 files changed, 2699 insertions(+) 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 (limited to 'lib/erl_docgen/doc') 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.

+
+ + -- cgit v1.2.3 From 4424b10d7054025eef3e721f64fb53ad7b357282 Mon Sep 17 00:00:00 2001 From: Lars Thorsen Date: Thu, 17 Nov 2011 12:27:59 +0100 Subject: [erl_docgen] Tidy up the documentation moved from docbuilder to erl_docgen --- lib/erl_docgen/doc/html/.gitignore | 0 lib/erl_docgen/doc/man3/.gitignore | 0 lib/erl_docgen/doc/pdf/.gitignore | 0 lib/erl_docgen/doc/src/Makefile | 135 ++++++++++++++++++++++++++ lib/erl_docgen/doc/src/block_tags.xml | 16 +-- lib/erl_docgen/doc/src/book.xml | 16 ++- lib/erl_docgen/doc/src/character_entities.xml | 2 +- lib/erl_docgen/doc/src/convert.howto | 13 --- lib/erl_docgen/doc/src/docb_xml_check.xml | 59 ----------- lib/erl_docgen/doc/src/docgen_xml_check.xml | 59 +++++++++++ lib/erl_docgen/doc/src/erl_docgen.txt | 6 -- lib/erl_docgen/doc/src/example.txt | 17 ++++ lib/erl_docgen/doc/src/gazonk | 17 ---- lib/erl_docgen/doc/src/header_tags.xml | 16 ++- lib/erl_docgen/doc/src/inline_tags.xml | 49 +--------- lib/erl_docgen/doc/src/notes.xml | 6 +- lib/erl_docgen/doc/src/overview.xml | 50 ++-------- lib/erl_docgen/doc/src/part.xml | 9 +- lib/erl_docgen/doc/src/ref_man.xml | 36 +++++++ lib/erl_docgen/doc/src/refman_dtds.xml | 6 +- 20 files changed, 292 insertions(+), 220 deletions(-) create mode 100644 lib/erl_docgen/doc/html/.gitignore create mode 100644 lib/erl_docgen/doc/man3/.gitignore create mode 100644 lib/erl_docgen/doc/pdf/.gitignore create mode 100644 lib/erl_docgen/doc/src/Makefile delete mode 100644 lib/erl_docgen/doc/src/convert.howto delete mode 100644 lib/erl_docgen/doc/src/docb_xml_check.xml create mode 100644 lib/erl_docgen/doc/src/docgen_xml_check.xml delete mode 100644 lib/erl_docgen/doc/src/erl_docgen.txt create mode 100644 lib/erl_docgen/doc/src/example.txt delete mode 100644 lib/erl_docgen/doc/src/gazonk create mode 100644 lib/erl_docgen/doc/src/ref_man.xml (limited to 'lib/erl_docgen/doc') diff --git a/lib/erl_docgen/doc/html/.gitignore b/lib/erl_docgen/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_docgen/doc/man3/.gitignore b/lib/erl_docgen/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_docgen/doc/pdf/.gitignore b/lib/erl_docgen/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 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 @@
- 19972009 + 19972011 Ericsson AB. All Rights Reserved. @@ -33,7 +33,7 @@ as a paragraph or a list.

The following subset of block tags are common for all DTDs in - the DocBuilder DTD suite: + the OTP DTD suite: <p>, <pre>, @@ -81,7 +81,7 @@ sum([]) ->

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

@@ -99,18 +99,18 @@ sum([]) -> gives the file name and tag defines a string which delimits the code snippet. Example:

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

results in:

- + -

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

provided there is a file named examples.txt looking like this:

... %% Erlang example --module(gazonk). +-module(example). start() -> {error,"Pid required!"}. @@ -125,7 +125,7 @@ start(Pid) -> included.

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

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 @@ - +
- 20042009 + 20042011 Ericsson AB. All Rights Reserved. @@ -21,27 +21,23 @@ - erl_docgen + Erl_Docgen Lars Thorsen - 2009-11-10 - 0.1 + 2011-11-10 + 0.3 book.xml
- - erl_docgen + - - - 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 @@
Added Latin 1 -

The DocBuilder DTD suite uses the same character entities as +

The OTP 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 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 - -- change to - -- 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/docb_xml_check.xml deleted file mode 100644 index eff4fc4342..0000000000 --- a/lib/erl_docgen/doc/src/docb_xml_check.xml +++ /dev/null @@ -1,59 +0,0 @@ - - - - -

- - 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/docgen_xml_check.xml b/lib/erl_docgen/doc/src/docgen_xml_check.xml new file mode 100644 index 0000000000..58cf069d81 --- /dev/null +++ b/lib/erl_docgen/doc/src/docgen_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. + + + docgen_xml_check + + + + +
+ docgen_xml_check + Validate XML documentation source code + +

docgen_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/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/example.txt b/lib/erl_docgen/doc/src/example.txt new file mode 100644 index 0000000000..ad86165391 --- /dev/null +++ b/lib/erl_docgen/doc/src/example.txt @@ -0,0 +1,17 @@ +This example code is used in block_tags.xml. + +%% Erlang example +-module(example). + +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/gazonk b/lib/erl_docgen/doc/src/gazonk deleted file mode 100644 index 1cf0b8f7bc..0000000000 --- a/lib/erl_docgen/doc/src/gazonk +++ /dev/null @@ -1,17 +0,0 @@ -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 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 @@
<shorttitle> -

This optional tag is ignored by DocBuilder. It will likely be +

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

@@ -112,8 +112,7 @@ <prepared> -

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

+

This tag is intended for administrative use and is ignored.

@@ -121,7 +120,7 @@ <responsible>

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

+ ignored.

@@ -141,7 +140,7 @@ <approved>

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

+ ignored.

@@ -149,15 +148,14 @@ <checked>

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

+ ignored.

<date> -

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

+

This tag is intended for administrative use and is ignored.

@@ -177,7 +175,7 @@ <file>

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

+ ignored.

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.

-
+
@@ -150,16 +150,10 @@

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 + because the default behavior 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.

@@ -192,28 +186,6 @@ 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. @@ -237,21 +209,6 @@ <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/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 @@ - + @@ -21,14 +21,14 @@ - erl_docgen Release Notes + Erl_Docgen Release Notes otp_appnotes nil nil nil notes.xml
-

This document describes the changes made to the erl_docgen application.

+

This document describes the changes made to the erl_docgen application.

Erl_Docgen 0.2.6 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 @@ -28,28 +28,6 @@ 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 @@ -94,10 +72,6 @@ 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.

@@ -120,7 +94,7 @@
Basic Tags -

All DTDs in the DocBuilder DTD suite share a basic set of tags. +

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 @@

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:

+ will look like, it is recommended to look at the documentation of + an OTP application.

- This User's Guide is written using the part and + This User's Guides are written using the part and chapter DTDs. - The Reference Manual is written using + The Reference Manuals are written using the application, appref and erlref DTDs. @@ -162,23 +136,19 @@

Create the relevant XML files.

-

If there are EDoc comments in a module, the function - docb_gen:module/1,2 +

If there are EDoc comments in a module, the escript + + xml_from_edoc can be used to generate an XML file according to the erlref DTD for this module.

 - + - -

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 index 546c6c612e..4594778a2f 100644 --- a/lib/erl_docgen/doc/src/part.xml +++ b/lib/erl_docgen/doc/src/part.xml @@ -1,10 +1,10 @@ - +
- 20072009 + 20112011 Ericsson AB. All Rights Reserved. @@ -20,21 +20,20 @@ under the License. - DocBuilder User's Guide + Erl_Docgen User's Guide
-

Docbuilder provides functionality for generating HTML +

Erl_Docgen 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.

 - 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 @@ + + + + +
+ + 20112011 + 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. + + + + Erl_Docgen Reference Manual + OTP Team + + 2011-11-10 + 0.3 + ref_man.xml +
+ +

The erl_docgen supports the OTP documentation build.

+ + + + 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 ]]> (function name and arguments, plain text).

-

In the case of an erlref DTD, DocBuilder will - automatically try to add a +

In the case of an erlref DTD, it will + automatically be added a marker, ]]> or ]]>, based on the contents of @@ -585,7 +585,7 @@ foo(Arg1, Arg2) -> ok | {error, Reason} ]]> -

DocBuilder will create a marker +

Then a marker like this will be added ]]> before the function definition in the generated HTML. That is, referring to the function using -- cgit v1.2.3 From 013e3840532b16308f4bfcf22bde0e6de8d064b2 Mon Sep 17 00:00:00 2001 From: Lars Thorsen Date: Fri, 18 Nov 2011 12:39:57 +0100 Subject: [erl_docgen] Add an application ref page --- lib/erl_docgen/doc/man3/.gitignore | 0 lib/erl_docgen/doc/man6/.gitignore | 0 lib/erl_docgen/doc/src/Makefile | 18 ++++----- lib/erl_docgen/doc/src/book.xml | 3 ++ lib/erl_docgen/doc/src/erl_docgen_app.xml | 64 +++++++++++++++++++++++++++++++ lib/erl_docgen/doc/src/ref_man.xml | 2 +- 6 files changed, 77 insertions(+), 10 deletions(-) delete mode 100644 lib/erl_docgen/doc/man3/.gitignore create mode 100644 lib/erl_docgen/doc/man6/.gitignore create mode 100644 lib/erl_docgen/doc/src/erl_docgen_app.xml (limited to 'lib/erl_docgen/doc') diff --git a/lib/erl_docgen/doc/man3/.gitignore b/lib/erl_docgen/doc/man3/.gitignore deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/lib/erl_docgen/doc/man6/.gitignore b/lib/erl_docgen/doc/man6/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/erl_docgen/doc/src/Makefile b/lib/erl_docgen/doc/src/Makefile index 1845f57fad..a546d8da33 100644 --- a/lib/erl_docgen/doc/src/Makefile +++ b/lib/erl_docgen/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2010. All Rights Reserved. +# Copyright Ericsson AB 2011-2011. 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 @@ -36,8 +36,8 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml -XML_REF3_FILES = \ - docgen_xml_check.xml +XML_REF6_FILES = \ + erl_docgen_app.xml XML_PART_FILES = \ part.xml @@ -54,7 +54,7 @@ XML_CHAPTER_FILES = \ BOOK_FILES = book.xml -XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \ +XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF6_FILES) \ $(XML_PART_FILES) $(XML_CHAPTER_FILES) TECHNICAL_DESCR_FILES = @@ -73,7 +73,7 @@ HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ INFO_FILE = ../../info -MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) +MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) HTML_REF_MAN_FILE = $(HTMLDIR)/index.html @@ -104,12 +104,12 @@ html: gifs examples $(HTML_REF_MAN_FILE) clean clean_docs: rm -rf $(HTMLDIR)/* - rm -f $(MAN3DIR)/* + rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) rm -f errs core *~ rm -f $(JD_HTML) $(JD_PACK) -man: $(MAN3_FILES) +man: $(MAN6_FILES) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) @@ -129,7 +129,7 @@ release_docs_spec: docs $(INSTALL_DATA) $(HTMLDIR)/* \ $(RELSYSDIR)/doc/html $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) - $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 - $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 + $(INSTALL_DATA) $(MAN6DIR)/* $(RELEASE_PATH)/man/man6 release_spec: diff --git a/lib/erl_docgen/doc/src/book.xml b/lib/erl_docgen/doc/src/book.xml index 1eef9a621b..73bfb7916d 100644 --- a/lib/erl_docgen/doc/src/book.xml +++ b/lib/erl_docgen/doc/src/book.xml @@ -35,6 +35,9 @@ + + + diff --git a/lib/erl_docgen/doc/src/erl_docgen_app.xml b/lib/erl_docgen/doc/src/erl_docgen_app.xml new file mode 100644 index 0000000000..25c473bb7e --- /dev/null +++ b/lib/erl_docgen/doc/src/erl_docgen_app.xml @@ -0,0 +1,64 @@ + + + + +

+ + 20112011 + 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. + + + + erl_docgen + erl_docgen_app.xml +
+ erl_docgen + + The erl_docgen application is used to produce the OTP documentation. + + + +

+ The application consists of the following parts + + XSL + +

+ A number of XSL files that is used to transform the xml files to html, pdf or man pages. +

+ + DTDs + +

+ The DTDs used for the OTP documentation. +

+ + escripts + +

+ Some scripts that is used to produce xml files according to OTP DTDs from some different input. +

+ + misc + +

+ Erlang logo, javascripts and css stylesheets used in the documentation. +

+ + +

+ + + diff --git a/lib/erl_docgen/doc/src/ref_man.xml b/lib/erl_docgen/doc/src/ref_man.xml index a92ab6c805..a2bc1a10a0 100644 --- a/lib/erl_docgen/doc/src/ref_man.xml +++ b/lib/erl_docgen/doc/src/ref_man.xml @@ -31,6 +31,6 @@

The erl_docgen supports the OTP documentation build.

 - + -- cgit v1.2.3