,MOD
- R 44X (11 April 1983) <PSL.NMODE-DOC>NM-BUGS.ibm
PLA 97_LAS 80 0_FIR 2_INT 1 6.0_TYP 160 163 162 193_INP 12 101_MAR 2
,END
,PRO
201 OUT 160_202 OUT 163_203 OUT 162_204 OUT 193
205 INP 12 101_206 INP 12 102
,END
,DEFINE
 UNIT SPACE
 FUNCTION
,END

          201/NMODE Manual (Correcting Mistakes and NMODE Problems)          Page 23-1


          202/23.  Correcting Mistakes and NMODE Problems

          201/If you type an NMODE command you did not intend, the results are often
          mysterious.  This chapter tells what you can do to cancel your mistake or
          recover from a mysterious situation.  NMODE bugs and system crashes are
          also considered.

          202/23.1  Quitting and Aborting

                  201/C-G    Quit.  Cancel partially typed command.

            There  are  two  ways  of  cancelling  commands  which  are  not  finished
          executing: 202/quitting 201/with C-G (203/nmode-abort-command201/), and 202/aborting 201/with C-C
          on Twenex or STOP on the hp9836.  Quitting is cancelling a partially typed
          command.   Aborting is cancelling a command which is already running.
          Aborting generally doesn't allow a  clean  re-entry  into  the  old  NMODE
          environment so it is generally not recommended.

            Quitting with C-G is used for getting rid of a partially typed command, or
          a numeric argument that you don't want.  Quitting an incremental search does
          special things documented under searching; in general, it may take two
          successive C-G's to get out of a search.

          202/23.1.1  Garbage on the Screen

            201/If the data on the screen looks wrong, it could be due to line noise on
          input or output, a bug in the terminal, a bug in NMODE redisplay, or a bug
          in an NMODE command.  To find out whether there is really anything wrong
          with your text, the first thing to do is type C-L.  This is a command to
          clear the screen and redisplay it.   Often this will display the text you
          expected.  Think of it as getting an opinion from another doctor.

          202/23.2  Reporting Bugs

            201/Sometimes you will encounter a bug in NMODE.  To get it fixed, you must
          report it.  It is your duty to do so; but you must know when to do so and
          how if it is to be constructive.

          202/23.2.1  When Is There a Bug

            201/If NMODE executes an illegal instruction, or dies with an operating system
          error message that indicates a problem in the program (as opposed to "disk
          full"), then it probably is a bug.

            We say "probably" because you can also cause these errors yourself if you
          execute your own code or modify NMODE by redefining its functions or
          changing its variables.

            If NMODE updates the display in a way that does not correspond to what is
          in the buffer, then it is probably a bug.  If a command seems to do the
          wrong thing but the problem is gone if you type C-L, then it is a case of
          incorrect display updating.
          201/Page 23-2                              NMODE Manual (When Is There a Bug)


            Taking forever to complete a command can be a bug, but you must make
          certain that it was really NMODE's fault.  Some commands simply take a long
          time.

            If a command you are familiar with causes an NMODE error message in a
          case where its usual definition ought to be reasonable, it is probably a bug.

            If a command does the wrong thing, that is a bug.  But be sure you know
          for certain what it ought to have done.   If you aren't familiar with the
          command, or don't know for certain how the command is supposed to work,
          then it might actually be working right.  Rather than jumping to conclusions,
          show the problem to someone who knows for certain.

            Finally, a command's intended definition may not be best for editing with.
          This is a very important sort of problem, but it is also a matter of judgment.
          Also, it is easy to come to such a conclusion out of ignorance of some of the
          existing features.  It is probably best not to complain about such a problem
          until you have checked the documentation in the usual ways, feel confident
          that you understand it, and know for certain that what you want is not
          available.  If you feel confused about the documentation instead, then you
          don't have grounds for an opinion about whether the command's definition is
          optimal.  Make sure you read it through and check the index or the menus
          for all references to subjects you don't fully understand.  If you have done
          this diligently and are still confused, or if you finally understand but think
          you could have said it better, then you have a constructive complaint to make
          203/about the documentation201/.  It is just as important to report documentation
          bugs as program bugs.

          202/23.2.2  How to Report a Bug

            201/When you decide that there is a bug, it is important to report it and to
          report it in a way which is useful.   What is most useful is an exact
          description of what commands you type, starting with a fresh NMODE just
          loaded, until the problem happens.  Send the bug report to the author (see
          the preface for the address).

            The most important principle in reporting a bug is to report 203/facts201/, not
          hypotheses or conditions.  It is always easier to report the facts, but people
          seem to prefer to strain to think up explanations and report them instead.  If
          the explanations are based on guesses about how NMODE is implemented, they
          will be useless; we will have to try to figure out what the facts must have
          been to lead to such speculations.  Sometimes this is impossible.  But in any
          case, it is unnecessary work for us.

            For example, suppose that you type C-X C-V <GLORP>BAZ.UGH<CR>,
          visiting a file which (you know) happens to be rather large, and NMODE
          prints out "I feel pretty today".  The best way to report the bug is with a
          sentence like the preceding one, because it gives all the facts and nothing
          but the facts.

            Do not assume that the problem is due to the size of the file and say "When
          I visit a large file, NMODE prints out 'I feel pretty today'".  This is what we
          mean by "guessing explanations".  The problem is just as likely to be due to
          201/NMODE Manual (How to Report a Bug)                              Page 23-3


          the fact that there is a "Z" in the filename.  If this is so, then when we got
          your report, we would try out the problem with some "big file", probably
          with no "Z" in its name, and not find anything wrong.  There is no way in
          the world that we could guess that we should try visiting a file with a "Z" in
          its name.

            Alternatively, the problem might be due to the fact that the file starts with
          exactly 25 spaces.  For this reason, you should make sure that you don't
          change the file until we have looked at it.  Suppose the problem only occurs
          when you have typed the C-X C-A command previously?  This is why we ask
          you to give the exact sequence of characters you typed since loading the
          NMODE.

            You should not even say "visit the file ..." instead of "C-X C-V" unless
          you 203/know 201/that it makes no difference which visiting command is used.
          Similarly, rather than saying "if I have three characters on the line", say
          "after I type <CR>A B C<CR>C-P", if that is the way you entered the text.
          In addition, you should say what mode you are in.

            If the bug occurred in a customized NMODE, it is helpful to try to
          reproduce the bug in a more standard NMODE.  It is best if you can make
          the problem happen in a completely standard NMODE.  If the problem does
          203/not 201/occur in a standard NMODE, it is very important to report that fact,
          because otherwise we will try to debug it in a standard NMODE, not find the
          problem, and give up.  If the problem does depend on an init file, then you
          should make sure it is not a bug in the init file by complaining to the person
          who wrote the file, first.  He should check over his code, and verify the
          definitions of the PSL commands he is using.  Then if he verifies that the
          bug is in NMODE he should report it.   We cannot be responsible for
          maintaining users' init files; we might not even be able to tell what they are
          supposed to do.

            If you can tell us a way to cause the problem without reading in any files,
          please do so.  This makes it much easier to debug.  If you do need files,
          make sure you arrange for us to see their exact contents.  For example, it
          can often matter whether there are spaces at the ends of lines, or a line
          separator after the last line in the buffer (nothing ought to care whether the
          last line is terminated, but tell that to the bugs).