Minor update to source/base/build.h and related docs.

source-doc/devutils.md

@@ -19,6 +19,11 @@ Git Utilities
         The newly generated `revision.txt` is _not_ intended to be committed as-is, but rather merged with the
         previous version manually.
 
+  - `git update-index --skip-workspace FILENAME`: Use this git command for any file that you have to
+    change in your workspace but don't want to include in any commits nor have it overwritten
+    during a reset (e.g. `source/base/build.h`, which must be edited in a Windows build environment
+    to placate the `BUILT_BY` mechanism).
+
 
 Visual Studio 2010 Utilities
 ============================

source/base/build.h

@@ -13,7 +13,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -55,20 +55,78 @@
 ///
 /// @{
 
-// Placeholders for macros injected during automated builds - do not remove or change!
-//{POV_AUTOBUILD_A}
-//{POV_AUTOBUILD_B}
-//{POV_AUTOBUILD_C}
-//{POV_AUTOBUILD_1}
-//{POV_AUTOBUILD_2}
-//{POV_AUTOBUILD_3}
+/// @def POV_BUILD_INFO
+/// Additional version information pertaining to the build.
+///
+/// This optional macro should concisely identify the target runtime environment
+/// as well as the build environment used. For instance, POV-Ray for Windows,
+/// 32-bit binary with SSE2 enabled, built with Visual Studio 2015, might be
+/// identified as `msvc14.sse2.win32`.
+///
+/// @note
+///     If defined, this macro must evaluate to an ASCII string containing only
+///     alphanumeric characters or dots.
+///
+/// The content of this macro will be included in the binary's version string,
+/// separated from the source code version by a `+` character.
+///
+/// The intent is to be able to distinguish binaries generated from the same
+/// source code version but for different target platforms or using different
+/// build environments.
+///
+#if defined(DOXYGEN) && !defined(POV_BUILD_INFO)
+    // Work around doxygen being unable to document undefined macros.
+    #define POV_BUILD_INFO (undefined)
+    #undef POV_BUILD_INFO
+#endif
+
+/// @def POV_RAY_BUILD_ID
+/// Unique build identifier string.
+///
+/// This optional macro should be set to a different string each time the build
+/// process is run, for example by setting it to a timestamp or the value of a
+/// counter automatically incremented before each build.
+///
+/// @note
+///     If defined, this macro must evaluate to an ASCII string containing only
+///     alphanumeric characters or dots.
+///
+/// The content of this macro will effectively be appended to the
+/// @ref POV_BUILD_INFO, separated by a `.` character.
+///
+/// The intent is to be able to distinguish binaries generated from the same
+/// source code version for different target platforms and using similar build
+/// environments, but with potential minute differences that may or may not
+/// cause differences in the binaries.
+///
+/// @note
+///     This macro should never be defined in any source code, but rather
+///     injected via other means as part of the build process, e.g. via a
+///     compiler option (`-DPOV_RAY_BUILD_ID=...` in gcc).
+///
+#if defined(DOXYGEN) && !defined(POV_RAY_BUILD_ID)
+    // Work around doxygen being unable to document undefined macros.
+    #define POV_RAY_BUILD_ID (undefined)
+    #undef POV_RAY_BUILD_ID
+#endif
 
 /// @def BUILT_BY
 /// Specifies the person or organization responsible for this build.
-/// @attention Please set this to your real name, and/or include a working email or website address to contact you.
+///
+/// @attention
+///     Please set this to your real name, and/or include a working email or
+///     website address to contact you.
+///
+/// @note
+///     It is recommended to avoid editing this macro in the source code,
+///     and instead inject the macro via other means. If this is not feasible
+///     and you are working in a git workspace, it is recommended to run
+///     `git update-index --skip-worktree source/base/build.h` to avoid
+///     undesired interference between the repository and your local changes.
+///
 #ifndef BUILT_BY
-#define BUILT_BY "YOUR NAME (YOUR EMAIL)"
-#error "Please fill in BUILT_BY, then remove this line"
+    #define BUILT_BY "YOUR NAME (YOUR EMAIL)"
+    #error "Please fill in BUILT_BY, then remove this line"
 #endif
 
 /// @}

windows/README.md

@@ -104,6 +104,12 @@ Build Steps
     `#error` directive afterwards to proceed with the build. Note that
     if you do not do this you will get compile errors.
 
+    Note: If you are building in a Git local workspace, we recommend you run
+    `git update-index --skip-workspace source/base/build.h`. This will keep
+    your changes to the file from being included in a commit, or overwritten
+    in a pull or reset, while still allowing you to pull non-conflicting
+    updates to the file).
+
     By default, the GUI project is built, and the Console project is
     excluded. If you wish to generate a simple console version of
     POV-Ray, please modify the configuration as needed, edit