Define the documentation build in docs/CMakeLists.txt and collect the prose

The Doxygen configuration, the page list, and the docs target live in
docs/, and the written documents live in docs/PROSE/, leaving the
top-level file with the output paths and the add_subdirectory call.

The subdirectory is given its own binary directory so that CMake's
scaffolding stays out of the documentation output, which holds pdf/ and
html/ and nothing else.

Paths both files need are set once above the call: the child's output
and cleanup and the parent's clean rule refer to the same variables.
This commit is contained in:
2026-08-16 00:37:33 -04:00
parent 64839e3933
commit 3b7091dc4b
10 changed files with 118 additions and 99 deletions

60
docs/PROSE/STYLE.md Normal file
View File

@@ -0,0 +1,60 @@
# Code Style Guide {#style}
Allman, with four modifications.
## Base
Allman: each brace on its own line, and the body indented one level inside them.
## Modification: Opening Braces Stay on the Line That Opens the Scope
An opening brace does not move to a line of its own. It stays on the line of the function definition, control statement, namespace, `extern "C"` block, struct, or enum that opens the scope. The closing brace keeps its own line.
## Modification: Every Scope Indents
Allman indents the body of a scope, and here that applies to every scope without exception — namespaces and `extern "C"` blocks included, not only functions and control statements. One level is four spaces.
```
namespace dpm_core {
bool parse_version(const char* s, long out[3]) {
if (!s || !*s) {
return false;
}
return true;
}
} // namespace dpm_core
```
## Modification: `} else {` Stays on One Line
Allman would put the closing brace, the `else`, and the opening brace on three lines. They stay on one.
```
if (level <= DPM_LOG_WARN) {
std::fprintf(stderr, "%s: %s\n", level_name(level), message);
} else {
std::fprintf(stdout, "%s\n", message);
}
```
## Modification: A Short Guarded Statement May Occupy One Line
Where a condition guards a single short statement, the braces and the statement stay on the line with the condition. The braces are still written.
```
if (v == "FATAL") { return DPM_LOG_FATAL; }
if (v == "ERROR") { return DPM_LOG_ERROR; }
if (v == "WARN") { return DPM_LOG_WARN; }
```
## Modification: A Closing Brace Names the Scope It Ends
Where the opening line is far enough above to be off screen — a namespace or an `extern "C"` block — the closing brace carries a comment naming what it closes.
```
} // namespace dpm_core
```
```
} /* extern "C" */
```