]> git.sur5r.net Git - cc65/blob - doc/ca65html.sgml
Fixed type in target name (it is not supposed to be "geos-apple2") and adjusted the...
[cc65] / doc / ca65html.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>ca65html Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
6 <date>2007-10-2
7
8 <abstract>
9 ca65html is an assembly-source-to-HTML converter.  It is very useful if you
10 want to publish your assembler sources in the web.
11 </abstract>
12
13 <!-- Table of contents -->
14 <toc>
15
16 <!-- Begin the document -->
17
18 <sect>Overview<p>
19
20 ca65html converts assembly source files written for use with the <tt/<url
21 url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone
22 tool written in PERL; and as such, it does not understand the structure of
23 assembler sources in the same depth as ca65 does, so it may fail in very rare
24 cases. In all other cases, it generates very nice output.
25
26
27 <sect>Usage<p>
28
29
30 <sect1>Command line option overview<p>
31
32 The HTML converter accepts the following options:
33
34 <tscreen><verb>
35 ---------------------------------------------------------------------------
36 Usage: ca65html [options] file ...
37 Options:
38   --bgcolor c        Use background color c instead of #FFFFFF
39   --colorize         Add color highlights to the output
40   --commentcolor c   Use color c for comments instead of #B22222
41   --crefs            Generate references to the C source file(s)
42   --ctrlcolor c      Use color c for directives instead of #228B22
43   --cvttabs          Convert tabs to spaces in the output
44   --help             This text
45   --htmldir dir      Specify directory for HTML files
46   --indexcols n      Use n columns on index page (default 6)
47   --indexname file   Use file for the index file instead of index.html
48   --indexpage        Create an index page
49   --indextitle title Use title as the index title instead of Index
50   --keywordcolor c   Use color c for keywords instead of #A020F0
51   --linelabels       Generate a linexxx HTML label for each line
52   --linenumbers      Add line numbers to the output
53   --linkstyle style  Use the given link style
54   --replaceext       Replace source extension instead of appending .html
55   --textcolor c      Use text color c instead of #000000
56   --verbose          Be more verbose
57 ---------------------------------------------------------------------------
58 </verb></tscreen>
59
60
61 <sect1>Command line options in detail<p>
62
63 Here is a description of all the command line options:
64
65 <descrip>
66
67   <tag><tt>--bgcolor c</tt></tag>
68
69   Set the background color. The argument c must be a valid HTML color, usually
70   given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are the
71   respective red, green, and blue parts as two-digit hex values. The default is
72   <tt/#FFFFFF/ (white). That color is used in the <tt/&lt;body&gt;/ of the
73   generated HTML output.
74
75
76   <tag><tt>--colorize</tt></tag>
77
78   Colorize the output. The converter outputs processor instructions, assembler
79   control commands, and comments in different colors.
80
81
82   <tag><tt>--commentcolor c</tt></tag>
83
84   Set the color used for comments. The argument c must be a valid HTML color,
85   usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
86   the respective red, green, and blue parts as two-digit hex values. The
87   default is <tt/#B22222/ (red).
88
89   Note that this option has no effect if <tt/--colorize/ is not also given.
90
91
92   <tag><tt>--crefs</tt></tag>
93
94   Generate references to the C file, when a <tt/.dbg/ command is found with a
95   file name. The converter assumes that the C source was also converted into
96   HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and
97   lives in the same directory as the assembler file. If the <tt/.dbg/
98   directive specifies a line, a link to the correct line in the C file is
99   generated, using a label in the form <tt/linexxx/, as it is created by
100   <tt/c2html/ by use of the <tt/-n/ option.
101
102
103   <tag><tt>--commentcolor c</tt></tag>
104
105   Set the color used for assembler control commands. The argument c must be a
106   valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
107   where r, g, and b are the respective red, green, and blue parts as two-digit
108   hex values. The default is <tt/#228B22/ (green).
109
110   Note that this option has no effect if <tt/--colorize/ is not also given.
111
112
113   <tag><tt>--cvttabs</tt></tag>
114
115   Convert tabs in the input into spaces in the output, assuming the standard
116   tab width of 8. This is useful if the <tt/--linenumbers/ option is used to
117   retain the indentation.
118
119
120   <tag><tt>--help</tt></tag>
121
122   Print the command line option summary shown above.
123
124
125   <tag><tt>--htmldir dir</tt></tag>
126
127   Specify an output directory for the generated HTML files.
128
129
130   <tag><tt>--indexcols n</tt></tag>
131
132   Use n columns on the index page. This option has no effect if used without
133   <tt/--indexpage/.
134
135
136   <tag><tt>--indexname name</tt></tag>
137
138   Use another index file name instead of <tt/index.html/. This option has no
139   effect if used without <tt/--indexpage/.
140
141
142   <tag><tt>--indexpage</tt></tag>
143
144   Causes the converter to generate an index page listing file names, and all
145   exports found in the converted files.
146
147
148   <tag><tt>--indextitle title</tt></tag>
149
150   Use "title" as the title of the index page. This option has no effect if
151   used without <tt/--indexpage/.
152
153
154   <tag><tt>--keywordcolor c</tt></tag>
155
156   Set the color used for processor instructions. The argument c must be a
157   valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
158   where r, g, and b are the respective red, green, and blue parts as two-digit
159   hex values. The default is <tt/#A020F0/ (purple).
160
161   Note that this option has no effect if <tt/--colorize/ is not also given.
162
163   <tag><tt>--linelabels</tt></tag>
164
165   Generate a label for each line using the name <tt/linexxx/ where xxx is the
166   number of the line.
167
168   Note: The converter will not make use of this label. Use this option if you
169   have other HTML pages referencing the converted assembler file.
170
171
172   <tag><tt>--linenumbers</tt></tag>
173
174   Generate line numbers on the left side of the output.
175
176
177   <tag><tt>--linkstyle n</tt></tag>
178
179   Influences the style used when generating links for imports. If n is zero
180   (the default), the converter creates a link to the actual symbol if it is
181   defined somewhere in the input files. If not, it creates a link to the
182   <tt/.import/ statement. If n is one, the converter will always generate a
183   HTML link to the <tt/.import/ statement.
184
185
186   <tag><tt>--replaceext</tt></tag>
187
188   Replace the file extension of the input file instead of appending <tt/.html/
189   when generating the output file name.
190
191
192   <tag><tt>--textcolor c</tt></tag>
193
194   Set the color for normal text. The argument c must be a valid HTML color,
195   usually given as RGB triplet in the form <tt/#rrggbb/, where r, g, and b are
196   the respective red, green, and blue parts as two-digit hex values. The
197   default is <tt/#000000/ (black). This color is used in the <tt/&lt;body&gt;/
198   of the generated HTML output.
199
200
201   <tag><tt>--verbose</tt></tag>
202
203   Increase the converter verbosity. Without this option, ca65html is quiet
204   when working. If you have a slow machine and lots of files to convert, you
205   might like a little bit more progress information.
206
207 </descrip>
208 <p>
209
210
211 <sect>Peculiarities<p>
212
213 <sect1>Cross links<p>
214
215 Since ca65html is able to generate links between modules, the best way to use
216 it is to supply all modules to it in one run, instead of running each file
217 separately through it.
218
219
220 <sect1>Include files<p>
221
222 For now, ca65html will not read files included with <tt/.include/. Specifying
223 the include files as normal input files on the command line works in many
224 cases.
225
226
227 <sect1>Conversion errors<p>
228
229 Since ca65html does not really parse the input, but does most of its work
230 applying text patterns, it doesn't know anything about scoping and advanced
231 features of the assembler. This means that it might miss a label.  And, it
232 might choose the wrong color for an item, in rare cases. Because it's just a
233 tool for displaying sources in a nice form, I think that's OK. Anyway, if you
234 find a conversion problem, you can send me a short piece of example input code.
235 If possible, I will fix it.
236
237
238 <sect1>Colorization<p>
239
240 While having colors in the output looks really nice, it has one drawback:
241
242 <enum>
243
244 <item>Because lots of <tt/&lt;span&gt;/ tags are created in the output,
245 the size of the output file literally will explode.  It seems to be the price
246 that you have to pay for color.
247
248 </enum>
249
250
251 <sect>Bugs/Feedback<p>
252
253 If you have problems using the converter, if you find any bugs, or if you're
254 doing something interesting with the assembler, I would be glad to hear from
255 you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
256 name="uz@cc65.org">).
257
258
259
260 <sect>Copyright<p>
261
262 ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the
263 following conditions apply:
264
265 This software is provided 'as-is', without any expressed or implied
266 warranty.  In no event will the authors be held liable for any damages
267 arising from the use of this software.
268
269 Permission is granted to anyone to use this software for any purpose,
270 including commercial applications, and to alter it and redistribute it
271 freely, subject to the following restrictions:
272
273 <enum>
274 <item>  The origin of this software must not be misrepresented; you must not
275         claim that you wrote the original software. If you use this software
276         in a product, an acknowledgment in the product documentation would be
277         appreciated but is not required.
278 <item>  Altered source versions must be plainly marked as such, and must not
279         be misrepresented as being the original software.
280 <item>  This notice may not be removed or altered from any source
281         distribution.
282 </enum>
283
284
285
286 </article>
287
288
289