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