
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.

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

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
