[NH5] Update files in DEVEL directory and subdirectories

DEVEL/Developer.txt

@@ -4,7 +4,7 @@
  |___/\___|\_/\___|_\___/ .__/\___|_|
                         |_|
 
-# NetHack 3.6  Developer.txt       $NHDT-Date: 1524689668 2018/04/25 20:54:28 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.13 $
+# NetHack 3.7  Developer.txt       $NHDT-Date: 1596498265 2020/08/03 23:44:25 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.19 $
 # Copyright (c) 2015 by Kenneth Lorber, Kensington, Maryland
 # NetHack may be freely redistributed.  See license for details.
 
@@ -35,8 +35,7 @@ while.  Please do not send save files, binary screen grabs, or other large
 things.
 ------------------------------------------------------------------------------
 2. git repositories
-A public repository of the latest NetHack code that we've made 
-available can be obtained via git from either of two locations:
+The public NetHack git repository is available (read-only) at:
     https://github.com/NetHack/NetHack
      or
     https://sourceforge.net/p/nethack/NetHack/
@@ -59,18 +58,36 @@ NOTE: These instructions assume you are on the default branch; this _is_
 NOTE: The following instructions require perl.  If you do not have perl on
       your system, please install it before proceeding.
 
+NOTE: More information on nhgitset.pl is available before installation via:
+           perldoc DEVEL/nhgitset.pl
+      After installation, the same information is available with:
+           git nhhelp nhgitset
+
 A. If you have never set up git on this machine before:
    (This assumes you will only be using git for NetHack.  If you are going to
    use it for other projects as well, think before you type.)
 	Tell git what name (or nickname) and email address to use for you:
 		git config --global user.name "MY NAME"
 		git config --global user.email USER@EXAMPLE.COM
    You probably want to set up a credential cache.
-	Mac OS X:
-		git config --global credential.helper osxkeychain
-	Windows:
-		git config --global credential.helper store
-XXX linux
+	macOS (10 or greater):
+	    git config --global credential.helper osxkeychain
+	Linux:
+	    (This will vary by distribution.)
+	    cd /usr/share/doc/git/contrib/credential/libsecret
+	    sudo apt-get install libglib-2.0-dev libsecret-1-dev
+	    sudo make
+	    git config --global credential.helper `pwd`/git-credential-libsecret
+		OR
+	    sudo yum install git-credential-libsecret
+	    git config --global credential.helper /usr/libexec/git-core/git-credential-libsecret
+	Windows: (The following three assume that Git for Windows is already installed on
+	          the underlying Windows system https://git-scm.com/download/win):
+	    git config --global credential.helper store
+          MSYS2 UCRT64 bash shell:
+            git config --global credential.helper "/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
+	  Windows Subsystem for Linux 2 (WSL2) bash shell:
+            git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
 B. Specify the prefix for variable substitution:
    (This assumes you are not a member of DevTeam or any variant's development
    team.  If you are, this may be wrong.  Look for more specific documentation.
@@ -80,10 +97,11 @@ B. Specify the prefix for variable substitution:
 	tree you cloned from git.  I use ~/nethack/GITADDDIR; for that base,
 	create the needed directories and edit the file:
 		~/nethack/GITADDDIR/DOTGIT/PRE
-	Put this in it (if your OS is not Unix-like you may need to change
-	the first line):
+	Put this in it, adapting it to your variant (if your OS is not Unix-like
+	you may need to change the first line):
 		#!/bin/sh
 		git config nethack.substprefix MINE
+		git config nethack.projectname MineHack
 	Now make it executable:
 		chmod +x ~/nethack/GITADDDIR/DOTGIT/PRE
 C. Configure the repository:
@@ -157,8 +175,8 @@ A. Introduction
    The PREFIX is the value in the git config variable nethack.substprefix.
    VARNAME is one of:
 	Date
-	Branch (experimental)
-	Revision (experimental)
+	Branch
+	Revision
    other names will give a warning.
 
 B. Enabling variable expansion

DEVEL/VERSION

@@ -0,0 +1,4 @@
+5
+Please see "git log DEVEL" for previous changes.
+Make documentation of nhgitset.pl easier to find and
+find out about.

DEVEL/code_features.txt

@@ -1,4 +1,4 @@
-# NetHack 3.6  code_features.txt $NHDT-Date: 1524689669 2018/04/25 20:54:29 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.3 $
+# NetHack 5.0  code_features.txt $NHDT-Date: 1596498264 2020/08/03 23:44:24 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.6 $
 # Copyright (c) 2015 by Michael Allison
 # NetHack may be freely redistributed.  See license for details.
 
@@ -101,6 +101,23 @@ engine are incompatible.
 Additional regular expression implementations can be written. The full
 interface documentation is in sys/share/posixregex.c
 
+===========================================================
+HEADER FILE NOTES
+
+hack.h defines values that are available to all NetHack source files,
+contains enums for use in all NetHack source files, and contains a
+number of struct definitions for use in all NetHack source files.
+hack.h does not contain variable declarations or variable definitions.
+
+decl.h and decl.c are related: decl.h contains the extern declarations
+for variables that are defined in decl.c. These variables are global
+and available to all NetHack source files.
+decl.c variable definitions are generally laid out in much the same
+order as their corresponding declarations in decl.h.
+
+A new header file cstd.h was added to coincide with 5.0's switch to
+C99. It contains calls to some C99 standard header files.
+
 =================== NEXT FEATURE ==========================
 
 

DEVEL/code_style.txt

@@ -1,4 +1,4 @@
-# NetHack 3.6  code_style.txt       $NHDT-Date: 1524689669 2018/04/25 20:54:29 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.2 $
+# NetHack 3.7  code_style.txt       $NHDT-Date: 1694890786 2023/09/16 18:59:46 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.8 $
 # Copyright (c) 2015 by Derek S. Ray
 # NetHack may be freely redistributed.  See license for details.
 
@@ -13,7 +13,8 @@ should be styled in keeping with C.
 The code base in C files was, close to the 3.6 release, reformatted using a
 version of the clang-format tool patched to support K&R-style argument
 declarations. Due to some incompatibilities, the patch is not publicly
-available and clang-format is not expected to be regularly used.
+available and clang-format is not expected to be regularly used.  Since then,
+function declarations and definitions have been switched to ANSI.
 
 Developers should do their best to adhere to the coding style to promote
 legible, easy-to-edit code. Legibility is paramount, so in some cases, it may
@@ -44,17 +45,43 @@ possible:
 Single blank lines should be used wherever convenient to improve readability.
 
 Functions and Control Statements
--------------------------------
+--------------------------------
 
 For a function definition, the return type, declarator, and opening brace
-should each appear on a line of their own. Arguments are never declared in the
-function declarator, but are declared, unintended, K&R-style before the
-opening brace:
+should each appear on a line of their own. Arguments are defined in the following
+parenthesis, per ANSI.  There are two general styles.  One with no comments, where
+arguments are added one after another, with a wrap aligning to the first argument
+if there is an overflow.
 
     void
-    foo(i, c)
-    int i;
-    char c;
+    foo(int i, char c)
+    {
+        /* function body */
+    }
+
+    void
+    long_function_name(int first_arg, struct long_name *second_arg,
+                       int third_arg, int forth_arg)
+    {
+        /* function body */
+    }
+
+Alternatively, arguments can be one per line if they are commented:
+
+    void
+    long_function_name(int first_arg,                /* main operation */
+                       struct long_name *second_arg, /* control details */
+                       int third_arg,                /* local conditions - if
+                                                        they apply */
+                       int forth_arg)                /* remote conditions */
+    {
+        /* function body */
+    }
+
+If the function takes no parameters:
+
+    int
+    long_function_name(void)
     {
         /* function body */
     }
@@ -136,6 +163,26 @@ wrapped in an additional set of parentheses for clarity:
         /* body */
     }
 
+Variable names to avoid
+-----------------------
+
+    near, far    Some compilers and cross-compilers that target old
+                 processors with segmented architectures may treat
+                 those as keywords. It is safest to just avoid them.
+
+    NEARDATA     Some data is marked with this define; the Amiga port uses
+                 it to mark data items to be used with a short addressing mode.
+                 You don't need to use this.
+
+static vs staticfn
+------------------
+
+The staticfn macro evaluates to either "static" or to nothing (see config.h).
+If possible, functions in src/*.c that would otherwise be marked static should
+be marked staticfn so platforms that do not name static functions in their
+stack traces can be forced to do so; this means function names cannot be
+reused.  Never use staticfn with data.
+
 Spaces in Expressions
 ---------------------
 
@@ -149,6 +196,63 @@ immediately inside a pair of parentheses:
         /* body */
     }
 
+Casts and sizeof
+----------------
+
+Casts should separate the cast operator and its expression with a space:
+    '(char *) str'
+'sizeof (type)' requires the parentheses.  'sizeof expression' does not;
+using them is not wrong but omitting them avoids some visual clutter.
+Using them without the separating space gives the false impression of a
+function call or macro-with-argument(s) expansion; 'sizeof' is an operator
+and the parentheses required for '(type)' are to treat it like a cast.
+
+Comments
+--------
+
+Some block comments are undecorated, just split into reasonable width lines:
+    /* this is
+       a comment */
+They usually don't include sentence punctuation.
+
+Others are more elaborate:
+    /*
+     * This is
+     * another comment.
+     */
+This style is usually used with sentence punctuation, particularly if they
+contain more than one sentence.
+
+End-of-line comments which need to span lines
+    somecode(); /* this comment
+                 * is ok */
+should start every continuation line with an asterisk, otherwise clang-format
+would convert them into a block comment
+    othercode(); /* this comment
+                    should be avoided */
+because it would be converted into
+    othercode();
+    /* this comment
+       should be avoided */
+if another bulk reformatting ever gets performed.  Similarly, multiple
+comments intended to read as one
+    morecode(); /* start of comment */
+                /* more of comment  */
+                /* end of comment   */
+are deprecated because they will end up losing the indentation of the
+followup lines if reformatted.
+
+Many files end with
+    /*filename*/
+usually preceded by a blank line.  This was intended as a workaround for a
+comment--somewhere, possibly in Amiga or Atari code--that stated that some
+compiler or other didn't always process the last line of the file.  If that
+last line is a comment, nothing is lost.  The real issue almost certainly
+was source file(s) that didn't end in newline.  These days we try to force
+the final newline for every file, prior to release if not always maintained
+day-to-day.  The name at the end can still be worthwhile when editing or
+browsing multiple files.
+
 Vim Configuration
 =================
 
@@ -168,7 +272,7 @@ ensure that indentation is done correctly:
 Visual Studio Configuration
 ===========================
 
-In Visual Studio under Tools->Options->Text Editor->C/C++, you can set the 
+In Visual Studio under Tools->Options->Text Editor->C/C++, you can set the
 following options to obtain desired behavior:
 
 [Tabs]
@@ -179,8 +283,8 @@ Insert Spaces
 
 There are a number of other options under [Formatting] that should be
 checked (Indentation, New Lines, Spacing, and Wrapping), but there are so
-many entries that reproducing them here is impractical. Fortunately, the 
-options are in plain English, so walking through them with a copy of 
+many entries that reproducing them here is impractical. Fortunately, the
+options are in plain English, so walking through them with a copy of
 this Guide handy and making changes as required will suffice.
 
 Emacs Configuration
@@ -192,7 +296,6 @@ Putting the following in ~/.emacs.el is one
 (defun hook-c ()
   (setq c-set-style "k&r")
   (setq c-basic-offset 4)
-  (setq indent-tabs-mode nil)
-  (c-set-offset 'knr-argdecl-intro 0))
+  (setq indent-tabs-mode nil))
 (add-hook 'c-mode-common-hook 'hook-c)
 

DEVEL/git_recipes.txt

@@ -1,4 +1,4 @@
-# NetHack 3.6  git_recipes.txt       $NHDT-Date: 1524689669 2018/04/25 20:54:29 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.9 $
+# NetHack 3.7  git_recipes.txt       $NHDT-Date: 1596498266 2020/08/03 23:44:26 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.11 $
 # Copyright (c) 2015 by Derek S. Ray
 # NetHack may be freely redistributed.  See license for details.
 
@@ -193,6 +193,10 @@ it were a patch. Does not delete the stash from the list.
 list: Lists all of your stashed code blobs.
 
 
+=======================================
+External Links
+=======================================
+http://pcottle.github.io/learnGitBranching
 
 =======================================
 Typical workflows for common activities

DEVEL/gitinfo.pl

@@ -1,5 +1,5 @@
 #!/usr/bin/perl
-# NetHack 3.6  getinfo.pl       $NHDT-Date: 1524689669 2018/04/25 20:54:29 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.2 $
+# NetHack 3.7  getinfo.pl       $NHDT-Date: 1596498266 2020/08/03 23:44:26 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.3 $
 # Copyright (c) 2018 by Michael Allison
 # NetHack may be freely redistributed.  See license for details.
 

DEVEL/hooksdir/NHadd

@@ -1,5 +1,5 @@
 #!/usr/bin/perl
-# NetHack 3.6  NHadd       $NHDT-Date: 1524689631 2018/04/25 20:53:51 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.1 $
+# NetHack 3.7  NHadd       $NHDT-Date: 1596498406 2020/08/03 23:46:46 $  $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.2 $
 # Copyright (c) 2015 by Kenneth Lorber, Kensington, Maryland
 # NetHack may be freely redistributed.  See license for details.
 
@@ -12,11 +12,32 @@ die "Bad subcommand '$ARGV[0]'" unless $ok{$ARGV[0]};
 # we won't fail on a failure, so just system()
 $rv = system('.git/hooks/nhsub',"--$ARGV[0]",@ARGV[1..$#ARGV]);
 if($rv){
-        print "warning: nhsub failed: $rv $!\n";
+    print "warning: nhsub failed: $rv $!\n";
 }
 
 if(length $ENV{GIT_PREFIX}){
-        chdir($ENV{GIT_PREFIX}) or die "Can't chdir $ENV{GIT_PREFIX}: $!";
+    chdir($ENV{GIT_PREFIX}) or die "Can't chdir $ENV{GIT_PREFIX}: $!";
 }
 
 exec "git", @ARGV or die "Can't exec git: $!";
+
+__END__
+=for nhgitset nhadd Add file contents to the index with NetHack additions
+=for nhgitset nhcommit Record changes to the repository with NetHack additions
+
+=head1 NAME
+
+C<NHadd> - NetHack internal common code for nhadd and nhcommit
+
+=head1 SYNOPSIS
+
+C<git nhadd E<lt>git add optionsE<gt>>
+
+C<git nhcommit E<lt>git add optionsE<gt>>
+
+=head1 DESCRIPTION
+
+Run nhsub with the given arguments, then run C<git add> or C<git commit>
+with the given arguments.  Note that only basic arguments for those commands
+are understood; more complex situations may be handled by running C<git nhsub>
+manually before running C<git add> or C<git commit>.