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. * technical documentation formerly found in vice/doc/plain/*.txt was moved into a seperate svn repository ("techdocs" in the main VICE repo). * 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 when adding/removing files, remember to update the main html page, and also the main doxy file (mainpage.dox). ------------------------------------------------------------------------------ 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:

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 , , , for example: @node New Section, Next Section, Last Section, Chapter @section New Section command-line options: --------------------- @table @code @findex -something @item -something Set something to (@code{SomeResource}) (all emulators except x128). (0: on, 1: off, 2: something else) @findex SomeResource @item SomeResource Set the volume (xplus4 only). (0..100) @findex -something, +something @item -something @itemx +something Enable/disable something (@code{SomeResource=1}, @code{SomeResource=0}) (xvic only). @end table resources: ---------- @table @code @vindex SomeResource @item SomeResource Boolean to enable some option (all emulators except x128). @vindex SomeResource @item SomeResource Integer specifying the mode to use (xvic only). (0: on, 1: off, 2: something else) @vindex SomeResource @item SomeResource Integer specifying the volume (xplus4 only). (0..100) @vindex SomeResource @item SomeResource String specifying the filename of the ROM (xplus4 and x64 only). @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 (xplus4, xvic and vsid only). @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. ------------------------------------------------------------------------------ platform specific sections: =========================== When VICE is configured with the --enable-platformdox option, the configure script will try to detect what platform is being compiled for and it will tell the documentation generation system to make the documentation platform specific. Only the parts of the vice.texi that are for the platform being compiled for will show up in the resulting documentation files. Certain variables are defined to indicate which platform the documentation needs to be generated for: - platformsdl (sdl) - platformgtk3 (gtk3) - platformunix (will be set when using platformgtk3) - platformosx (mac os x) - platformall (sets all previous variables) An example of a platform specific section would be: @ifset platformamiga * AmigaOS-specific features:: @end ifset ------------------------------------------------------------------------------ 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 documentation. - text (doc/vice.txt) Makeinfo is used to convert from texi to text, and the included doc/fixdates.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. ------------------------------------------------------------------------------ other files generated from the documentation: ============================================= Some other files are (re-)generated from information contained in the documentation, the sections that are used for this are indicated by a comment line: @c section used in file generation, keep to the format used. ... @c end of file generation section. Do not remove any comments in these sections and keep to the format being used in these sections. Files generated from these sections are: src/infocontrib.h (fully generated) src/arch/unix/macosx/Resources/Credits.html (fully generated) README (partially generated) doc/html/index.html (partially generated) ------------------------------------------------------------------------------ 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