From: nhmall <nhmall@nethack.org>
Date: Sat, 30 Jan 2021 17:18:49 +0000 (-0500)
Subject: doc/options.doc update
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=513bf63300bfd91f990e19f18db83501656cd3ab;p=nethack

doc/options.doc update
---

diff --git a/doc/options.doc b/doc/options.doc
index be189aa0e..21891041a 100644
--- a/doc/options.doc
+++ b/doc/options.doc
@@ -3,13 +3,33 @@ February 2020 in 3.7 WIP.
 
 Boolean and compound options are combined into a single allopt[] array.
 
-To add an option:
+To add an entirely new option macro type:
+
+    The current list of option macros:
+    NHOPTB (for boolean options)
+    NHOPTC (for complex options that take values beyond off/on)
+    NHOPTP (for handling a suite that all begin with a common prefix)
+
+     1. You need to add three different expansions of your macro, one for
+        the NHOPT_PROTO phase where function prototypes are generated,
+        one for the NHOPT_ENUM phase where enums are generated, and
+        NHOPT_PARSE phase.
+
+     2. If you are adding a new macro type to the current list of NHOPTB,
+        NHOPTC, or NHOPTP, don't forget to add the #undef near the bottom
+        of optlist.h, so that the macro is available for re-use during the
+        next usage phase.
+
+ To add an option:
+
+     1. Add an entry to include/optlist.h, using the NHOPTB macro for a
+       boolean on/off option, or NHOPTC macro for a compound option,
+       or NHOPTP macro if it handles an entire prefix.
+
+       The list of options is always kept in optlist.h in alphabetical order.
 
-    1. Add an entry to include/optlist.h, using the NHOPTB macro for a
-       boolean on/off option, or NHOPTC macro for a compound option. The
-       list of options is kept in alphabetical order.
        When the list of options is processed during the compile of options.c,
-       the following will be automatically generated and included in 
+       the following will be automatically generated and included in
        options.c:
 
             i) an optfn_xxxx function prototype (xxxx is the option name).
@@ -52,7 +72,7 @@ To add an option:
                     /* this is optional. If the option needs its own
                        special handling after the doset menu, do it here
                        or call a function to do it. The naming convention
-                       for such a function in options.c has been 
+                       for such a function in options.c has been
                        handler_xxxx(), but the function does not need to
                        reside in options.c */