1 <!doctype linuxdoc system>
4 <title>ca65html Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
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.
13 <!-- Table of contents -->
16 <!-- Begin the document -->
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.
30 <sect1>Command line option overview<p>
32 The HTML converter accepts the following options:
35 ---------------------------------------------------------------------------
36 Usage: ca65html [options] file ...
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
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 ---------------------------------------------------------------------------
61 <sect1>Command line options in detail<p>
63 Here is a description of all the command line options:
67 <tag><tt>--bgcolor c</tt></tag>
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/<body>/ of the
73 generated HTML output.
76 <tag><tt>--colorize</tt></tag>
78 Colorize the output. The converter outputs processor instructions, assembler
79 control commands, and comments in different colors.
82 <tag><tt>--commentcolor c</tt></tag>
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).
89 Note that this option has no effect if <tt/--colorize/ is not also given.
92 <tag><tt>--crefs</tt></tag>
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.
103 <tag><tt>--commentcolor c</tt></tag>
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).
110 Note that this option has no effect if <tt/--colorize/ is not also given.
113 <tag><tt>--cvttabs</tt></tag>
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.
120 <tag><tt>--help</tt></tag>
122 Print the command line option summary shown above.
125 <tag><tt>--htmldir dir</tt></tag>
127 Specify an output directory for the generated HTML files.
130 <tag><tt>--indexcols n</tt></tag>
132 Use n columns on the index page. This option has no effect if used without
136 <tag><tt>--indexname name</tt></tag>
138 Use another index file name instead of <tt/index.html/. This option has no
139 effect if used without <tt/--indexpage/.
142 <tag><tt>--indexpage</tt></tag>
144 Causes the converter to generate an index page listing file names, and all
145 exports found in the converted files.
148 <tag><tt>--indextitle title</tt></tag>
150 Use "title" as the title of the index page. This option has no effect if
151 used without <tt/--indexpage/.
154 <tag><tt>--keywordcolor c</tt></tag>
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).
161 Note that this option has no effect if <tt/--colorize/ is not also given.
163 <tag><tt>--linelabels</tt></tag>
165 Generate a label for each line using the name <tt/linexxx/ where xxx is the
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.
172 <tag><tt>--linenumbers</tt></tag>
174 Generate line numbers on the left side of the output.
177 <tag><tt>--linkstyle n</tt></tag>
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.
186 <tag><tt>--replaceext</tt></tag>
188 Replace the file extension of the input file instead of appending <tt/.html/
189 when generating the output file name.
192 <tag><tt>--textcolor c</tt></tag>
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/<body>/
198 of the generated HTML output.
201 <tag><tt>--verbose</tt></tag>
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.
211 <sect>Peculiarities<p>
213 <sect1>Cross links<p>
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.
220 <sect1>Include files<p>
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
227 <sect1>Conversion errors<p>
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.
238 <sect1>Colorization<p>
240 While having colors in the output looks really nice, it has one drawback:
244 <item>Because lots of <tt/<span>/ 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.
251 <sect>Bugs/Feedback<p>
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">).
262 ca65html is (c) Copyright 2000-2007 Ullrich von Bassewitz. For its use, the
263 following conditions apply:
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.
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:
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