commit feb0a5feb64ef7e59e223caf5be77a5bef58fb3d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 14 10:29:26 2024 -0500
Commit: Fabian Greffrath <fabian@greffrath.com>
CommitDate: Wed Jul 2 08:24:12 2025 +0200
man/strife.template: Improve formatting and markup
1. Use quotation to cite other sections of the same man page.
2. Break input lines at sentence endings.
3. Set "Doom" in titlecase, not full capitals. On the Chocolate master
branch, before my changes, the former is preponderant in
documentation.
$ git grep -wc DOOM man
man/INSTALL.template:9 (all of which are `#if` or `#ifdef`)
man/strife.template:2
$ git grep -wc Doom man
man/INSTALL.template:16
man/Makefile.am:2
man/bash-completion/doom.template.in:1
man/docgen:4
man/doom.template:5
man/heretic.template:1
man/hexen.template:1
man/iwad_paths.man:5
man/server.template:1
man/setup.template:1
man/strife.template:5
man/wikipages:1
4. Use man(7) font style macros, not asterisks, for typographical
emphasis. Man pages and Markdown employ different conventions.
5. Set the C standard library symbol "NULL" in italics, not roman.
groff_man_style(7):
Article titles and brief runs of literal text, such as references
to individual characters or short strings, including section and
subsection headings of man pages, are suitable objects for
quotation; see the \(lq, \(rq, \(oq, and \(cq escape sequences in
subsection “Portability” below.
...
\(lq
\(rq Left and right double quotation marks. Use these for paired
directional double quotes, “like this”.
roff(7):
A roff formatter attempts to detect boundaries between sentences,
and supplies additional inter‐sentence space between them. It
flags certain characters (normally “!”, “?”, and “.”) as
potentially ending a sentence. When the formatter encounters one
of these end‐of‐sentence characters at the end of an input line, or
one of them is followed by two (unescaped) spaces on the same input
line, it appends an inter‐word space followed by an inter‐sentence
space in the output. ...
Input conventions
Since troff fills text automatically, it is common practice in the
roff language to avoid visual composition of text in input files:
the esthetic appeal of the formatted output is what matters.
Therefore, roff input should be arranged such that it is easy for
authors and maintainers to compose and develop the document,
understand the syntax of roff requests, macro calls, and
preprocessor languages used, and predict the behavior of the
formatter. Several traditions have accrued in service of these
goals.
• Follow sentence endings in the input with newlines to ease their
recognition. It is frequently convenient to end text lines
after colons and semicolons as well, as these typically precede
independent clauses. Consider doing so after commas; they often
occur in lists that become easy to scan when itemized by line,
or constitute supplements to the sentence that are added,
deleted, or updated to clarify it. Parenthetical and quoted
phrases are also good candidates for placement on text lines by
themselves.
---
man/strife.template | 68 ++++++++++++++++++++++++++++++-----------------------
1 file changed, 39 insertions(+), 29 deletions(-)
diff --git a/man/strife.template b/man/strife.template
index 75ca91b4..51defaec 100644
--- a/man/strife.template
+++ b/man/strife.template
@@ -11,7 +11,8 @@ Rogue Entertainment's
.IR "Strife: Quest for the Sigil" .
It was created through
more than two years of reverse engineering effort with the blessings
-of the original programmers of the game (see the section HISTORY below).
+of the original programmers of the game;
+see section \(lqHISTORY\(rq below.
@content
.SH IWAD SEARCH PATHS
@include iwad_paths.man
@@ -34,38 +35,47 @@ See \fB@PROGRAM_SPREFIX@\-strife.cfg\fR(5).
\fB@PROGRAM_SPREFIX@\-server\fR(6),
\fB@PROGRAM_SPREFIX@\-setup\fR(6)
.SH HISTORY
-The source code for Strife was lost, which means, unlike the code for all the
-other commercial DOOM-engine games, it cannot be released. The only access we
-have to the code is the binary executable file. Reverse engineering tools
-were employed to disassemble and decompile the executables, which were cross-
-referenced against the Linux DOOM and DOS Heretic sources and painstakingly
-combed over multiple times, instruction-by-instruction, to ensure that the
-resulting Chocolate-Doom-based executable is as close as possible to the
-original.
+The source code for Strife was lost, which means, unlike the code for
+all the other commercial games using the Doom engine, it cannot be
+released.
+The only access we have to the code is the binary executable file.
+Reverse engineering tools were employed to disassemble and decompile the
+executables, which were cross-referenced against the Linux Doom and
+DOS Heretic sources and painstakingly combed over multiple times,
+instruction by instruction, to ensure that the resulting
+Chocolate-Doom-based executable is as close as possible to the original.
.SH LEGALITY
-Reverse engineering is a protected activity so long as the original code is
-not used directly in the product. Due to the vast amount of information lost
-through the process of compilation, and the need to refactor large portions
-of code in order to eliminate non-portable idioms or to adapt them properly to
-Chocolate Doom's framework, the resulting code behaves the same, but is not
-the *same* code.
+Reverse engineering is a protected activity so long as the original code
+is not used directly in the product.
+Due to the vast amount of information lost through the process of
+compilation, and the need to refactor large portions of code in order to
+eliminate non-portable idioms or to adapt them properly to Chocolate
+Doom's framework, the resulting code behaves the same, but is not the
+.I same
+code.
.PP
-In addition, James Monroe and John Carmack have both stated that they have no
-objections to the project. Because they are the original authors of the code,
-and neither Rogue nor their publisher, Velocity, Inc., exist any longer as
-legal entities, this is effectively legal permission.
+In addition, James Monroe and John Carmack have both stated that they
+have no objections to the project.
+Because they are the original authors of the code, and neither Rogue nor
+their publisher, Velocity, Inc., exist any longer as legal entities,
+this is effectively legal permission.
.SH BUGS
-@PACKAGE_SHORTNAME@ Strife is almost, but not entirely perfect, in recreating the
-behavior of Vanilla Strife. Help us by reporting any discrepancies you
-might notice between this executable and the vanilla DOS program.
+@PACKAGE_SHORTNAME@ Strife is almost, but not entirely perfect, in
+recreating the behavior of Vanilla Strife.
+Help us by reporting any discrepancies you might notice between this
+executable and the vanilla DOS program.
.PP
-However, do *not* report any glitch that you can replicate in the vanilla EXE
-as a bug. The point of @PACKAGE_SHORTNAME@ Strife, like Chocolate Doom before it, is to
-be as bug-compatible with the original game as possible. Also be aware that
-some glitches are impossible to compatibly recreate, and wherever this is the
-case, @PACKAGE_SHORTNAME@ Strife has erred on the side of not crashing the program,
-for example by initializing pointers to NULL rather than using them without
-setting a value first.
+However, do
+.I not
+report any glitch that you can replicate in the vanilla EXE as a bug.
+The point of @PACKAGE_SHORTNAME@ Strife, like Chocolate Doom before it,
+is to be as bug-compatible with the original game as possible.
+Also be aware that some glitches are impossible to compatibly recreate,
+and wherever this is the case, @PACKAGE_SHORTNAME@ Strife has erred on
+the side of not crashing the program, for example by initializing
+pointers to
+.I NULL
+rather than using them without setting a value first.
.SH AUTHORS
Chocolate Strife is part of the Chocolate Doom project.
It was reverse engineered from the DOS versions of Strife by James Haley