ncurses 6.1 - patch 20181125
[ncurses.git] / doc / hackguide.doc
index a3524301681375b8ea77c43ae0185e4f45b5862a..2324322a4e67a6a539f688dd27c6b13fe2dfecff 100644 (file)
@@ -1,4 +1,3 @@
-
                           A Hacker's Guide to NCURSES
 
                                    Contents
@@ -112,7 +111,7 @@ How to Design Extensions
 
    Our conventions are simple:
     1. Maintain package-internal files in plain text. The expected viewer
-       for  them  more(1)  or  an  editor  window;  there's  no  point in
+       for  them  more(1)  or  an  editor  window;  there  is no point in
        elaborate mark-up.
     2. Mark  up manual pages in the man macros. These have to be viewable
        through traditional man(1) programs.
@@ -121,10 +120,10 @@ How to Design Extensions
    When  in  doubt,  HTMLize  a  master and use lynx(1) to generate plain
    ASCII (as we do for the announcement document).
 
-   The reason for choosing HTML is that it's (a) well-adapted for on-line
-   browsing through viewers that are everywhere; (b) more easily readable
-   as  plain  text  than most other mark-ups, if you don't have a viewer;
-   and   (c)   carries   enough  information  that  you  can  generate  a
+   The  reason  for  choosing  HTML  is  that  it is (a) well-adapted for
+   on-line  browsing through viewers that are everywhere; (b) more easily
+   readable  as plain text than most other mark-ups, if you do not have a
+   viewer;  and  (c)  carries  enough information that you can generate a
    nice-looking  printed  version  from  it.  Also,  of  course,  it make
    exporting things like the announcement document to WWW pretty trivial.
 
@@ -136,16 +135,16 @@ How to Design Extensions
              subscribe <name>@<host.domain>
 
    The  ncurses  code is maintained by a small group of volunteers. While
-   we  try  our  best to fix bugs promptly, we simply don't have a lot of
+   we  try  our best to fix bugs promptly, we simply do not have a lot of
    hours  to  spend  on  elementary  hand-holding. We rely on intelligent
    cooperation  from  our  users.  If  you  think you have found a bug in
    ncurses,  there  are some steps you can take before contacting us that
    will help get the bug fixed quickly.
 
    In  order  to  use  our bug-fixing time efficiently, we put people who
-   show us they've taken these steps at the head of our queue. This means
-   that  if you don't, you'll probably end up at the tail end and have to
-   wait a while.
+   show  us  they  have  taken these steps at the head of our queue. This
+   means that if you do not, you will probably end up at the tail end and
+   have to wait a while.
     1. Develop a recipe to reproduce the bug.
        Bugs  we  can reproduce are likely to be fixed very quickly, often
        within  days.  The most effective single thing you can do to get a
@@ -156,17 +155,17 @@ How to Design Extensions
     2. Try to reproduce the bug on a different terminal type.
        In  our experience, most of the behaviors people report as library
        bugs are actually due to subtle problems in terminal descriptions.
-       This is especially likely to be true if you're using a traditional
-       asynchronous  terminal  or PC-based terminal emulator, rather than
-       xterm or a UNIX console entry.
-       It's therefore extremely helpful if you can tell us whether or not
-       your  problem  reproduces  on other terminal types. Usually you'll
-       have  both  a  console  type  and  xterm available; please tell us
+       This  is  especially  likely  to  be  true  if  you  are  using  a
+       traditional  asynchronous  terminal or PC-based terminal emulator,
+       rather than xterm or a UNIX console entry.
+       It  is  therefore  extremely helpful if you can tell us whether or
+       not  your  problem reproduces on other terminal types. Usually you
+       will  have both a console type and xterm available; please tell us
        whether or not your bug reproduces on both.
        If  you  have  xterm  available,  it is also good to collect xterm
        reports for different window sizes. This is especially true if you
        normally  use  an unusual xterm window size -- a surprising number
-       of the bugs we've seen are either triggered or masked by these.
+       of the bugs we have seen are either triggered or masked by these.
     3. Generate and examine a trace file for the broken behavior.
        Recompile   your  program  with  the  debugging  versions  of  the
        libraries.  Insert  a  trace()  call  with  the  argument  set  to
@@ -179,35 +178,35 @@ How to Design Extensions
        tell  you  immediately if this is happening, and save you from the
        possible  embarrassment of being told that the bug is in your code
        and is your problem rather than ours.
-       If  the  virtual-screen  dumps  look correct but the bug persists,
-       it's  possible  to  crank up the trace level to give more and more
+       If  the virtual-screen dumps look correct but the bug persists, it
+       is  possible  to  crank  up  the trace level to give more and more
        information  about  the  library's  update actions and the control
        sequences  it  issues  to  perform them. The test directory of the
        distribution contains a tool for digesting these logs to make them
        less tedious to wade through.
-       Often you'll find terminfo problems at this stage by noticing that
-       the  escape  sequences put out for various capabilities are wrong.
-       If  not,  you're likely to learn enough to be able to characterize
-       any bug in the screen-update logic quite exactly.
+       Often  you  will  find terminfo problems at this stage by noticing
+       that  the  escape  sequences  put out for various capabilities are
+       wrong.  If  not,  you  are  likely  to  learn enough to be able to
+       characterize any bug in the screen-update logic quite exactly.
     4. Report details and symptoms, not just interpretations.
-       If  you  do the preceding two steps, it is very likely that you'll
+       If you do the preceding two steps, it is very likely that you will
        discover the nature of the problem yourself and be able to send us
        a  fix.  This  will  create happy feelings all around and earn you
-       good  karma for the first time you run into a bug you really can't
+       good karma for the first time you run into a bug you really cannot
        characterize and fix yourself.
-       If  you're  still  stuck,  at  least  you'll know what to tell us.
+       If  you  are  still stuck, at least you will know what to tell us.
        Remember,  we  need  details.  If  you guess about what is safe to
        leave out, you are too likely to be wrong.
        If  your  bug  produces a bad update, include a trace file. Try to
        make  the  trace  at the least voluminous level that pins down the
-       bug.  Logs  that  have  been through tracemunch are OK, it doesn't
-       throw   away   any   information  (actually  they're  better  than
-       un-munched ones because they're easier to read).
+       bug.  Logs  that  have been through tracemunch are OK, it does not
+       throw   away  any  information  (actually  they  are  better  than
+       un-munched ones because they are easier to read).
        If  your bug produces a core-dump, please include a symbolic stack
        trace generated by gdb(1) or your local equivalent.
-       Tell us about every terminal on which you've reproduced the bug --
-       and  every  terminal on which you can't. Ideally, sent us terminfo
-       sources for all of these (yours might differ from ours).
+       Tell  us about every terminal on which you have reproduced the bug
+       --  and  every  terminal  on  which  you  cannot. Ideally, sent us
+       terminfo sources for all of these (yours might differ from ours).
        Include  your ncurses version and your OS/machine type, of course!
        You can find your ncurses version in the curses.h file.
 
@@ -220,8 +219,8 @@ How to Design Extensions
    The   most  important  of  these  is  mvcur,  a  test  frame  for  the
    cursor-movement  optimization  code.  With  this  program, you can see
    directly  what  control sequences will be emitted for any given cursor
-   movement or scroll/insert/delete operations. If you think you've got a
-   bad  capability  identified,  you  can  disable it and test again. The
+   movement or scroll/insert/delete operations. If you think you have got
+   a  bad  capability  identified, you can disable it and test again. The
    program is command-driven and has on-line help.
 
    If  you think the vertical-scroll optimization is broken, or just want
@@ -229,10 +228,6 @@ How to Design Extensions
    comments  of hardscroll.c and hashmap.c; then try it out. You can also
    test the hardware-scrolling optimization separately with hardscroll.
 
-   There's   one   other   interactive  tester,  tctest,  that  exercises
-   translation  between  termcap  and  terminfo  formats.  If  you have a
-   serious need to run this, you probably belong on our development team!
-
                          A Tour of the Ncurses Library
 
 Library Overview
@@ -266,7 +261,7 @@ Library Overview
      lib_tracedmp.c lib_tracemse.c trace_buf.c
 
    It  is  rather unlikely you will ever need to change these, unless you
-   want to introduce a new debug trace level for some reasoon.
+   want to introduce a new debug trace level for some reason.
 
    There  is  another  group  of  files  that  do direct I/O via tputs(),
    computations  on  the  terminal  capabilities,  or  queries  to the OS
@@ -295,8 +290,9 @@ Library Overview
      lib_mouse.c lib_mvcur.c lib_refresh.c lib_setup.c lib_vidattr.c
 
    Most  of  the  algorithmic  complexity  in  the library lives in these
-   files.  If  there is a real bug in ncurses itself, it's probably here.
-   We'll tour some of these files in detail below (see The Engine Room).
+   files.  If there is a real bug in ncurses itself, it is probably here.
+   We  will  tour  some  of  these  files in detail below (see The Engine
+   Room).
 
    Finally,  there  is  a  group  of  files  that is actually most of the
    terminfo  compiler.  The reason this code lives in the ncurses library
@@ -305,7 +301,7 @@ Library Overview
      alloc_entry.c  captoinfo.c  comp_captab.c  comp_error.c comp_hash.c
      comp_parse.c comp_scan.c parse_entry.c read_termcap.c write_entry.c
 
-   We'll discuss these in the compiler tour.
+   We will discuss these in the compiler tour.
 
 The Engine Room
 
@@ -328,8 +324,9 @@ The Engine Room
 
    Hackers  bruised  by  previous encounters with variant select(2) calls
    may  find  the  code  in  lib_twait.c  interesting.  It deals with the
-   problem that some BSD selects don't return a reliable time-left value.
-   The function timed_wait() effectively simulates a System V select.
+   problem  that  some  BSD  selects  do  not return a reliable time-left
+   value.  The  function  timed_wait()  effectively  simulates a System V
+   select.
 
   Mouse Events
 
@@ -346,10 +343,10 @@ The Engine Room
    to  imply having the prefix somewhere in the function-key capabilities
    at terminal-type initialization.
 
-   This  kluge  only  works  because  kmous  isn't  actually  used by any
+   This  kluge  only  works  because  kmous  is  not actually used by any
    historic terminal type or curses implementation we know of. Best guess
-   is  it's  a  relic  of some forgotten experiment in-house at Bell Labs
-   that  didn't  leave  any  traces  in the publicly-distributed System V
+   is  it  is  a relic of some forgotten experiment in-house at Bell Labs
+   that  did  not  leave  any traces in the publicly-distributed System V
    terminfo  files.  If System V or XPG4 ever gets serious about using it
    again, this kluge may have to change.
 
@@ -402,7 +399,7 @@ The Engine Room
    transformations  of curscr lines to newscr lines. Its main tool is the
    routine  mvcur()  in  lib_mvcur.c.  This  routine does cursor-movement
    optimization,  attempting to get from given screen location A to given
-   location B in the fewest output characters posible.
+   location B in the fewest output characters possible.
 
    If  you  want to work on screen optimizations, you should use the fact
    that  (in  the  trace-enabled  version  of  the  library) enabling the
@@ -424,7 +421,7 @@ The Engine Room
    TYPE_REGEXP will recognize.
 
    The  configuration  code  prefers the POSIX regex facility, modeled on
-   System  V's,  but  will  settle  for  BSD  regexps if the former isn't
+   System  V's,  but  will  settle  for  BSD regexps if the former is not
    available.
 
    Historical  note:  the  panels code was written primarily to assist in
@@ -442,7 +439,7 @@ The Engine Room
 
    The  implementation  therefore  starts  with a table-driven, dual-mode
    lexical analyzer (in comp_scan.c). The lexer chooses its mode (termcap
-   or terminfo) based on the first `,' or `:' it finds in each entry. The
+   or terminfo) based on the first "," or ":" it finds in each entry. The
    lexer  does  all  the work of recognizing capability names and values;
    the  grammar above it is trivial, just "parse entries till you run out
    of file".
@@ -465,23 +462,23 @@ Translation of Non-use Capabilities
    shareable text space).
 
    Thus, adding a new capability is usually pretty trivial, just a matter
-   of  adding  one  line to the include/Caps file. We'll have more to say
+   of  adding one line to the include/Caps file. We will have more to say
    about this in the section on Source-Form Translation.
 
 Use Capability Resolution
 
-   The  background  problem  that  makes  tic tricky isn't the capability
-   translation  itself,  it's  the  resolution of use capabilities. Older
+   The  background  problem  that  makes tic tricky is not the capability
+   translation  itself,  it  is the resolution of use capabilities. Older
    versions would not handle forward use references for this reason (that
    is, a using terminal always had to follow its use target in the source
    file).  By  doing  this,  they  got  away with a simple implementation
    tactic;  compile  everything  as  it  blows by, then resolve uses from
    compiled entries.
 
-   This  won't  do  for  ncurses.  The  problem  is  that  that the whole
+   This  will  not  do  for  ncurses.  The problem is that that the whole
    compilation  process  has  to  be embeddable in the ncurses library so
    that it can be called by the startup code to translate termcap entries
-   on  the  fly.  The  embedded  version  can't  go promiscuously writing
+   on  the  fly.  The  embedded  version  cannot go promiscuously writing
    everything  it  translates  out  to  disk  --  for  one thing, it will
    typically be running with non-root permissions.
 
@@ -490,7 +487,7 @@ Use Capability Resolution
    use  resolution  in-memory  before writing everything out. This design
    has other advantages: it makes forward and back use-references equally
    easy  (so  we get the latter for free), and it makes checking for name
-   collisions before they're written out easy to do.
+   collisions before they are written out easy to do.
 
    And   this  is  exactly  how  the  embedded  version  works.  But  the
    stand-alone  user-accessible  version  of  tic  partly  reverts to the
@@ -507,8 +504,8 @@ Use Capability Resolution
    writes  out  the  referenced  entry if it has no use capabilities. The
    compiler  main loop refrains from adding the entry to the in-core list
    when  this hook fires. If some other entry later needs to reference an
-   entry  that  got  written  immediately, that's OK; the resolution code
-   will fetch it off disk when it can't find it in core.
+   entry  that  got  written immediately, that is OK; the resolution code
+   will fetch it off disk when it cannot find it in core.
 
    Name  collisions  will  still  be  detected,  just not as cleanly. The
    write_entry()   code   complains  before  overwriting  an  entry  that
@@ -530,9 +527,9 @@ Source-Form Translation
 
    The  include/Caps  file  has  a header comment describing ways you can
    specify  source  translations  for  nonstandard  capabilities  just by
-   altering the master table. It's possible to set up capability aliasing
-   or  tell  the  compiler  to  plain  ignore  a given capability without
-   writing any C code at all.
+   altering  the  master  table.  It  is  possible  to  set up capability
+   aliasing  or  tell  the  compiler  to  plain ignore a given capability
+   without writing any C code at all.
 
    For  circumstances where you need to do algorithmic translation, there
    are  functions  in  parse_entry.c called after the parse of each entry
@@ -568,14 +565,14 @@ Source-Form Translation
    Look  for  the  string  FIXME  in  source  files to tag minor bugs and
    potential problems that could use fixing.
 
-   Don't  try  to auto-detect OS features in the main body of the C code.
-   That's the job of the configuration system.
+   Do  not try to auto-detect OS features in the main body of the C code.
+   That is the job of the configuration system.
 
    To hold down complexity, do make your code data-driven. Especially, if
    you  can drive logic from a table filtered out of include/Caps, do it.
    If  you  find  you  need  to augment the data in that file in order to
-   generate  the  proper table, that's still preferable to ad-hoc code --
-   that's why the fifth field (flags) is there.
+   generate  the proper table, that is still preferable to ad-hoc code --
+   that is why the fifth field (flags) is there.
 
    Have fun!
 
@@ -584,7 +581,7 @@ Source-Form Translation
    The  following  notes  are intended to be a first step towards DOS and
    Macintosh ports of the ncurses libraries.
 
-   The  following library modules are `pure curses'; they operate only on
+   The  following library modules are "pure curses"; they operate only on
    the  curses  internal  structures,  do all output through other curses
    calls  (not  including  tputs()  and putp()) and do not call any other
    UNIX  routines  such  as  signal(2)  or  the stdio library. Thus, they
@@ -631,7 +628,7 @@ Source-Form Translation
 
    Modules that would have to be modified for a port start here:
 
-   The  following  modules  are  `pure  curses'  but  contain assumptions
+   The  following  modules  are  "pure  curses"  but  contain assumptions
    inappropriate for a memory-mapped port.
 
    lib_longname.c