[ci skip] Source documentation housekeeping; we're now relying on Doxygen 1.8.12.

Author: c-lipka

.gitignore

@@ -176,9 +176,6 @@ $RECYCLE.BIN/
 /configure
 /configure.ac
 /kde_install.sh
-/platform/Makefile
-/platform/Makefile.am
-/platform/Makefile.in
 /povray.1
 /povray.conf
 /povray.ini.in

source-doc/architecture.md

@@ -1,7 +1,7 @@
-# Architecture Overview {#architecture}
+@page architecture  Architecture Overview
 
 
-Modules {#arch_modules}
+Modules
 =======
 
 The original architectural design of POV-Ray 3.7.0 identified POV-Ray as being comprised of two main entities, called
@@ -11,8 +11,8 @@ compute raw output image data from it. The front-end would then wait for the ima
 write the collected data to an actual image file. The communication between the front- and back-end would use a
 proprietary asynchronous message-passing protocol called _POVMS_.
 
-Each of these two entities resided in a separate sub-tree within the source tree, named @ref source/backend and
-@ref source/frontend. A third sub-tree, @ref source/base, contained code shared between back- and front-end.
+Each of these two entities resided in a separate sub-tree within the source tree, named `source/backend` and
+`source/frontend`. A third sub-tree, `source/base`, contained code shared between back- and front-end.
 
 @remark
     The ability to run and manage multiple back-end instances is a prerequisite for distributed rendering in a networked
@@ -28,20 +28,23 @@ Since the official release of POV-Ray 3.7.0, ongoing work has been put into furt
 currently distinguishing the following _modules_, each of which again resides in its own separate source sub-tree:
 
 
-Back-End Module {#arch_backend}
+Back-End Module
 ---------------
 
 The responsibility of the _back-end_ module, residing in the @ref source/backend source sub-tree, is being trimmed down
 to coordinating multi-threaded execution of the _core_ and _parser_ modules, as well as interfacing them to a --
 possibly remote -- _front-end_ instance via the _POVMS_ protocol.
 
-@todo The exact line between the back-end module and the _core_ module has not been finalized yet.
+@todo
+    The exact line between the back-end module and the _core_ module has not been finalized yet.
 
 The back-end module depends on the _base_, _core_, _parser_, _povms_ and _vm_ modules.
-@todo At present, the back-end module also depends on the _vfe_ module.
 
+@todo
+    At present, the back-end module also depends on the _vfe_ module.
 
-Base Module {#arch_base}
+
+Base Module
 -----------
 
 The _base_ module, still residing in the @ref source/base source sub-tree, continues to be a loose collection of
@@ -51,10 +54,11 @@ _core_ and _front-end_.
 The base module is intended to be mostly unaware of multithreading, except that it makes provisions for sharing a few of
 its data structures -- mostly related to performance optimizations -- among multiple threads.
 
-@todo At present, the base module depends on the _vfe_ module.
+@todo
+    At present, the base module depends on the _vfe_ module.
 
 
-Core Module {#arch_core}
+Core Module
 -----------
 
 The _core_ module, residing in the @ref source/core source sub-tree, is designated to contain the actual render engine
@@ -67,23 +71,27 @@ The core module is intended to be mostly unaware of multithreading, except that
 its data structures -- mostly related to performance optimizations -- among multiple core threads.
 
 The core module depends on the _base_ module.
-@note Although the core module makes use of the _vm_ module at run-time, the interface is entirely abstract, and
-therefore does not constitute a formal dependency. From the perspective of the core module, the vm module could be
-replaced any time with an entirely different implementation.
+
+@note
+    Although the core module makes use of the _vm_ module at run-time, the interface is entirely abstract, and
+    therefore does not constitute a formal dependency. From the perspective of the core module, the vm module could be
+    replaced any time with an entirely different implementation.
 
 
-Front-End Module {#arch_frontend}
+Front-End Module
 ----------------
 
 The _front-end_ module, residing in the @ref source/frontend source sub-tree, currently retains its dual role of
 providing high-level control of the rendering process as well as assembling the computed image data into an actual
 result image file.
 
 The front-end module depends on the _base_ and _povms_ modules.
-@todo At present, the front-end module also depends on the _vfe_ module.
 
+@todo
+    At present, the front-end module also depends on the _vfe_ module.
 
-Parser Module {#arch_parser}
+
+Parser Module
 -------------
 
 The _parser_, residing in the @ref source/parser source sub-tree, is responsible for parsing a scene file, reading in
@@ -94,10 +102,12 @@ The parser module is entirely unaware of multithreading: It does not seem to mak
 to process the same file, nor to share data between multiple parser instances processing different files.
 
 The parser module depends on the _base_, _core_, and _vm_ modules.
-@todo At present, the parser module also depends on the _back-end_ module.
+
+@todo
+    At present, the parser module also depends on the _back-end_ module.
 
 
-POVMS Module {#arch_povms}
+POVMS Module
 ------------
 
 The _POVMS_ module, residing in the @ref source/povms source sub-tree, implements the message-passing interface used
@@ -106,7 +116,7 @@ between the _front-end_ and _back-end_ modules.
 The povms module depends on the _base_ module.
 
 
-Virtual Machine Module {#arch_vm}
+Virtual Machine Module {#module_vm}
 ----------------------
 
 The _virtual machine_ module, or _VM_, residing in the @ref source/vm source sub-tree, implements a virtual machine to
@@ -115,15 +125,41 @@ execute user-defined functions, both during parsing and at render time.
 The vm module depends on the _base_ and _core_ modules.
 
 
-Virtual Front-End Module {#arch_vfe}
+Platform-Specific Code {#module_sys}
+----------------------
+
+While the above modules are all designed to be portable, they rely on certain functionality that cannot be provided in a
+portable manner, and consequently require platform-specific adapter code; in addition, for some functionality optimized
+non-portable alternative implementations are provided. Such code resides in the separate @ref platform directory
+sub-tree, even when conceptually considered part of one of the above modules.
+
+@note
+    Platform-specific code should not be confused with _user interface_-specific code.
+
+@todo
+    At present, some platform-specific code also resides in the @ref vfe directory sub-tree.
+
+
+User Interface {#module_ui}
+--------------
+
+The above modules are started and controlled by the _user interface_.
+
+@note
+    POV-Ray does not provide any portable user interface; instead, each family of platforms has its own user interface,
+    and potentially even multiple entirely different user interfaces (such as the GUI and command-line versions of
+    POV-Ray for Windows).
+
+
+Virtual Front-End Module
 ------------------------
 
-The _virtual front-end_ module, or _VFE_, which resides outside the main source tree, contains code shared between most
-platform-specific versions of POV-Ray to abstract away various details of the _POVMS_ interface exposed by the official
-_front-end_.
+The _virtual front-end_ module, or _VFE_, residing in the @ref vfe directory, contains code shared between several
+user interfaces for POV-Ray, designed to abstract away various details of the _POVMS_ interface exposed by the
+_front-end module_.
 
 
-Units {#arch_units}
+Units
 =====
 
 The POV-Ray code is comprised of hundreds of code _units_ -- that is, individual `.cpp` files and their respective

source-doc/compiler.md

@@ -1,7 +1,7 @@
-# Compiler Requirements {#compiler}
+@page compiler  Compiler Requirements
 
 
-General Presumptions {#compiler_exot}
+General Presumptions
 ====================
 
 While POV-Ray is being developed with portability high in mind, the C++ standard allows for some degrees of freedom that
@@ -22,7 +22,7 @@ following additional restrictions:
     computed by the modulus operator `%`) is negative (or zero) if the dividend and divisor have different sign.
 
 
-POVMS Additional Restrictions {#compiler_povms}
+POVMS Additional Restrictions
 =============================
 
 To support network rendering (a feature not yet implemented but planned) in a heterogenous network, the POVMS interface

source-doc/devutils.md

@@ -1,16 +1,33 @@
-# Development Utilities {#devutils}
+@page devutils  Development Utilities
+
 
 Aside from the necessary material to re-build POV-Ray from scratch, the GitHub repository (and source package) also
 includes a few utilities that may make life a little easier for developers. These usually reside in the platform or
 build tool specific sections of the directory tree.
 
-@section vs10       Visual Studio 2010 utilities
+
+Git Utilities
+=============
+
+  - `tools/git/hooks/pre-commit`: Copy this to your local repository's `.git/hooks` directory for some automatic
+    housekeeping at each commit. Most notably, this will auto-increment the version number if you commit any changes to
+    the source code. It will also clean up whitespace and do a sanity check of the file header comments.
+
+  - `tools/git/revision.sh`: This shell script will re-generate `revision.txt` from the Git history.
+    @note
+        The newly generated `revision.txt` is _not_ intended to be committed as-is, but rather merged with the
+        previous version manually.
+
+
+Visual Studio 2010 Utilities
+============================
 
   - `windows/vs10/autoexp.dat`: For easier viewing of common POV-Ray data structures, merge the snippets in this file
     into `C:\Program Files\Microsoft Visual Studio 10.0\Common7\Packages\Debugger\autoexp.dat` (or wherever you happen
     to have installed Visual Studio).
 
   - `windows/vs10/StepOver.reg`: Import this to your registry to step over some library code during debugging.
     Currently, this steps over any code in std::tr1::shared_ptr and std::vector.
-    @warning    If you are already using the step over feature, check that the registry keys in `StepOver.reg` don't
-                conflict with any already in use.
+    @warning
+        If you are already using the step over feature, check that the registry keys in `StepOver.reg` don't
+        conflict with any already in use.

source-doc/include_hierarchy.md

@@ -1,57 +1,56 @@
-# Include Hierarchy {#include_hierarchy}
-
-Within the POV-Ray source code, the following rules apply for the include hierarchy of header files:
+@page include_hierarchy  Include Hierarchy
 
 
-@section self       Self-Containedness
-
-Header files should be self-contained, i.e. include all files they depend on themselves.
+Within the POV-Ray source code, the following rules apply for the include hierarchy of header files:
 
 
-@section small      Small Include Footprint
+General Rules
+=============
 
-Each file's include footprint should be kept small to simplify include hierarchy:
+  - **Self-Containedness**: Header files should be self-contained, i.e. include all files they depend on themselves.
 
-  - Forward type declarations shall be used wherever this avoids having to include a header file.
+  - **Small Include Footprint**: Each file's include footprint should be kept small to simplify the include hierarchy:
+      - Forward type declarations shall be used wherever this avoids having to include a header file.
+      - Files already included in a unit header file shall _not_ be included again in the respective `.cpp` file (e.g. a
+        file included in @ref core/colourspace.h shall not be included in @ref core/colourspace.cpp).
 
-  - Files already included in a unit header file shall _not_ be included again in the respective `.cpp` file (e.g. a
-    file included in @ref core/colourspace.h shall not be included in @ref core/colourspace.cpp).
 
+Pulling In Special Headers
+==========================
 
-@section spec       Pulling In Special Headers
 
-@subsection conf        Configuration Headers
+Configuration Headers
+---------------------
 
-The files @ref base/configbase.h, @ref core/configcore.h, @ref parser/configparser.h, @ref backend/configbackend.h and
-@ref frontend/configfrontend.h serve as module configuration headers, and the only POV-Ray configuration headers to be
-pulled in directly by code residing in the respective directory sub-tree; they automatically take care of pulling in any
-other relevant configuration headers, including platform-specific headers.
+The files @ref backend/configbackend.h, @ref base/configbase.h, @ref core/configcore.h, @ref frontend/configfrontend.h,
+@ref parser/configparser.h and @ref vm/configvm.h serve as module configuration headers, and the only POV-Ray
+configuration headers to be pulled in directly by code comprising part of the respective module; they automatically
+take care of pulling in any other relevant configuration headers, including platform-specific headers.
 
-@note   While the povms module has a configuration header following the same naming convention, the rules in this
-        section do _not_ apply accordingly.
+@note
+    While the povms module has a configuration header following the same naming convention, the rules in this
+    section do _not_ apply accordingly.
 
-Each and every file within the @ref base/, @ref core/, @ref parser/, @ref backend/ or @ref frontend/ directory sub-trees
-must effectively pull in the respective module configuration header as the very first header file. This is achieved by
-the following requirements:
+Each and every file comprising part of the _backend_, _base_, _core_, _frontend_, _parser_ or _vm_ module must
+effectively pull in the respective module configuration header as the very first header file. This is achieved by the
+following requirements:
 
-  - Each non-header file residing in the @ref base/, @ref core/, @ref parser/, @ref backend/ or @ref frontend/ directory
-    sub-tree shall include its respective unit header file (the header file with the same base name but `.h` or `.hpp`
-    extension) as the very first header file.
+  - Each non-header file comprising part of one of the aforementioned modules shall include its respective unit header
+    file (the header file with the same base name but `.h` or `.hpp` extension) as the very first header file.
 
-  - Each header file residing in the @ref base/, @ref core/, @ref parser/, @ref backend/ or @ref frontend/ directory
-    sub-tree shall include the respective module configuration header as the very first header file.
+  - Each header file comprising part of one of the aforementioned modules shall include the respective module
+    configuration header as the very first header file.
 
 This allows to also apply the following rule without any drawbacks:
 
-  - Each non-header file residing in the @ref base/, @ref core/, @ref parser/, @ref backend/ or @ref frontend/ directory
-    sub-tree, respectively, shall _not_ include the
-    respective module configuration header.
+  - Each non-header file comprising part of one of the aforementioned modules shall _not_ include the respective module
+    configuration header.
 
-The reason for this rule is to keep graphical representations of the include hierarchy simple.
+The intention of the latter rule is to keep graphical representations of the include hierarchy simple.
 
 
-@subsection debg        Last Header To Include
+Last Header To Include
+----------------------
 
-Each non-header source file residing in the @ref base/, @ref core/, @ref parser/, @ref backend/ or @ref frontend/
-directory sub-tree, respectively, or including any of the headers therein, shall include @ref base/povdebug.h as the
-very last include file.
+Each non-header source file including any header files from the _backend_, _base_, _core_, _frontend_, _parser_ or _vm_
+modules shall include @ref base/povdebug.h as the _very last_ include file.