← Back to branch summary

~clint-fewbar/ubuntu/precise/erlang/merge-15b

« back to all changes in this revision

Viewing changes to lib/erl_docgen/doc/src/doc-build.xml

  • Committer: Package Import Robot
  • Author(s): Sergei Golovan
  • Date: 2011-12-15 19:20:10 UTC
  • mfrom: (1.1.18) (3.5.15 sid)
  • mto: (3.5.16 sid)
  • mto: This revision was merged to the branch mainline in revision 33.
  • Revision ID: package-import@ubuntu.com-20111215192010-jnxcfe3tbrpp0big
Tags: 1:15.b-dfsg-1
* New upstream release.
* Upload to experimental because this release breaks external drivers
  API along with ABI, so several applications are to be fixed.
* Removed SSL patch because the old SSL implementation is removed from
  the upstream distribution.
* Removed never used patch which added native code to erlang beam files.
* Removed the erlang-docbuilder binary package because the docbuilder
  application was dropped by upstream.
* Documented dropping ${erlang-docbuilder:Depends} substvar in
  erlang-depends(1) manpage.
* Made erlang-base and erlang-base-hipe provide virtual package
  erlang-abi-15.b (the number means the first erlang version, which
  provides current ABI).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/erl_docgen/doc/src/doc-build.xml
 
1
<?xml version="1.0" encoding="iso-8859-1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1997</year><year>2011</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
     </legalnotice>
 
23
    <title>How to Build OTP like documentation</title>
 
24
    <prepared></prepared>
 
25
    <docno></docno>
 
26
    <date></date>
 
27
    <rev></rev>
 
28
    <file>doc-build.xml</file>
 
29
  </header>
 
30
 
 
31
  <section>
 
32
    <title>Utilities to prepare XML files</title>
 
33
    <section>
 
34
      <title>Create XML files from code</title>
 
35
      <p>
 
36
        If there are EDoc comments in a module, the escript <c>xml_from_edoc.escript</c>
 
37
        can be used to generate an XML file according to the <c>erlref</c> DTD 
 
38
        for this module.
 
39
      </p>
 
40
      <p>
 
41
        Example:
 
42
      </p>
 
43
      <code>
 
44
 
 
45
        1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl
 
46
      </code>
 
47
    </section>
 
48
    <section>
 
49
      <title>Include code in XML</title>
 
50
      <p>If there are OTP DTD <i>codeinclude</i> tags in the source XML file, the escript
 
51
          <c>codeline_preprocessing.escript</c> can be used to include the code and produce
 
52
          an XML file according to the OTP DTDs. 
 
53
      </p>
 
54
      <p>
 
55
        Example:
 
56
      </p>
 
57
      <code>
 
58
 
 
59
        1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/codeline_preprocessing.escript ex1.xmlsrc ex1.xml
 
60
      </code>
 
61
    </section>
 
62
  </section>
 
63
 
 
64
  <section>
 
65
    <title>Use xsltproc to generate different output formats</title>
 
66
 
 
67
    <section>
 
68
      <title>Parameters used in all the the XSL transformations</title>
 
69
      <p>
 
70
        These parameters to <c>xsltproc</c> are used for all the supported output formats.
 
71
      </p>
 
72
      <taglist>
 
73
        <tag><c>docgen</c></tag>
 
74
        <item>
 
75
          Path to erl_docgen's top directory.
 
76
        </item>
 
77
        <tag><c>gendate</c></tag>
 
78
        <item>
 
79
          The date string that will be used in the documentation.
 
80
        </item>
 
81
        <tag><c>appname</c></tag>
 
82
        <item>
 
83
          The name of the application.>
 
84
        </item> 
 
85
        <tag><c>appver</c></tag>
 
86
        <item>
 
87
          The version of the application.
 
88
        </item>
 
89
     </taglist>
 
90
    </section>
 
91
 
 
92
    <section>
 
93
      <title>Generate HTML output</title>
 
94
      <p>
 
95
        When generating HTML one also needs these three pramaters to <c>xsltproc</c>.
 
96
      </p> 
 
97
      <taglist>
 
98
        <tag><c>outdir</c></tag>
 
99
        <item>
 
100
          Output directory for the produced html files.
 
101
        </item>
 
102
        <tag><c>topdocdir</c></tag>
 
103
        <item>
 
104
          If one builds a standalone documentation for an application this should be set to ".".
 
105
        </item>
 
106
        <tag><c>pdfdir</c></tag>
 
107
        <item>
 
108
          Relative path from the html directory to where the pdf file are placed.
 
109
        </item>
 
110
      </taglist>
 
111
      <p>
 
112
        Example:
 
113
      </p>
 
114
      <code>
 
115
        
 
116
        1> xsltproc --noout --stringparam outdir /tmp/myhtmldoc \
 
117
              --stringparam docgen $(ERL_TOP)/lib/erl_docgen \
 
118
              --stringparam topdocdir . \
 
119
              --stringparam pdfdir "$(PDFDIR)" \
 
120
              --xinclude \
 
121
              --stringparam gendate "December 5 2011" \
 
122
              --stringparam appname MyApp \
 
123
              --stringparam appver 0.1 \
 
124
              -path $ERL_TOP/lib/erl_docgen/priv/dtd \
 
125
              -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \
 
126
              $ERL_TOP/lib/erl_docgen/priv/xsl/db_html.xsl mybook.xml
 
127
      </code>
 
128
    </section>
 
129
 
 
130
    <section>
 
131
      <title>Generate PDF</title>
 
132
      <p>
 
133
        The generation of the PDF file is done in two steps. First is <c>xsltproc</c> used to generate a <c>.fo</c> file 
 
134
        which is used as input to the <c>fop</c> command to produce th PDF file.
 
135
      </p>
 
136
      <p>
 
137
        Example:
 
138
      </p>
 
139
      <code>
 
140
 
 
141
        1> xsltproc --output MyApp.fo \
 
142
             --stringparam docgen $ERL_TOP/lib/erl_docgen \
 
143
             --stringparam gendate  "December 5 2011" \
 
144
             --stringparam appname MyApp \
 
145
             --stringparam appver 0.1 \
 
146
             --xinclude \
 
147
             -path $ERL_TOP/lib/erl_docgen/priv/dtd \
 
148
             -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \
 
149
             $ERL_TOP/lib/erl_docgen/priv/xsl/db_pdf.xsl mybook.xml
 
150
 
 
151
 
 
152
        2> fop -fo MyApp.fo -pdf MyApp.pdf
 
153
      </code>
 
154
    </section>
 
155
 
 
156
    <section>
 
157
      <title>Generate man pages</title>
 
158
      <p>
 
159
        Unix man pages can be generated with <c>xsltproc</c> from XML files written according to 
 
160
        the different OTP ref type DTDs. 
 
161
      </p>
 
162
      <p>
 
163
        Example:
 
164
      </p>
 
165
      <code>
 
166
 
 
167
        1> xsltproc --output  my_module.3\
 
168
              --stringparam docgen $ERL_TOP/lib/erl_docgen \
 
169
              --stringparam gendate  "December 5 2011" \
 
170
              --stringparam appname MyApp \
 
171
              --stringparam appver 0.1 \
 
172
              --xinclude -path $ERL_TOP/lib/erl_docgen/priv/dtd  \
 
173
              -path $ERL_TOP/lib/erl_docgen/priv/dtd_man_entities \
 
174
              $ERL_TOP/lib/erl_docgen/priv/xsl/db_man.xsl my_refpage.xml
 
175
      </code>
 
176
    </section>
 
177
 
 
178
    <section>
 
179
      <title>Upcomming changes</title>
 
180
      <p>
 
181
        The output from the <c>erl_docgen</c> documentation build process is now just the OTP style. 
 
182
        But in a near future we will for example add the possibility to change logo, color in the PDF and 
 
183
        style sheet for the HTML.
 
184
      </p>
 
185
    </section>
 
186
 
 
187
  </section>
 
188
</chapter>