[ntpsec commit] Document the documentation policy.

[Eric S. Raymond]

Module:    ntpsec
Branch:    master
Commit:    d8ff1b5ec11f110e9501926243ddbe5d560a88d0
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=d8ff1b5ec11f110e9501926243ddbe5d560a88d0

Author:    Eric S. Raymond <esr at thyrsus.com>
Date:      Thu Oct 15 16:47:32 2015 -0400

Document the documentation policy.

---

 devel-docs/hacking.txt | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/devel-docs/hacking.txt b/devel-docs/hacking.txt
index 7e0f9b0..ea8ab1d 100644
--- a/devel-docs/hacking.txt
+++ b/devel-docs/hacking.txt
@@ -131,7 +131,7 @@ For documentation:
 // SPDX-License-Identifier: CC-BY-4.0
 ------------------------------------------------
 
-Modify as needed for whatever comment syntax the languge or markup uses.
+Modify as needed for whatever comment syntax the language or markup uses.
 Good places for these markings are at the end of an extended
 header comment, or at the very top of the file.
 
@@ -140,7 +140,7 @@ especially all references to Dr. Dave Mills, to Mr Harlan Stenn, and
 to the Network Time Foundation.
 
 You *may* add a project copyright and replace the inline license
-with an SPDX tag. For exmple:
+with an SPDX tag. For example:
 
 ------------------------------------------------
 /* Copyright 2015 by the NTPsec project contributors
@@ -153,6 +153,37 @@ the historic copyright is no longer appropriate, but such decisions
 cannot be made casually. Discuss it with the project management
 before moving.
 
+=== Documentation format and structure ===
+
+All our documentation is mastered in asciidoc.  That includes internal
+documentation like this file. We do this because asciidoc is easy to
+edit and gives us good options for rendering to multiple formats,
+including both HTML and Unix manual pages
+
+If you're going to write in anything else you need to have a good
+reason, and the bar for "good" will be set high.  "I like Markdown",
+in particular, does not qualify - it doesn't have good enough table
+support for our needs.  ReST does, but the hassle costs of supporting
+two different master markups are too high.
+
+The NTP Classic documentation had a terrible problem with duplicative
+documentation gradually diverging as the duplicates mutated and
+bitrotted. Therefore one of our house rules is to have a *single point
+of truth* for everything.
+
+Accordingly, the way we handle pairs of manual and Web pages that
+need to have the same content is to have both be thin wrappers around
+a large common include file. These includes live in docs/includes
+and are probably what you need to edit if you're updating anything
+that appears on a man page.
+
+Most manual-page masters actually have the extension *.txt.in.  The
+.in part is a convention for files that need to be macroexpanded as a
+first stage for processing.  The reason for this is that asciidoc
+becomes syntactically confused if inclusion directives collide with
+its parser's idea of where the next section header should be.  We use
+the build system to patch around this problem.
+
 === Conventions for #ifdef guard names ===
 
 Parts of this code are a thicket of C preprocessor conditionals.