--- /dev/null
+<!doctype linuxdoc system>
+
+<article>
+<title>ca65html Users Guide
+<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
+<date>2003-10-16
+
+<abstract>
+ca65html is an assembler source to HTML converter. It is very useful if you
+want to publish your assembler sources in the web.
+</abstract>
+
+<!-- Table of contents -->
+<toc>
+
+<!-- Begin the document -->
+
+<sect>Overview<p>
+
+ca65html converts assembler source files written for use with the <tt/<htmlurl
+url="ca65.html" name="ca65">/ crossassembler into HTML. It is a standalone
+tool written in Perl, and as such it does not understand the structure of
+assembler sources in the same depth as ca65 does, so it may fail in very rare
+cases. In all other cases it generates very nice output.
+
+
+<sect>Usage<p>
+
+
+<sect1>Command line option overview<p>
+
+The HTML converter accepts the following options:
+
+<tscreen><verb>
+---------------------------------------------------------------------------
+Usage: ca65html [options] file ...
+Options:
+ --bgcolor c Use background color c instead of #FFFFFF
+ --colorize Colorize the output (generates non standard HTML)
+ --commentcolor c Use color c for comments instead of #B22222
+ --crefs Generate references to the C source file(s)
+ --ctrlcolor c Use color c for directives instead of #228B22
+ --cvttabs Convert tabs to spaces in the output
+ --help This text
+ --htmldir dir Specify directory for HTML files
+ --indexcols n Use n columns on index page (default 6)
+ --indexname file Use file for the index file instead of index.html
+ --indexpage Create an index page
+ --indextitle title Use title as the index title instead of Index
+ --keywordcolor c Use color c for keywords instead of #A020F0
+ --linelabels Generate a linexxx HTML label for each line
+ --linenumbers Add line numbers to the output
+ --linkstyle style Use the given link style
+ --replaceext Replace source extension instead of appending .html
+ --textcolor c Use text color c instead of #000000
+ --verbose Be more verbose
+---------------------------------------------------------------------------
+</verb></tscreen>
+
+
+<sect1>Command line options in detail<p>
+
+Here is a description of all the command line options:
+
+<descrip>
+
+ <tag><tt>--bgcolor c</tt></tag>
+
+ Set the background color. The argument c must be a valid HTML color, usually
+ given as RGB triplet in the form <tt/#rrggbb/, where r, g and b are the
+ respective red, green and blue parts as two digit hex values. The default is
+ <tt/#FFFFFF/ (white). This color is used in the <tt/<body>/ tag of the
+ generated HTML output.
+
+
+ <tag><tt>--colorize</tt></tag>
+
+ Colorize the output. The converter outputs processor instructions, assembler
+ control commands and comments in different colors.
+
+ While this make the output look very nice, it generates invalid HTML,
+ because using colors in a <tt/<pre>/ environment is not allowed.
+ However, most browsers display it well, and it is used by several other
+ tools, so it's up to you.
+
+
+ <tag><tt>--commentcolor c</tt></tag>
+
+ Set the color used for comments. The argument c must be a valid HTML color,
+ usually given as RGB triplet in the form <tt/#rrggbb/, where r, g and b are
+ the respective red, green and blue parts as two digit hex values. The
+ default is <tt/#B22222/ (red).
+
+ Note that this option has no effect if <tt/--colorize/ is not also given.
+
+
+ <tag><tt>--crefs</tt></tag>
+
+ Generate references to the C file, when a <tt/.dbg/ command is found with a
+ file name. The converter assumes that the C source was also converted into
+ HTML (for example by use of <tt/c2html/), has the name <tt/file.c.html/, and
+ lives in the same directory as the assembler file. If the <tt/.dbg/
+ directive specifies a line, a link to the correct line in the C file is
+ generated, using a label in the form <tt/linexxx>/, as it is created by
+ <tt/c2html/ by use of the <tt/-n/ option.
+
+
+ <tag><tt>--commentcolor c</tt></tag>
+
+ Set the color used for assembler control commands. The argument c must be a
+ valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
+ where r, g and b are the respective red, green and blue parts as two digit
+ hex values. The default is <tt/#228B22/ (green).
+
+ Note that this option has no effect if <tt/--colorize/ is not also given.
+
+
+ <tag><tt>--cvttabs</tt></tag>
+
+ Convert tabs in the input into spaces in the output, assuming the standard
+ tab width of 8. This is useful if the <tt/--linenumbers/ option is used to
+ retain the indentation.
+
+
+ <tag><tt>--help</tt></tag>
+
+ Print the command line option summary shown above.
+
+
+ <tag><tt>--htmldir dir</tt></tag>
+
+ Specify an output directory for the generated HTML files.
+
+
+ <tag><tt>--indexcols n</tt></tag>
+
+ Use n columns on the index page. This option has no effect if used without
+ <tt/--indexpage/.
+
+
+ <tag><tt>--indexname name</tt></tag>
+
+ Use another index file name instead of <tt/index.html/. This option has no
+ effect if used without <tt/--indexpage/.
+
+
+ <tag><tt>--indexpage</tt></tag>
+
+ Causes the converter to generate an index page listing all label names and
+ exports found in the converted files.
+
+
+ <tag><tt>--indextitle title</tt></tag>
+
+ Use "title" as the title of the index page. This option has no effect if
+ used without <tt/--indexpage/.
+
+
+ <tag><tt>--keywordcolor c</tt></tag>
+
+ Set the color used for processor instructions. The argument c must be a
+ valid HTML color, usually given as RGB triplet in the form <tt/#rrggbb/,
+ where r, g and b are the respective red, green and blue parts as two digit
+ hex values. The default is <tt/#A020F0/ (purple).
+
+ Note that this option has no effect if <tt/--colorize/ is not also given.
+
+ <tag><tt>--linelabels</tt></tag>
+
+ Generate a label for each line using the name <tt/linexxx/ where xxx is the
+ number of the line.
+
+ Note: The converter will not make use of this label. Use this option if you
+ have other HTML pages referencing the converted assembler file.
+
+
+ <tag><tt>--linenumbers</tt></tag>
+
+ Generate line numbers on the left side of the output.
+
+
+ <tag><tt>--linkstyle n</tt></tag>
+
+ Influences the style used when generating links for imports. If n is zero
+ (the default), the converter creates a link to the actual symbol if it is
+ defined somewhere in the input files. If not, it creates a link to the
+ <tt/.import/ statement. If n is one, the converter will always generate a
+ HTML link to <tt/.import/ statement.
+
+
+ <tag><tt>--replaceext</tt></tag>
+
+ Replace the file extension of the input file instead of appending <tt/.html/
+ when generating the output file name.
+
+
+ <tag><tt>--textcolor c</tt></tag>
+
+ Set the color for normal text. The argument c must be a valid HTML color,
+ usually given as RGB triplet in the form <tt/#rrggbb/, where r, g and b are
+ the respective red, green and blue parts as two digit hex values. The
+ default is <tt/#000000/ (black). This color is used in the <tt/<body>/
+ tag of the generated HTML output.
+
+
+ <tag><tt>--verbose</tt></tag>
+
+ Increase the converter verbosity. Without this option, ca65html is quiet
+ when working. If you have a slow machine and lots of files to convert, you
+ may like a little bit more progress information.
+
+</descrip>
+<p>
+
+
+<sect>Peculiarities<p>
+
+<sect1>Cross links<p>
+
+Since <tt/ca65html/ is able to generate links between modules, the best way to
+use it is to supply all modules to it in one run, instead of running each file
+separately through it.
+
+
+<sect1>Include files<p>
+
+For now, <tt/ca65html/ will not read files included with <tt/.include/.
+Specifying the include files as normal input files on the command line works
+in many cases.
+
+
+<sect1>Conversion errors<p>
+
+Since <tt/ca65html/ does not really parse the input, but does most of its work
+applying text patterns, it doesn't know anything about scoping and advanced
+features of the assembler. This means that it may miss a label may choose the
+wrong color for an item in rare cases. Since it's just a tool for displaying
+sources in a nice form, I think that's ok. Anyway, if you find a conversion
+problem, you can send me a short piece of example input code. If possible, I
+will fix it.
+
+
+<sect1>Colorization<p>
+
+While having colors in the output looks really nice, it has two drawbacks:
+
+<enum>
+
+<item>The output is not standard compliant HTML, because <tt/<font>/
+tags are use in a <tt/<pre>/ environment. This works with all browsers
+I've tested, but it may not work with the one you're using.
+
+<item>Since lots of <tt/<font>/ tags are created in the output, the size
+of the output file will literally explode. This seems to be the price, you
+have to pay for color...
+
+</enum>
+
+
+<sect>Bugs/Feedback<p>
+
+If you have problems using the converter, if you find any bugs, or if you're
+doing something interesting with the assembler, I would be glad to hear from
+you. Feel free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
+name="uz@cc65.org">).
+
+
+
+<sect>Copyright<p>
+
+ca65html is (C) Copyright 2000-2003 Ullrich von Bassewitz. For its use the
+following conditions apply:
+
+This software is provided 'as-is', without any expressed or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+<enum>
+<item> The origin of this software must not be misrepresented; you must not
+ claim that you wrote the original software. If you use this software
+ in a product, an acknowledgment in the product documentation would be
+ appreciated but is not required.
+<item> Altered source versions must be plainly marked as such, and must not
+ be misrepresented as being the original software.
+<item> This notice may not be removed or altered from any source
+ distribution.
+</enum>
+
+
+
+</article>
+
+
+
Main documentation page, contains links to other available stuff.
</abstract>
-<sect>
Documentation overview<p>
+<sect>
Program documentation<p>
<descrip>
- <tag><htmlurl url="BUGS" name="BUGS"></tag>
- Known compiler bugs.
-
- <tag><htmlurl url="CREDITS" name="CREDITS"></tag>
- Who helped with the compiler and tools?
-
<tag><htmlurl url="ar65.html" name="ar65.html"></tag>
Describes the ar65 archiver.
<tag><htmlurl url="ca65.html" name="ca65.html"></tag>
Describes the ca65 macro assembler.
+ <tag><htmlurl url="ca65html.html" name="ca65html.html"></tag>
+ Describes the ca65html assembler source to HTML converter.
+
<tag><htmlurl url="cc65.html" name="cc65.html"></tag>
Describes the cc65 C compiler.
<tag><htmlurl url="cl65.html" name="cl65.html"></tag>
Describes the cl65 compile & link utility.
+ <tag><htmlurl url="da65.html" name="da65.html"></tag>
+ Describes the da65 6502/65C02 disassembler.
+
+ <tag><htmlurl url="grc.txt" name="grc.txt"></tag>
+ Describes the GEOS resource compiler (grc).
+
+ <tag><htmlurl url="ld65.html" name="ld65.html"></tag>
+ Describes the ld65 linker.
+
+</descrip>
+
+
+<sect>Usage<p>
+
+<descrip>
+
+ <tag><htmlurl url="intro.html" name="intro.html"></tag>
+ Describes the use of the tools by a short "hello world" example.
+
<tag><htmlurl url="coding.html" name="coding.html"></tag>
Containes hints on creating the most effective code with cc65.
<tag><htmlurl url="compile.txt" name="compile.txt"></tag>
How to compile cc65 and the support tools.
- <tag><htmlurl url="da65.html" name="da65.html"></tag>
- Describes the da65 6502/65C02 disassembler.
-
<tag><htmlurl url="debugging.html" name="debugging.html"></tag>
Debug programs using the VICE emulator.
- <tag><htmlurl url="dio.html" name="dio.html"></tag>
- Low level disk I/O API.
+</descrip>
+
+<sect>Library information and other references<p>
+
+<descrip>
<tag><htmlurl url="funcref.html" name="funcref.html"></tag>
A (currently incomplete) function reference.
- <tag><htmlurl url="geos.html" name="geos.html"></tag>
- GEOSLib manual in several formats.
-
- <tag><htmlurl url="grc.txt" name="grc.txt"></tag>
- Describes the GEOS resource compiler (grc).
+ <tag><htmlurl url="dio.html" name="dio.html"></tag>
+ Low level disk I/O API.
- <tag><htmlurl url="index.html" name="index.html"></tag>
- This file.
+ <tag><htmlurl url="geos.html" name="geos.html"></tag>
+ The GEOSLib manual.
<tag><htmlurl url="internal.txt" name="internal.txt"></tag>
A somewhat older text describing several cc65 internals.
- <tag><htmlurl url="intro.html" name="intro.html"></tag>
- Describes the use of the tools by a short "hello world" example.
-
- <tag><htmlurl url="ld65.html" name="ld65.html"></tag>
- Describes the ld65 linker.
-
<tag><htmlurl url="library.html" name="library.html"></tag>
Describes the cc65 runtime and C libraries.
+</descrip>
+
+
+<sect>Platform specific information<p>
+
+<descrip>
+
+ <tag><htmlurl url="atari.html" name="atari.html"></tag>
+ Topics specific to the Atari 8 bit machines.
+
+ <tag><htmlurl url="c64.html" name="c64.html"></tag>
+ Topics specific to the Commodore 64.
+
+</descrip>
+
+
+<sect>Miscellaneous<p>
+
+<descrip>
+
<tag><htmlurl url="newvers.txt" name="newvers.txt"></tag>
Somewhat outdated. Lists the differences between the current cc65 release
and the original atari version created by J.R Dunning.
+ <tag><htmlurl url="BUGS" name="BUGS"></tag>
+ Known compiler bugs.
+
+ <tag><htmlurl url="CREDITS" name="CREDITS"></tag>
+ Who helped with the compiler and tools?
+
</descrip>
</article>
projects / cc65 / commitdiff