mirror of
https://github.com/cc65/cc65.git
synced 2024-12-25 17:29:50 +00:00
Restructured the index file.
Added documentation for the ca65html utility. git-svn-id: svn://svn.cc65.org/cc65/trunk@2539 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz
parent
e6c62531d7
commit
818cfc8677
@ -9,6 +9,7 @@ SGML = ar65.sgml \
|
||||
atari.sgml \
|
||||
c64.sgml \
|
||||
ca65.sgml \
|
||||
ca65html.sgml \
|
||||
cc65.sgml \
|
||||
cl65.sgml \
|
||||
co65.sgml \
|
||||
|
||||
298
doc/ca65html.sgml
Normal file
298
doc/ca65html.sgml
Normal file
@ -0,0 +1,298 @@
|
||||
<!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>
|
||||
|
||||
|
||||
|
||||
@ -9,71 +9,104 @@
|
||||
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="dio.html" name="dio.html"></tag>
|
||||
Low level disk I/O API.
|
||||
|
||||
<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="index.html" name="index.html"></tag>
|
||||
This file.
|
||||
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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user