X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fhackguide.html;h=2b9445538dc8df8aab657afde43639b7cf18ff6f;hb=205ea499dbbceba5201d997fbd8b6b1f7f29bd50;hp=71312a565f4c5c9d68cae44f7b9e70e95a59adba;hpb=18c5cff3297b96ac5988a716c66b374734a7de90;p=ncurses.git diff --git a/doc/html/hackguide.html b/doc/html/hackguide.html index 71312a56..2b944553 100644 --- a/doc/html/hackguide.html +++ b/doc/html/hackguide.html @@ -1,7 +1,7 @@ - - + "HTML Tidy for HTML5 for Linux version 5.6.0"> A Hacker's Guide to Ncurses Internals - -

A Hacker's Guide to NCURSES

+

A Hacker's Guide to NCURSES

-

Contents

+

A Hacker's Guide to NCURSES

- + -

Abstract

+

Abstract

This document is a hacker's tour of the ncurses library and utilities. It discusses @@ -117,8 +115,8 @@ this one. anyone who is interested in porting, extending or improving the package.

-

Objective of the - Package

+

Objective of the + Package

The objective of the ncurses package is to provide a free software API for character-cell terminals and @@ -144,7 +142,7 @@ this one. — we cannot add features if it means breaking the portion of the API corresponding to historical curses versions.

-

Why System V Curses?

+

Why System V Curses?

We used System V curses as a model, reverse-engineering their API, in order to fulfill the first two objectives.

@@ -158,8 +156,8 @@ this one. So conformance with System V took us most of the way to base-level XSI conformance.

-

How to Design - Extensions

+

How to Design + Extensions

The third objective (standards conformance) requires that it be easy to condition source code using ncurses @@ -177,8 +175,8 @@ this one. library header. You can use this to condition the calls to the mouse API calls.

-

Portability and - Configuration

+

Portability and + Configuration

Code written for ncurses may assume an ANSI-standard C compiler and POSIX-compatible OS interface. It @@ -208,8 +206,8 @@ this one. (configure.in and aclocal.m4) to set up a new feature macro, which you then use to condition your code.

-

Documentation - Conventions

+

Documentation + Conventions

There are three kinds of documentation associated with this package. Each has a different preferred format:

@@ -226,7 +224,7 @@ this one.
  1. Maintain package-internal files in plain - text. The expected viewer for them more(1) or + text. The expected viewer for them is more(1) or an editor window; there is no point in elaborate mark-up.
  2. Mark up manual pages in the man macros. @@ -249,7 +247,7 @@ this one. course, it make exporting things like the announcement document to WWW pretty trivial.

    -

    How to Report Bugs

    +

    How to Report Bugs

    The reporting address for bugs is bug-ncurses-request@gnu.org with a message containing the line:

    -
    +  
                  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 do not have a lot of hours to spend on elementary @@ -276,8 +273,7 @@ this one. tail end and have to wait a while.

      -
    1. Develop a recipe to reproduce the bug. - +
    2. 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 quick fix is develop a way we can duplicate the bad @@ -287,8 +283,7 @@ this one. with the distribution.)

    3. -
    4. Try to reproduce the bug on a different terminal type. - +
    5. 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 are @@ -309,8 +304,7 @@ this one. triggered or masked by these.

    6. -
    7. Generate and examine a trace file for the broken behavior. - +
    8. 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 TRACE_UPDATE. (See

    9. -
    10. Report details and symptoms, not just interpretations. - +
    11. Report details and symptoms, not just interpretations.

      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 @@ -397,10 +390,10 @@ this one. out. You can also test the hardware-scrolling optimization separately with hardscroll.

      -

      A Tour of the Ncurses - Library

      +

      A Tour of the Ncurses + Library

      -

      Library Overview

      +

      Library Overview

      Most of the library is superstructure — fairly trivial convenience interfaces to a small set of basic functions and data @@ -495,9 +488,9 @@ this one.

      We will discuss these in the compiler tour.

      -

      The Engine Room

      +

      The Engine Room

      -

      Keyboard Input

      +

      Keyboard Input

      All ncurses input funnels through the function wgetch(), defined in lib_getch.c. This @@ -523,7 +516,7 @@ this one. The function timed_wait() effectively simulates a System V select.

      -

      Mouse Events

      +

      Mouse Events

      If the mouse interface is active, wgetch() polls for mouse events each call, before it goes to the keyboard for @@ -568,7 +561,7 @@ this one. reports (low-level events) into a gesture (a high-level or composite event).

      -

      Output and Screen Updating

      +

      Output and Screen Updating

      With the single exception of character echoes during a wgetnstr() call (which simulates cooked-mode line @@ -630,7 +623,7 @@ this one. include/curses.h.in for mask values, near the end.

      -

      The Forms and Menu Libraries

      +

      The Forms and Menu Libraries

      The forms and menu libraries should work reliably in any environment you can port ncurses to. The only portability issue @@ -647,7 +640,7 @@ this one. This version has been slightly cleaned up for ncurses.

      -

      A Tour of the Terminfo Compiler

      +

      A Tour of the Terminfo Compiler

      The ncurses implementation of tic is rather complex internally; it has to do a @@ -664,8 +657,8 @@ this one. values; the grammar above it is trivial, just "parse entries till you run out of file".

      -

      Translation of - Non-use Capabilities

      +

      Translation of + Non-use Capabilities

      Translation of most things besides use capabilities is pretty straightforward. The lexical analyzer's @@ -689,7 +682,7 @@ this one. file. We will have more to say about this in the section on Source-Form Translation.

      -

      Use Capability Resolution

      +

      Use Capability Resolution

      The background problem that makes tic tricky is not the capability translation itself, it is the resolution of @@ -744,8 +737,8 @@ this one. overwriting entries newly made during the tic run, but not about overwriting ones that predate it.

      -

      Source-Form - Translation

      +

      Source-Form + Translation

      Another use of tic is to do source translation between various termcap and terminfo formats. There @@ -773,7 +766,7 @@ this one. where the AIX box1 capability get translated to an acsc string.

      -

      Other Utilities

      +

      Other Utilities

      The infocmp utility is just a wrapper around the same entry-dumping code used by tic for @@ -787,7 +780,7 @@ this one. just do an entry load followed by a tputs() of a selected capability.

      -

      Style Tips for Developers

      +

      Style Tips for Developers

      See the TO-DO file in the top-level directory of the source distribution for additions that would be particularly useful.

      @@ -816,7 +809,7 @@ this one.

      Have fun!

      -

      Porting Hints

      +

      Porting Hints

      The following notes are intended to be a first step towards DOS and Macintosh ports of the ncurses libraries.