...where available.
groff_man_style(7):
Notes
...
• When and how should I use quotation marks?
... groff, Heirloom Doctools troff, neatroff, and mandoc support
all of the special characters \[oq], \[cq], \[lq], \[rq], \[aq],
and \[dq] described in subsection “Portability” above. DWB, Plan
9, and Solaris troffs do not. Interpolating the strings \*(lq
and \*(rq portably yields directional double quotation marks, if
available, in all these formatters (though neatroff does not
supply a man macro package), but they cannot reliably be used in
macro arguments.
* Set cross reference to "nethack" man page in lowercase, because that's
the name under which it's installed, and POSIX systems are
case-sensitive.
* Refer to the "nethack" command using a man page cross reference only
on its first occurrence.
* Favor bullets over hyphens for itemized list.
* Drop explicit indentation amounts from lists. The man(7) package's
default suffices on all of Solaris 10, DWB 3.3, Plan 9, Heirloom
Doctools, and GNU *roffs, and on mandoc(1).
* Use tagged paragraphs to set synopses of syntax productions used in
the documented file format.
* Drop inset (indentation) of itemized and tagged lists; the bullets
make the structure clear, and (with the foregoing change) this way the
paragraphs align.
...on typesetters and UTF-8 terminals.
groff_man_style(7):
Portability
...
Several special characters are also widely portable. Except for
\-, \[em], and \[ga], AT&T troff did not consistently define the
characters listed below, but its descendants, like DWB, Plan 9, or
Solaris troff, can be made to support them by defining them in font
description files, making them aliases of existing glyphs if
necessary; see groff_font(5). groff’s extended notation for
special characters, \[xx], is also supported by mandoc(1), Heirloom
Doctools troff, and neatroff, but not DWB, Plan 9, or Solaris
troffs.
...
\[ha] Basic Latin circumflex accent (“hat”). Some output devices
format “^” as U+02C6 (modifier letter circumflex accent).
Notes
Some tips on composing and troubleshooting your man pages follow.
...
• Escape sequences of the form \[xx] don’t format correctly.
The \[xx] special character escape sequence is a GNU troff
extension also supported by mandoc, Heirloom Doctools troff, and
neatroff. DWB, Plan 9, and Solaris troffs don’t implement it.
If your man page requires portability to these formatters, spell
such escape sequences as “\(xx”; no closing parenthesis is used.
xx must be exactly two characters; groff_char(7) lists portable
special character identifiers.
Paragraphing macros in *roff systems generally break the output line,
and the same is true of all of man(7)'s paragraphing macros.
groff_man(7):
Paragraphing macros
These macros break the output line. An ordinary paragraph (P)
indents all output lines by the same amount. A hanging paragraph
(HP) is a cosmetic variant of P with a hanging indent. Definition
lists frequently occur in man pages; these can be set as tagged
paragraphs, which have one (TP) or more (TQ) leading tags followed
by a paragraph that has an additional indentation.
NetHack's man pages already preponderantly use man(7) `IR` macro for
this purpose. Align outliers.
The "SEE ALSO" section of doc/mn.7 is a partial exception. While the
rest of the document sets cross-referenced man page topics in italics,
this section of the page does not. It seems likely that this decision
was made in deliberate imitation of Seventh Edition Unix manuals (1979)
or their descendants in USG/USL and BSD Unices. That feature of the
Unix man pages, however, was not deliberate per Doug McIlroy, the author
of the man(7) macros and editor of Volume 1 of the Seventh Edition Unix
Programmer's Manual, per his communication on the groff mailing list.
But NetHack has a policy of not modifying Matt Bishop's "mn" macro
file or its man page, so I leave that exception in place.
References:
https://lists.gnu.org/archive/html/groff/2021-08/msg00023.htmlhttps://lists.gnu.org/archive/html/groff/2021-08/msg00040.htmlhttps://github.com/NetHack/NetHack/pull/977#issuecomment-1424996578
Sectioning and paragraphing macros always break the output line.
(Sub)sectioning macros always set text after the heading as a paragraph.
Fixes:
$ mandoc -T lint doc/*.[67] # output edited
doc/makedefs.6:49:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:367:2: WARNING: skipping paragraph macro: br after PP
doc/nethack.6:365:2: WARNING: skipping paragraph macro: PP empty
doc/nethack.6:157:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:431:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:673:2: WARNING: skipping paragraph macro: PP after SH
doc/nethack.6:676:2: WARNING: skipping paragraph macro: PP after SH
doc/recover.6:29:2: WARNING: skipping paragraph macro: PP after SH
doc/recover.6:125:2: WARNING: skipping paragraph macro: PP after SH
doc/recover.6:141:2: WARNING: skipping paragraph macro: PP after SH
doc/mnh.7:23:2: WARNING: skipping paragraph macro: PP after SH
doc/mnh.7:46:2: WARNING: skipping paragraph macro: PP after SH
Not a serious issue in my opinion, but worth fixing. DWB does not
misrender the document, and the "stack" referred to is not the runtime
stack employed by the operating system, but one in the *roff language
runtime.
The diagnostic appears to be spurious in this case, but it isn't always.
https://github.com/n-t-roff/DWB3.3/issues/10
groff_man_style(7):
• Option dashes are specified with the \- escape sequence; this is
an important practice to make them clearly visible and to
facilitate copy‐and‐paste from the rendered man page to a shell
prompt or text file.
...
\- Minus sign. \- produces the basic Latin hyphen‐minus
(U+002D) specifying Unix command‐line options and frequently
used in file names. “-” is a hyphen in roff; some output
devices format it as U+2010 (hyphen).
...pacifying a warning from the forthcoming groff 1.25.
Fixes:
troff:doc/dlb.6:159: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:53: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:55: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:58: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:153: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:159: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:166: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:222: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:245: warning: end of sentence detected before end of text line [-w style]
troff:doc/makedefs.6:279: warning: end of sentence detected before end of text line [-w style]
troff:doc/mnh.7:30: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:225: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:226: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:230: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:234: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:236: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:524: warning: end of sentence detected before end of text line [-w style]
troff:doc/nethack.6:577: warning: end of sentence detected before end of text line [-w style]
troff:doc/recover.6:155: warning: end of sentence detected before end of text line [-w style]
Starting a text line with leading spaces causes a break when filling.
Usually this is not what is intended.
Fixes:
$ nroff -ww -z -rCHECKSTYLE=4 -man doc/*.[67]
an.tmac:doc/makedefs.6:102: style: 1 leading space(s) on input line
To update, run "perl DEVEL/nhgitset.pl"
Fixes:
- "nhcommit -a" has been fixed
- NHDT was hardwired in places
- no longer complain about a missing dat directory outside of the
NetHack source tree
- make update of gitinfo atomic
- Replace some hardwired directory separators with OS-dependent constructs
Backwards Incompatibilities:
- NH_DATESUB's DATE() is now Date() to match the other variables
- MSYS2 requires an additional Perl package - the MSYS2 docs have
been updated
New Help System:
- git nhhelp
This command mirrors "git help" for nh* commands.
- See git nhhelp nhsub for general help on substitution variables
New Substitution Variables:
-Brev()
An aBREViation of $PREFIX-Branch$:$PREFIX-Revision$ - this
may help get line length under control in file headers.
-Assert(TYPE=VALUE)
If TYPE does not match VALUE, do not substitute on this line.
TYPE P checks VALUE against nethack.substprefix
-Project(arg)
Returns nethack.projectname if there is no arg and an uppercase
version if arg is uc.
Other New Features:
- Add nethack.projectname
- Documentation updates - see "git nhhelp nhsub"
- On checkout or merge of a branch, check for nhgitset version updates
and provide an optional message to the user.
- Move NH_DATESUB substitutions here from cron job to keep dates in sync
- PREFIX-* keywords now available in NH_DATESUB templates
- Support use of nhgitset.pl from a different repo; note that update
checks will be dependent on keeping the original source repo up-to-date
and in the same location.
This may be useful for some build environments to avoid parallel make
issues, and artificially-concocted order dependencies, leaving the ordering
up to that specified in the Makefile.
The related makedefs options are now:
‐s Generate the bogusmon , engrave and epitaph files.
‐1 Generate the epitaph file.
‐2 Generate the engrave file.
‐3 Generate the bogusmon file.
Also resolves an existing issue encountered in doc/makedefs.6 where "and epitaphfiles"
was being produced in the result.
When calling panic() or impossible(), create the option
of opening a browser window with most of the fields
already populated. Code for MacOS and linux is included;
other ports are affected by argument change to early_init
which are done but not tested.
To enable, define CRASHREPORT in config.h and set
CRASHREPORTURL in sysconf to (for the moment at least)
http[s]://www.nethack.org/common/contactcr.html
Adds --grep-defined option to makedefs for Makefiles.
Adds "bid" (binary identifier), an MD4 of the main nethack
binary. This is ONLY for helping (in the future) contact.html
to set the "NetHack from" field automatically for our own
binaries. This can be faked, but the user can lie so nothing
lost. There's nothing magic about MD4; other ports can use
anything that prodcues a long apparently random string we can
match against.
- new option --bidshow for us to get the MD4 of a
released binary so I can add it to the website.
Only available in wizard mode and not in nethack.6.
- typo macos -> macosx in hints file
No support for packaging builds as I'm not sure what that
would look like.
Adds a javascript helper for MacOS.
Adds a lua helper for linux (and builds and installs
nhlua).
Update makdefs source and its man page.
Remove all mentions of the vision table files from:
o .gitattributes
o .gitignore
o Files
o Cross-compiling
Add a brief note in the fixes file.
Incorporate some git information into NetHack so that it
is potentially visible to a player. That's useful when
collecting details about the version that they are
running and, if the gitinfo is present, it can tie the
code to a specific git commit in the repository.
This modifies 'makedefs -v' to check for the presence of a data file
called dat/gitinfo.txt and if it is there, parse out its
contents, then write additional lines to include/date.h beyond
what 'makedefs -v' was previously putting in there, similar to
this sample:
#define NETHACK_GIT_SHA "0c84e564c78e2024e562d39539376ce2e21eec8e"
#define NETHACK_GIT_BRANCH "NetHack-3.6.0"
The contents of an appropriate dat/gitinfo.txt are as follows,
and trailing/leading whitespace is not significant:
githash = 0c84e564c78e2024e562d39539376ce2e21eec8e
gitbranch = NetHack-3.6.0
It also adjusts the contents of the 'v' version information to
include the additional git info when available.
Also adds some hooks DEVEL/hooksdir and a perl file to DEVEL
for simplifying and automating the deposit of dat/gitinfo.txt
so that it generally reflects the most current git commit.
DEVEL/gitinfo.pl can be used to build dat/gitinfo.txt at any
time without doing a commit, merge, or checkout.
perl DEVEL/gitinfo.pl
command line --version and -version support
To complement the extra information being provided in the
version by the 'v' command, this also adds support for the
following new command line arguments:
--version
-version Output the NetHack version string then exit.
--version:paste Output the NetHack version string and also copy it to
-version:paste the platform's paste buffer for insertion somewhere,
then exit.
If the paste variation of -version is requested on a platform that
hasn't incorporated any support for the capability, it will deliver
the version info then an error message, prior to exiting.
To support the extended -version:paste variation, a port needs to:
- provide a port-specific routine to perform
the paste buffer copy in a port code file.
- #define RUNTIME_PASTEBUF_SUPPORT in the include/portconf.h header file.
--skeleton--
void port_insert_pastebuf(buf)
char *buf;
{
/* insert code to copy the version info from buf into
platform's paste buffer in a supported way */
}
macosx and Windows have both added support for RUNTIME_PASTEBUF_SUPPORT
Add a man page for makedefs so mdgrep is documented better.
Add missing INSURANCE to mdgrep.h. (yes, LIFE leaks in as well)
Add makefile bits to build makedefs.txt.
Pass dungeon.def through mdgrep internally to makedefs - this will make
it possible to commit the LIFE patch and have config.h actually turn it
all the way off (by skipping bigrm-6).
G. Branden Robinson