From 5a649701ee9413a43fe8542e8a8146618464d485 Mon Sep 17 00:00:00 2001 From: Lars Thorsen Date: Wed, 7 Dec 2011 13:01:40 +0100 Subject: [erl_docgen] Updated users guide --- lib/erl_docgen/doc/src/Makefile | 1 + lib/erl_docgen/doc/src/doc-build.xml | 188 +++++++++++++++++++++++++++++++++++ lib/erl_docgen/doc/src/overview.xml | 72 ++------------ lib/erl_docgen/doc/src/part.xml | 3 +- lib/erl_docgen/info | 1 - 5 files changed, 202 insertions(+), 63 deletions(-) create mode 100644 lib/erl_docgen/doc/src/doc-build.xml diff --git a/lib/erl_docgen/doc/src/Makefile b/lib/erl_docgen/doc/src/Makefile index a546d8da33..ff50c12895 100644 --- a/lib/erl_docgen/doc/src/Makefile +++ b/lib/erl_docgen/doc/src/Makefile @@ -44,6 +44,7 @@ XML_PART_FILES = \ XML_CHAPTER_FILES = \ overview.xml \ + doc-build.xml \ user_guide_dtds.xml \ refman_dtds.xml \ notes.xml \ diff --git a/lib/erl_docgen/doc/src/doc-build.xml b/lib/erl_docgen/doc/src/doc-build.xml new file mode 100644 index 0000000000..08410a1539 --- /dev/null +++ b/lib/erl_docgen/doc/src/doc-build.xml @@ -0,0 +1,188 @@ + + + + +
+ + 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. + + + How to Build OTP like documentation + + + + + doc-build.xml +
+ +
+ Utilities to prepare XML files +
+ Create XML files from code +

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

+

+ Example: +

+ + + 1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl + +
+
+ Include code in XML +

If there are OTP DTD codeinclude tags in the source XML file, the escript + codeline_preprocessing.escript can be used to include the code and produce + an XML file according to the OTP DTDs. +

+

+ Example: +

+ + + 1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/codeline_preprocessing.escript ex1.xmlsrc ex1.xml + +
+
+ +
+ Use xsltproc to generate different output formats + +
+ Parameters used in all the the XSL transformations +

+ These parameters to xsltproc are used for all the supported output formats. +

+ + docgen + + Path to erl_docgen's top directory. + + gendate + + The date string that will be used in the documentation. + + appname + + The name of the application.> + + appver + + The version of the application. + + +
+ +
+ Generate HTML output +

+ When generating HTML one also needs these three pramaters to xsltproc. +

+ + outdir + + Output directory for the produced html files. + + topdocdir + + If one builds a standalone documentation for an application this should be set to ".". + + pdfdir + + Relative path from the html directory to where the pdf file are placed. + + +

+ Example: +

+ + + 1> xsltproc --noout --stringparam outdir /tmp/myhtmldoc \ + --stringparam docgen $(ERL_TOP)/lib/erl_docgen \ + --stringparam topdocdir . \ + --stringparam pdfdir "$(PDFDIR)" \ + --xinclude \ + --stringparam gendate "December 5 2011" \ + --stringparam appname MyApp \ + --stringparam appver 0.1 \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \ + $ERL_TOP/lib/erl_docgen/priv/xsl/db_html.xsl mybook.xml + +
+ +
+ Generate PDF +

+ The generation of the PDF file is done in two steps. First is xsltproc used to generate a .fo file + which is used as input to the fop command to produce th PDF file. +

+

+ Example: +

+ + + 1> xsltproc --output MyApp.fo \ + --stringparam docgen $ERL_TOP/lib/erl_docgen \ + --stringparam gendate "December 5 2011" \ + --stringparam appname MyApp \ + --stringparam appver 0.1 \ + --xinclude \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \ + $ERL_TOP/lib/erl_docgen/priv/xsl/db_pdf.xsl mybook.xml + + + 2> fop -fo MyApp.fo -pdf MyApp.pdf + +
+ +
+ Generate man pages +

+ Unix man pages can be generated with xsltproc from XML files written according to + the different OTP ref type DTDs. +

+

+ Example: +

+ + + 1> xsltproc --output my_module.3\ + --stringparam docgen $ERL_TOP/lib/erl_docgen \ + --stringparam gendate "December 5 2011" \ + --stringparam appname MyApp \ + --stringparam appver 0.1 \ + --xinclude -path $ERL_TOP/lib/erl_docgen/priv/dtd \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd_man_entities \ + $ERL_TOP/lib/erl_docgen/priv/xsl/db_man.xsl my_refpage.xml + +
+ +
+ Upcomming changes +

+ The output from the erl_docgen documentation build process is now just the OTP style. + But in a near future we will for example add the possibility to change logo, color in the PDF and + style sheet for the HTML. +

+
+ +
+ diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml index f0f97d8d45..2a420c53d9 100644 --- a/lib/erl_docgen/doc/src/overview.xml +++ b/lib/erl_docgen/doc/src/overview.xml @@ -1,10 +1,10 @@ - +
- 19972009 + 19972011 Ericsson AB. All Rights Reserved. @@ -20,7 +20,7 @@ under the License. - Overview + Overview OTP DTDs @@ -42,7 +42,7 @@ A collection of chapters (chapter).

- + Reference Manual @@ -72,23 +72,16 @@ the application or part DTD to write other types of documentation for the application.

- - -
- 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 structure of the different documents and the meaning of the + tags are explained. There are numerous examples of documentation + source code.

-

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

+

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 documentation of + an OTP application.

-

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

@@ -108,48 +101,5 @@ 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 documentation of - an OTP application.

- - This User's Guides are written using the part and - chapter DTDs. - - The Reference Manuals are written using - the application, appref and erlref DTDs. - - -
- -
- Usage - - - -

Create the relevant XML files.

- -

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.

- - - - - -
diff --git a/lib/erl_docgen/doc/src/part.xml b/lib/erl_docgen/doc/src/part.xml index 4594778a2f..26d660df08 100644 --- a/lib/erl_docgen/doc/src/part.xml +++ b/lib/erl_docgen/doc/src/part.xml @@ -27,10 +27,11 @@
-

Erl_Docgen provides functionality for generating HTML/PDF +

Erl_Docgen provides functionality for generating HTML/PDF/man 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/info b/lib/erl_docgen/info index 4dc2a02bfb..31c7eb911a 100644 --- a/lib/erl_docgen/info +++ b/lib/erl_docgen/info @@ -1,3 +1,2 @@ group: doc Documentation Applications short: A utility used to produce the OTP documentation. - -- cgit v1.2.3