
This document contains information on how to create/edit the documentation
that comes with VICE. Incase you were looking for the documentation itself,
look at the generated files in the html subdirectory.

------------------------------------------------------------------------------

WARNING: this document is under construction :)

Overview:
=========

* vice/doc/vice.texi is the main documentation source.

* vice/doc/plain/*.txt should contain only technical information (related to
  actual commodore computers, not vice). Files placed here should get linked
  from index.html and als mentioned in vice.texi

* vice/doc/readmes/*.txt should contain port specific readme files
* vice/doc/building/*.txt should contain info on building specific ports
* vice/doc/*.txt should only contain developer- or port-specific info

------------------------------------------------------------------------------

updating the documentation:
===========================

to make half automatic checking easier, mark things that should be fixed right
in vice.texi in the following form:

@c FIXME: <details>

chapters/sections:
------------------

when creating a new chapter or (sub)section, you may not want to immediatly
create a proper node (and possibly menus) too. in that case add a comment
like this directly above the new section:

@c @node FIXME
@subsection New Section

the general format of a node looks like this:

@node <this node>, <next node>, <previous node>, <parent node>

for example:

@node New Section, Next Section, Last Section, Chapter
@section New Section

command-line options:
---------------------

@table @code

@cindex -something
@item -something <value>
Set something to <value>.

@cindex -something, +something
@item -something
@itemx +something
Enable/disable something

@end table

resources:
----------

@table @code

@vindex SomeResource
@item SomeResource
Boolean to enable some option.

@c NOTE: put commands above this block, not in between
@vindex SomeResource1
@vindex SomeResource2
@vindex SomeResource3
@vindex SomeResource4
@item SomeResource1
@itemx SomeResource2
@itemx SomeResource3
@itemx SomeResource4
Boolean to enable some option.

@end table

simple unnumbered list:
-----------------------

@itemize @bullet

@item foo
@item bar

@end itemize

preformatted text:
------------------

@example
    +---------
    + whatever
    +---------
@end example

Warning: using more than 77 characters per line will produce bugs in the pdf
         output (and possibly others) - use @smallexample instead in such cases.

------------------------------------------------------------------------------

generating the various documentation formats:
=============================================

The VICE documentation base is vice.texi, all the other documentation formats
are generated from this file.

The following formats are generated provided you have the tools to be able
to generate them:

- html (doc/html/vice_*.html)
  The included doc/html/texi2html perl script is used to convert from texi to
  html. Perl needs to be installed to be able to generate the html documenation.

- text (doc/vice.txt)
  Makeinfo is used to convert from texi to text, and the included doc/fixdox.sh
  shell script is used to 'post-fix' the text. Makeinfo needs to be installed
  to be able to generate the text documentation.

- pdf (doc/vice.pdf)
  Texi2dvi is used to convert from texi to pdf. Texi2dvi needs to be installed
  to be able to generate the pdf documentation.

- amigaguide (doc/vice.guide)
  A special version of makeinfo that is able to generate amigaguide files is
  used to convert from texi to amigaguide. If you want to keep your regular
  makeinfo you can rename the amigaguide makeinfo to makeguide and the
  configure script will be able to find and use it. The included
  doc/texi2guide.sh shell script is used to do the actual converting. The
  special amigaguide makeinfo/makeguide needs to be installed to be able to
  generate amigaguide documentation.
  
  http://aminet.net/text/hyper/mkguide155.lha

- windows help (doc/vice.hlp)
  Makertf and hcrtf from the winhelp compiler package 
  is used to convert from texi to
  windows help. The included doc/fixdox.sh shell script is used to pre-fix the
  texi file so that it can be converted by makertf to rtf, which hcrtf then
  converts to a windows help file. Makertf and hcrtf need to be installed to
  be able to generate the window help documentation.

  http://download.microsoft.com/download/office97dev/helpws97/4.03/win98/en-us/hcwsetup.exe

- windows chm (doc/vice.chm)
  Hhc from the Microsoft help compiler package is used to convert from texi to
  windows chm. The included doc/texi2chm.sh shell script is used to do the
  actual converting. It uses the included doc/fixdox.sh shell script to
  pre-fix the texi file so that the included doc/t2h.pl perl script can
  convert the texi file to an html file which hhc can then convert to a
  windows chm. Hhc and perl need to be installed to be able to generate the
  windows chm documentation.

  http://go.microsoft.com/fwlink/?LinkId=14188

- os/2 inf (doc/vice.inf)
  Texi2ipf in combination with either ipfc (which is part of the ibm visual age
  c++ package) or wipfc (which is part of the openwatcom package) is used to
  convert from texi to os/2 inf. Texi2ipf and (w)ipfc needs to be installed to
  be able to generate os/2 inf documentation.

- info (doc/vice.info)
  Makeinfo is used to convert texi to info. Makeinfo needs to be installed to
  be able to generate info documentation.
  
------------------------------------------------------------------------------

how to use the checkdoc tool:
=============================

This is a little tool which tries to automatically check the documentation for
some common errors and missing things, for example:
 - missing and/or outdated commandline options
 - missing and/or outdated resources
 - incorrect usage of the index

- the tool must be run from within vice/doc and the emulator must be installed
  prior to running the tool (because that is required for the translation stuff
  to work correctly)

run the tool by either typing

make -f checkdoc.mak <option>

or (if your shell can figure out and call the interpreter) simply:

./checkdoc.mak <option>

with option being one of either

full    do all checks
opt     check command-line options
res     check resources
listopt list all command-line options
listres list all resources
fixme   show FIXMEs
nodes   show nodes marked FIXME
clean   remove temp files
update  generate the documentation

------------------------------------------------------------------------------

TODO:
=====

like mentioned above, the todo list is contained in vice.texi in the form of
comments. to show it using the checkdoc tool use "./checkdoc.mak fixme"

at the time of last updating this file (30/06/2012), the list looked like this:

list of FIXMEs (26):
669:@c FIXME: add link to doc/html/plain/PETdoc.txt
690:@c FIXME: add link to doc/html/plain/PETdoc.txt
719:@c FIXME: add link to section
789:@c FIXME: add a detailed list of all keys
4323:@c FIXME: is this correct?
4417:@c FIXME: clean up "c64/128" vs "c64"
8475:@c FIXME: relink this node
10329:@c FIXME: add some info on making screenshots, wav- and avi recordings
10406:@c FIXME: the "Event history" section needs to be style-checked.
11366:@c FIXME: add more c1541 examples
11741:@c FIXME: add D67 CBM2040 (DOS1) disk image file structure
11742:@c FIXME: add D1M FD2000/FD4000 DD disk image file structure
11743:@c FIXME: add D2M FD2000/FD4000 HD disk image file structure
11744:@c FIXME: add D4M FD4000 ED disk image file structure
12163:@c FIXME: the P64 section needs to be style-checked.
12451:@c FIXME: the D64 section needs to be style-checked.
13347:@c FIXME: the X64 section needs to be style-checked.
13463:@c FIXME: the D71 section needs to be style-checked.
14125:@c FIXME: the D81 section needs to be style-checked.
15024:@c FIXME: the D80 section needs to be style-checked.
15714:@c FIXME: the D82 section needs to be style-checked.
16806:@c FIXME: the P00 section needs to be style-checked.
16860:@c FIXME: the CRT section needs to be style-checked.
19704:@c FIXME: todo
19720:@c FIXME: todo
19736:@c FIXME: todo

nodes that need fixing (180)

to get a much more detailed list use "./checkdoc.mak full"

------------------------------------------------------------------------------

Last fully checked:

c64 using cartridges                        - 22/01/2011
c64 io extensions                           - 22/01/2011

monitor                                     - 22/01/2011

petcat                                      - 22/01/2011
cartconv                                    - 22/01/2011
c1541                                       -

all command line options complete           - 19/06/2012
all resources complete                      - 22/06/2012
