Annotation of embedaddon/readline/doc/history.info, revision 1.1.1.1

1.1       misho       1: This is history.info, produced by makeinfo version 4.13 from
                      2: /usr/homes/chet/src/bash/readline-src/doc/history.texi.
                      3: 
                      4: This document describes the GNU History library (version 6.3, 6 January
                      5: 2014), a programming tool that provides a consistent user interface for
                      6: recalling lines of previously typed input.
                      7: 
                      8:    Copyright (C) 1988-2014 Free Software Foundation, Inc.
                      9: 
                     10:      Permission is granted to copy, distribute and/or modify this
                     11:      document under the terms of the GNU Free Documentation License,
                     12:      Version 1.3 or any later version published by the Free Software
                     13:      Foundation; with no Invariant Sections, no Front-Cover Texts, and
                     14:      no Back-Cover Texts.  A copy of the license is included in the
                     15:      section entitled "GNU Free Documentation License".
                     16: 
                     17: 
                     18: INFO-DIR-SECTION Libraries
                     19: START-INFO-DIR-ENTRY
                     20: * History: (history).       The GNU history library API.
                     21: END-INFO-DIR-ENTRY
                     22: 
                     23: 
                     24: File: history.info,  Node: Top,  Next: Using History Interactively,  Up: (dir)
                     25: 
                     26: GNU History Library
                     27: *******************
                     28: 
                     29: This document describes the GNU History library, a programming tool that
                     30: provides a consistent user interface for recalling lines of previously
                     31: typed input.
                     32: 
                     33: * Menu:
                     34: 
                     35: * Using History Interactively::          GNU History User's Manual.
                     36: * Programming with GNU History::  GNU History Programmer's Manual.
                     37: * GNU Free Documentation License::     License for copying this manual.
                     38: * Concept Index::                Index of concepts described in this manual.
                     39: * Function and Variable Index::          Index of externally visible functions
                     40:                                  and variables.
                     41: 
                     42: 
                     43: File: history.info,  Node: Using History Interactively,  Next: Programming with GNU History,  Prev: Top,  Up: Top
                     44: 
                     45: 1 Using History Interactively
                     46: *****************************
                     47: 
                     48: This chapter describes how to use the GNU History Library interactively,
                     49: from a user's standpoint.  It should be considered a user's guide.  For
                     50: information on using the GNU History Library in your own programs,
                     51: *note Programming with GNU History::.
                     52: 
                     53: * Menu:
                     54: 
                     55: * History Interaction::                What it feels like using History as a user.
                     56: 
                     57: 
                     58: File: history.info,  Node: History Interaction,  Up: Using History Interactively
                     59: 
                     60: 1.1 History Expansion
                     61: =====================
                     62: 
                     63: The History library provides a history expansion feature that is similar
                     64: to the history expansion provided by `csh'.  This section describes the
                     65: syntax used to manipulate the history information.
                     66: 
                     67:    History expansions introduce words from the history list into the
                     68: input stream, making it easy to repeat commands, insert the arguments
                     69: to a previous command into the current input line, or fix errors in
                     70: previous commands quickly.
                     71: 
                     72:    History expansion takes place in two parts.  The first is to
                     73: determine which line from the history list should be used during
                     74: substitution.  The second is to select portions of that line for
                     75: inclusion into the current one.  The line selected from the history is
                     76: called the "event", and the portions of that line that are acted upon
                     77: are called "words".  Various "modifiers" are available to manipulate
                     78: the selected words.  The line is broken into words in the same fashion
                     79: that Bash does, so that several words surrounded by quotes are
                     80: considered one word.  History expansions are introduced by the
                     81: appearance of the history expansion character, which is `!' by default.
                     82: 
                     83: * Menu:
                     84: 
                     85: * Event Designators::  How to specify which history line to use.
                     86: * Word Designators::   Specifying which words are of interest.
                     87: * Modifiers::          Modifying the results of substitution.
                     88: 
                     89: 
                     90: File: history.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction
                     91: 
                     92: 1.1.1 Event Designators
                     93: -----------------------
                     94: 
                     95: An event designator is a reference to a command line entry in the
                     96: history list.  Unless the reference is absolute, events are relative to
                     97: the current position in the history list.  
                     98: 
                     99: `!'
                    100:      Start a history substitution, except when followed by a space, tab,
                    101:      the end of the line, or `='.
                    102: 
                    103: `!N'
                    104:      Refer to command line N.
                    105: 
                    106: `!-N'
                    107:      Refer to the command N lines back.
                    108: 
                    109: `!!'
                    110:      Refer to the previous command.  This is a synonym for `!-1'.
                    111: 
                    112: `!STRING'
                    113:      Refer to the most recent command preceding the current position in
                    114:      the history list starting with STRING.
                    115: 
                    116: `!?STRING[?]'
                    117:      Refer to the most recent command preceding the current position in
                    118:      the history list containing STRING.  The trailing `?' may be
                    119:      omitted if the STRING is followed immediately by a newline.
                    120: 
                    121: `^STRING1^STRING2^'
                    122:      Quick Substitution.  Repeat the last command, replacing STRING1
                    123:      with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.
                    124: 
                    125: `!#'
                    126:      The entire command line typed so far.
                    127: 
                    128: 
                    129: 
                    130: File: history.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction
                    131: 
                    132: 1.1.2 Word Designators
                    133: ----------------------
                    134: 
                    135: Word designators are used to select desired words from the event.  A
                    136: `:' separates the event specification from the word designator.  It may
                    137: be omitted if the word designator begins with a `^', `$', `*', `-', or
                    138: `%'.  Words are numbered from the beginning of the line, with the first
                    139: word being denoted by 0 (zero).  Words are inserted into the current
                    140: line separated by single spaces.
                    141: 
                    142:    For example,
                    143: 
                    144: `!!'
                    145:      designates the preceding command.  When you type this, the
                    146:      preceding command is repeated in toto.
                    147: 
                    148: `!!:$'
                    149:      designates the last argument of the preceding command.  This may be
                    150:      shortened to `!$'.
                    151: 
                    152: `!fi:2'
                    153:      designates the second argument of the most recent command starting
                    154:      with the letters `fi'.
                    155: 
                    156:    Here are the word designators:
                    157: 
                    158: `0 (zero)'
                    159:      The `0'th word.  For many applications, this is the command word.
                    160: 
                    161: `N'
                    162:      The Nth word.
                    163: 
                    164: `^'
                    165:      The first argument; that is, word 1.
                    166: 
                    167: `$'
                    168:      The last argument.
                    169: 
                    170: `%'
                    171:      The word matched by the most recent `?STRING?' search.
                    172: 
                    173: `X-Y'
                    174:      A range of words; `-Y' abbreviates `0-Y'.
                    175: 
                    176: `*'
                    177:      All of the words, except the `0'th.  This is a synonym for `1-$'.
                    178:      It is not an error to use `*' if there is just one word in the
                    179:      event; the empty string is returned in that case.
                    180: 
                    181: `X*'
                    182:      Abbreviates `X-$'
                    183: 
                    184: `X-'
                    185:      Abbreviates `X-$' like `X*', but omits the last word.
                    186: 
                    187: 
                    188:    If a word designator is supplied without an event specification, the
                    189: previous command is used as the event.
                    190: 
                    191: 
                    192: File: history.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction
                    193: 
                    194: 1.1.3 Modifiers
                    195: ---------------
                    196: 
                    197: After the optional word designator, you can add a sequence of one or
                    198: more of the following modifiers, each preceded by a `:'.
                    199: 
                    200: `h'
                    201:      Remove a trailing pathname component, leaving only the head.
                    202: 
                    203: `t'
                    204:      Remove all leading pathname components, leaving the tail.
                    205: 
                    206: `r'
                    207:      Remove a trailing suffix of the form `.SUFFIX', leaving the
                    208:      basename.
                    209: 
                    210: `e'
                    211:      Remove all but the trailing suffix.
                    212: 
                    213: `p'
                    214:      Print the new command but do not execute it.
                    215: 
                    216: `s/OLD/NEW/'
                    217:      Substitute NEW for the first occurrence of OLD in the event line.
                    218:      Any delimiter may be used in place of `/'.  The delimiter may be
                    219:      quoted in OLD and NEW with a single backslash.  If `&' appears in
                    220:      NEW, it is replaced by OLD.  A single backslash will quote the
                    221:      `&'.  The final delimiter is optional if it is the last character
                    222:      on the input line.
                    223: 
                    224: `&'
                    225:      Repeat the previous substitution.
                    226: 
                    227: `g'
                    228: `a'
                    229:      Cause changes to be applied over the entire event line.  Used in
                    230:      conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
                    231: 
                    232: `G'
                    233:      Apply the following `s' modifier once to each word in the event.
                    234: 
                    235: 
                    236: 
                    237: File: history.info,  Node: Programming with GNU History,  Next: GNU Free Documentation License,  Prev: Using History Interactively,  Up: Top
                    238: 
                    239: 2 Programming with GNU History
                    240: ******************************
                    241: 
                    242: This chapter describes how to interface programs that you write with
                    243: the GNU History Library.  It should be considered a technical guide.
                    244: For information on the interactive use of GNU History, *note Using
                    245: History Interactively::.
                    246: 
                    247: * Menu:
                    248: 
                    249: * Introduction to History::    What is the GNU History library for?
                    250: * History Storage::            How information is stored.
                    251: * History Functions::          Functions that you can use.
                    252: * History Variables::          Variables that control behaviour.
                    253: * History Programming Example::        Example of using the GNU History Library.
                    254: 
                    255: 
                    256: File: history.info,  Node: Introduction to History,  Next: History Storage,  Up: Programming with GNU History
                    257: 
                    258: 2.1 Introduction to History
                    259: ===========================
                    260: 
                    261: Many programs read input from the user a line at a time.  The GNU
                    262: History library is able to keep track of those lines, associate
                    263: arbitrary data with each line, and utilize information from previous
                    264: lines in composing new ones.
                    265: 
                    266:    The programmer using the History library has available functions for
                    267: remembering lines on a history list, associating arbitrary data with a
                    268: line, removing lines from the list, searching through the list for a
                    269: line containing an arbitrary text string, and referencing any line in
                    270: the list directly.  In addition, a history "expansion" function is
                    271: available which provides for a consistent user interface across
                    272: different programs.
                    273: 
                    274:    The user using programs written with the History library has the
                    275: benefit of a consistent user interface with a set of well-known
                    276: commands for manipulating the text of previous lines and using that text
                    277: in new commands.  The basic history manipulation commands are similar to
                    278: the history substitution provided by `csh'.
                    279: 
                    280:    If the programmer desires, he can use the Readline library, which
                    281: includes some history manipulation by default, and has the added
                    282: advantage of command line editing.
                    283: 
                    284:    Before declaring any functions using any functionality the History
                    285: library provides in other code, an application writer should include
                    286: the file `<readline/history.h>' in any file that uses the History
                    287: library's features.  It supplies extern declarations for all of the
                    288: library's public functions and variables, and declares all of the
                    289: public data structures.
                    290: 
                    291: 
                    292: File: history.info,  Node: History Storage,  Next: History Functions,  Prev: Introduction to History,  Up: Programming with GNU History
                    293: 
                    294: 2.2 History Storage
                    295: ===================
                    296: 
                    297: The history list is an array of history entries.  A history entry is
                    298: declared as follows:
                    299: 
                    300:      typedef void *histdata_t;
                    301: 
                    302:      typedef struct _hist_entry {
                    303:        char *line;
                    304:        char *timestamp;
                    305:        histdata_t data;
                    306:      } HIST_ENTRY;
                    307: 
                    308:    The history list itself might therefore be declared as
                    309: 
                    310:      HIST_ENTRY **the_history_list;
                    311: 
                    312:    The state of the History library is encapsulated into a single
                    313: structure:
                    314: 
                    315:      /*
                    316:       * A structure used to pass around the current state of the history.
                    317:       */
                    318:      typedef struct _hist_state {
                    319:        HIST_ENTRY **entries; /* Pointer to the entries themselves. */
                    320:        int offset;           /* The location pointer within this array. */
                    321:        int length;           /* Number of elements within this array. */
                    322:        int size;             /* Number of slots allocated to this array. */
                    323:        int flags;
                    324:      } HISTORY_STATE;
                    325: 
                    326:    If the flags member includes `HS_STIFLED', the history has been
                    327: stifled.
                    328: 
                    329: 
                    330: File: history.info,  Node: History Functions,  Next: History Variables,  Prev: History Storage,  Up: Programming with GNU History
                    331: 
                    332: 2.3 History Functions
                    333: =====================
                    334: 
                    335: This section describes the calling sequence for the various functions
                    336: exported by the GNU History library.
                    337: 
                    338: * Menu:
                    339: 
                    340: * Initializing History and State Management::  Functions to call when you
                    341:                                                want to use history in a
                    342:                                                program.
                    343: * History List Management::            Functions used to manage the list
                    344:                                        of history entries.
                    345: * Information About the History List:: Functions returning information about
                    346:                                        the history list.
                    347: * Moving Around the History List::     Functions used to change the position
                    348:                                        in the history list.
                    349: * Searching the History List::         Functions to search the history list
                    350:                                        for entries containing a string.
                    351: * Managing the History File::          Functions that read and write a file
                    352:                                        containing the history list.
                    353: * History Expansion::                  Functions to perform csh-like history
                    354:                                        expansion.
                    355: 
                    356: 
                    357: File: history.info,  Node: Initializing History and State Management,  Next: History List Management,  Up: History Functions
                    358: 
                    359: 2.3.1 Initializing History and State Management
                    360: -----------------------------------------------
                    361: 
                    362: This section describes functions used to initialize and manage the
                    363: state of the History library when you want to use the history functions
                    364: in your program.
                    365: 
                    366:  -- Function: void using_history (void)
                    367:      Begin a session in which the history functions might be used.  This
                    368:      initializes the interactive variables.
                    369: 
                    370:  -- Function: HISTORY_STATE * history_get_history_state (void)
                    371:      Return a structure describing the current state of the input
                    372:      history.
                    373: 
                    374:  -- Function: void history_set_history_state (HISTORY_STATE *state)
                    375:      Set the state of the history list according to STATE.
                    376: 
                    377: 
                    378: File: history.info,  Node: History List Management,  Next: Information About the History List,  Prev: Initializing History and State Management,  Up: History Functions
                    379: 
                    380: 2.3.2 History List Management
                    381: -----------------------------
                    382: 
                    383: These functions manage individual entries on the history list, or set
                    384: parameters managing the list itself.
                    385: 
                    386:  -- Function: void add_history (const char *string)
                    387:      Place STRING at the end of the history list.  The associated data
                    388:      field (if any) is set to `NULL'.
                    389: 
                    390:  -- Function: void add_history_time (const char *string)
                    391:      Change the time stamp associated with the most recent history
                    392:      entry to STRING.
                    393: 
                    394:  -- Function: HIST_ENTRY * remove_history (int which)
                    395:      Remove history entry at offset WHICH from the history.  The
                    396:      removed element is returned so you can free the line, data, and
                    397:      containing structure.
                    398: 
                    399:  -- Function: histdata_t free_history_entry (HIST_ENTRY *histent)
                    400:      Free the history entry HISTENT and any history library private
                    401:      data associated with it.  Returns the application-specific data so
                    402:      the caller can dispose of it.
                    403: 
                    404:  -- Function: HIST_ENTRY * replace_history_entry (int which, const char
                    405:           *line, histdata_t data)
                    406:      Make the history entry at offset WHICH have LINE and DATA.  This
                    407:      returns the old entry so the caller can dispose of any
                    408:      application-specific data.  In the case of an invalid WHICH, a
                    409:      `NULL' pointer is returned.
                    410: 
                    411:  -- Function: void clear_history (void)
                    412:      Clear the history list by deleting all the entries.
                    413: 
                    414:  -- Function: void stifle_history (int max)
                    415:      Stifle the history list, remembering only the last MAX entries.
                    416: 
                    417:  -- Function: int unstifle_history (void)
                    418:      Stop stifling the history.  This returns the previously-set
                    419:      maximum number of history entries (as set by `stifle_history()').
                    420:      The value is positive if the history was stifled, negative if it
                    421:      wasn't.
                    422: 
                    423:  -- Function: int history_is_stifled (void)
                    424:      Returns non-zero if the history is stifled, zero if it is not.
                    425: 
                    426: 
                    427: File: history.info,  Node: Information About the History List,  Next: Moving Around the History List,  Prev: History List Management,  Up: History Functions
                    428: 
                    429: 2.3.3 Information About the History List
                    430: ----------------------------------------
                    431: 
                    432: These functions return information about the entire history list or
                    433: individual list entries.
                    434: 
                    435:  -- Function: HIST_ENTRY ** history_list (void)
                    436:      Return a `NULL' terminated array of `HIST_ENTRY *' which is the
                    437:      current input history.  Element 0 of this list is the beginning of
                    438:      time.  If there is no history, return `NULL'.
                    439: 
                    440:  -- Function: int where_history (void)
                    441:      Returns the offset of the current history element.
                    442: 
                    443:  -- Function: HIST_ENTRY * current_history (void)
                    444:      Return the history entry at the current position, as determined by
                    445:      `where_history()'.  If there is no entry there, return a `NULL'
                    446:      pointer.
                    447: 
                    448:  -- Function: HIST_ENTRY * history_get (int offset)
                    449:      Return the history entry at position OFFSET, starting from
                    450:      `history_base' (*note History Variables::).  If there is no entry
                    451:      there, or if OFFSET is greater than the history length, return a
                    452:      `NULL' pointer.
                    453: 
                    454:  -- Function: time_t history_get_time (HIST_ENTRY *entry)
                    455:      Return the time stamp associated with the history entry ENTRY.
                    456: 
                    457:  -- Function: int history_total_bytes (void)
                    458:      Return the number of bytes that the primary history entries are
                    459:      using.  This function returns the sum of the lengths of all the
                    460:      lines in the history.
                    461: 
                    462: 
                    463: File: history.info,  Node: Moving Around the History List,  Next: Searching the History List,  Prev: Information About the History List,  Up: History Functions
                    464: 
                    465: 2.3.4 Moving Around the History List
                    466: ------------------------------------
                    467: 
                    468: These functions allow the current index into the history list to be set
                    469: or changed.
                    470: 
                    471:  -- Function: int history_set_pos (int pos)
                    472:      Set the current history offset to POS, an absolute index into the
                    473:      list.  Returns 1 on success, 0 if POS is less than zero or greater
                    474:      than the number of history entries.
                    475: 
                    476:  -- Function: HIST_ENTRY * previous_history (void)
                    477:      Back up the current history offset to the previous history entry,
                    478:      and return a pointer to that entry.  If there is no previous
                    479:      entry, return a `NULL' pointer.
                    480: 
                    481:  -- Function: HIST_ENTRY * next_history (void)
                    482:      Move the current history offset forward to the next history entry,
                    483:      and return the a pointer to that entry.  If there is no next
                    484:      entry, return a `NULL' pointer.
                    485: 
                    486: 
                    487: File: history.info,  Node: Searching the History List,  Next: Managing the History File,  Prev: Moving Around the History List,  Up: History Functions
                    488: 
                    489: 2.3.5 Searching the History List
                    490: --------------------------------
                    491: 
                    492: These functions allow searching of the history list for entries
                    493: containing a specific string.  Searching may be performed both forward
                    494: and backward from the current history position.  The search may be
                    495: "anchored", meaning that the string must match at the beginning of the
                    496: history entry.  
                    497: 
                    498:  -- Function: int history_search (const char *string, int direction)
                    499:      Search the history for STRING, starting at the current history
                    500:      offset.  If DIRECTION is less than 0, then the search is through
                    501:      previous entries, otherwise through subsequent entries.  If STRING
                    502:      is found, then the current history index is set to that history
                    503:      entry, and the value returned is the offset in the line of the
                    504:      entry where STRING was found.  Otherwise, nothing is changed, and
                    505:      a -1 is returned.
                    506: 
                    507:  -- Function: int history_search_prefix (const char *string, int
                    508:           direction)
                    509:      Search the history for STRING, starting at the current history
                    510:      offset.  The search is anchored: matching lines must begin with
                    511:      STRING.  If DIRECTION is less than 0, then the search is through
                    512:      previous entries, otherwise through subsequent entries.  If STRING
                    513:      is found, then the current history index is set to that entry, and
                    514:      the return value is 0.  Otherwise, nothing is changed, and a -1 is
                    515:      returned.
                    516: 
                    517:  -- Function: int history_search_pos (const char *string, int
                    518:           direction, int pos)
                    519:      Search for STRING in the history list, starting at POS, an
                    520:      absolute index into the list.  If DIRECTION is negative, the search
                    521:      proceeds backward from POS, otherwise forward.  Returns the
                    522:      absolute index of the history element where STRING was found, or
                    523:      -1 otherwise.
                    524: 
                    525: 
                    526: File: history.info,  Node: Managing the History File,  Next: History Expansion,  Prev: Searching the History List,  Up: History Functions
                    527: 
                    528: 2.3.6 Managing the History File
                    529: -------------------------------
                    530: 
                    531: The History library can read the history from and write it to a file.
                    532: This section documents the functions for managing a history file.
                    533: 
                    534:  -- Function: int read_history (const char *filename)
                    535:      Add the contents of FILENAME to the history list, a line at a time.
                    536:      If FILENAME is `NULL', then read from `~/.history'.  Returns 0 if
                    537:      successful, or `errno' if not.
                    538: 
                    539:  -- Function: int read_history_range (const char *filename, int from,
                    540:           int to)
                    541:      Read a range of lines from FILENAME, adding them to the history
                    542:      list.  Start reading at line FROM and end at TO.  If FROM is zero,
                    543:      start at the beginning.  If TO is less than FROM, then read until
                    544:      the end of the file.  If FILENAME is `NULL', then read from
                    545:      `~/.history'.  Returns 0 if successful, or `errno' if not.
                    546: 
                    547:  -- Function: int write_history (const char *filename)
                    548:      Write the current history to FILENAME, overwriting FILENAME if
                    549:      necessary.  If FILENAME is `NULL', then write the history list to
                    550:      `~/.history'.  Returns 0 on success, or `errno' on a read or write
                    551:      error.
                    552: 
                    553:  -- Function: int append_history (int nelements, const char *filename)
                    554:      Append the last NELEMENTS of the history list to FILENAME.  If
                    555:      FILENAME is `NULL', then append to `~/.history'.  Returns 0 on
                    556:      success, or `errno' on a read or write error.
                    557: 
                    558:  -- Function: int history_truncate_file (const char *filename, int
                    559:           nlines)
                    560:      Truncate the history file FILENAME, leaving only the last NLINES
                    561:      lines.  If FILENAME is `NULL', then `~/.history' is truncated.
                    562:      Returns 0 on success, or `errno' on failure.
                    563: 
                    564: 
                    565: File: history.info,  Node: History Expansion,  Prev: Managing the History File,  Up: History Functions
                    566: 
                    567: 2.3.7 History Expansion
                    568: -----------------------
                    569: 
                    570: These functions implement history expansion.
                    571: 
                    572:  -- Function: int history_expand (char *string, char **output)
                    573:      Expand STRING, placing the result into OUTPUT, a pointer to a
                    574:      string (*note History Interaction::).  Returns:
                    575:     `0'
                    576:           If no expansions took place (or, if the only change in the
                    577:           text was the removal of escape characters preceding the
                    578:           history expansion character);
                    579: 
                    580:     `1'
                    581:           if expansions did take place;
                    582: 
                    583:     `-1'
                    584:           if there was an error in expansion;
                    585: 
                    586:     `2'
                    587:           if the returned line should be displayed, but not executed,
                    588:           as with the `:p' modifier (*note Modifiers::).
                    589: 
                    590:      If an error occurred in expansion, then OUTPUT contains a
                    591:      descriptive error message.
                    592: 
                    593:  -- Function: char * get_history_event (const char *string, int
                    594:           *cindex, int qchar)
                    595:      Returns the text of the history event beginning at STRING +
                    596:      *CINDEX.  *CINDEX is modified to point to after the event
                    597:      specifier.  At function entry, CINDEX points to the index into
                    598:      STRING where the history event specification begins.  QCHAR is a
                    599:      character that is allowed to end the event specification in
                    600:      addition to the "normal" terminating characters.
                    601: 
                    602:  -- Function: char ** history_tokenize (const char *string)
                    603:      Return an array of tokens parsed out of STRING, much as the shell
                    604:      might.  The tokens are split on the characters in the
                    605:      HISTORY_WORD_DELIMITERS variable, and shell quoting conventions
                    606:      are obeyed.
                    607: 
                    608:  -- Function: char * history_arg_extract (int first, int last, const
                    609:           char *string)
                    610:      Extract a string segment consisting of the FIRST through LAST
                    611:      arguments present in STRING.  Arguments are split using
                    612:      `history_tokenize'.
                    613: 
                    614: 
                    615: File: history.info,  Node: History Variables,  Next: History Programming Example,  Prev: History Functions,  Up: Programming with GNU History
                    616: 
                    617: 2.4 History Variables
                    618: =====================
                    619: 
                    620: This section describes the externally-visible variables exported by the
                    621: GNU History Library.
                    622: 
                    623:  -- Variable: int history_base
                    624:      The logical offset of the first entry in the history list.
                    625: 
                    626:  -- Variable: int history_length
                    627:      The number of entries currently stored in the history list.
                    628: 
                    629:  -- Variable: int history_max_entries
                    630:      The maximum number of history entries.  This must be changed using
                    631:      `stifle_history()'.
                    632: 
                    633:  -- Variable: int history_write_timestamps
                    634:      If non-zero, timestamps are written to the history file, so they
                    635:      can be preserved between sessions.  The default value is 0,
                    636:      meaning that timestamps are not saved.
                    637: 
                    638:      The current timestamp format uses the value of HISTORY_COMMENT_CHAR
                    639:      to delimit timestamp entries in the history file.  If that
                    640:      variable does not have a value (the default), timestamps will not
                    641:      be written.
                    642: 
                    643:  -- Variable: char history_expansion_char
                    644:      The character that introduces a history event.  The default is `!'.
                    645:      Setting this to 0 inhibits history expansion.
                    646: 
                    647:  -- Variable: char history_subst_char
                    648:      The character that invokes word substitution if found at the start
                    649:      of a line.  The default is `^'.
                    650: 
                    651:  -- Variable: char history_comment_char
                    652:      During tokenization, if this character is seen as the first
                    653:      character of a word, then it and all subsequent characters up to a
                    654:      newline are ignored, suppressing history expansion for the
                    655:      remainder of the line.  This is disabled by default.
                    656: 
                    657:  -- Variable: char * history_word_delimiters
                    658:      The characters that separate tokens for `history_tokenize()'.  The
                    659:      default value is `" \t\n()<>;&|"'.
                    660: 
                    661:  -- Variable: char * history_search_delimiter_chars
                    662:      The list of additional characters which can delimit a history
                    663:      search string, in addition to space, TAB, `:' and `?' in the case
                    664:      of a substring search.  The default is empty.
                    665: 
                    666:  -- Variable: char * history_no_expand_chars
                    667:      The list of characters which inhibit history expansion if found
                    668:      immediately following HISTORY_EXPANSION_CHAR.  The default is
                    669:      space, tab, newline, carriage return, and `='.
                    670: 
                    671:  -- Variable: int history_quotes_inhibit_expansion
                    672:      If non-zero, single-quoted words are not scanned for the history
                    673:      expansion character.  The default value is 0.
                    674: 
                    675:  -- Variable: rl_linebuf_func_t * history_inhibit_expansion_function
                    676:      This should be set to the address of a function that takes two
                    677:      arguments: a `char *' (STRING) and an `int' index into that string
                    678:      (I).  It should return a non-zero value if the history expansion
                    679:      starting at STRING[I] should not be performed; zero if the
                    680:      expansion should be done.  It is intended for use by applications
                    681:      like Bash that use the history expansion character for additional
                    682:      purposes.  By default, this variable is set to `NULL'.
                    683: 
                    684: 
                    685: File: history.info,  Node: History Programming Example,  Prev: History Variables,  Up: Programming with GNU History
                    686: 
                    687: 2.5 History Programming Example
                    688: ===============================
                    689: 
                    690: The following program demonstrates simple use of the GNU History
                    691: Library.
                    692: 
                    693:      #include <stdio.h>
                    694:      #include <readline/history.h>
                    695: 
                    696:      main (argc, argv)
                    697:           int argc;
                    698:           char **argv;
                    699:      {
                    700:        char line[1024], *t;
                    701:        int len, done = 0;
                    702: 
                    703:        line[0] = 0;
                    704: 
                    705:        using_history ();
                    706:        while (!done)
                    707:          {
                    708:            printf ("history$ ");
                    709:            fflush (stdout);
                    710:            t = fgets (line, sizeof (line) - 1, stdin);
                    711:            if (t && *t)
                    712:              {
                    713:                len = strlen (t);
                    714:                if (t[len - 1] == '\n')
                    715:                  t[len - 1] = '\0';
                    716:              }
                    717: 
                    718:            if (!t)
                    719:              strcpy (line, "quit");
                    720: 
                    721:            if (line[0])
                    722:              {
                    723:                char *expansion;
                    724:                int result;
                    725: 
                    726:                result = history_expand (line, &expansion);
                    727:                if (result)
                    728:                  fprintf (stderr, "%s\n", expansion);
                    729: 
                    730:                if (result < 0 || result == 2)
                    731:                  {
                    732:                    free (expansion);
                    733:                    continue;
                    734:                  }
                    735: 
                    736:                add_history (expansion);
                    737:                strncpy (line, expansion, sizeof (line) - 1);
                    738:                free (expansion);
                    739:              }
                    740: 
                    741:            if (strcmp (line, "quit") == 0)
                    742:              done = 1;
                    743:            else if (strcmp (line, "save") == 0)
                    744:              write_history ("history_file");
                    745:            else if (strcmp (line, "read") == 0)
                    746:              read_history ("history_file");
                    747:            else if (strcmp (line, "list") == 0)
                    748:              {
                    749:                register HIST_ENTRY **the_list;
                    750:                register int i;
                    751: 
                    752:                the_list = history_list ();
                    753:                if (the_list)
                    754:                  for (i = 0; the_list[i]; i++)
                    755:                    printf ("%d: %s\n", i + history_base, the_list[i]->line);
                    756:              }
                    757:            else if (strncmp (line, "delete", 6) == 0)
                    758:              {
                    759:                int which;
                    760:                if ((sscanf (line + 6, "%d", &which)) == 1)
                    761:                  {
                    762:                    HIST_ENTRY *entry = remove_history (which);
                    763:                    if (!entry)
                    764:                      fprintf (stderr, "No such entry %d\n", which);
                    765:                    else
                    766:                      {
                    767:                        free (entry->line);
                    768:                        free (entry);
                    769:                      }
                    770:                  }
                    771:                else
                    772:                  {
                    773:                    fprintf (stderr, "non-numeric arg given to `delete'\n");
                    774:                  }
                    775:              }
                    776:          }
                    777:      }
                    778: 
                    779: 
                    780: File: history.info,  Node: GNU Free Documentation License,  Next: Concept Index,  Prev: Programming with GNU History,  Up: Top
                    781: 
                    782: Appendix A GNU Free Documentation License
                    783: *****************************************
                    784: 
                    785:                      Version 1.3, 3 November 2008
                    786: 
                    787:      Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
                    788:      `http://fsf.org/'
                    789: 
                    790:      Everyone is permitted to copy and distribute verbatim copies
                    791:      of this license document, but changing it is not allowed.
                    792: 
                    793:   0. PREAMBLE
                    794: 
                    795:      The purpose of this License is to make a manual, textbook, or other
                    796:      functional and useful document "free" in the sense of freedom: to
                    797:      assure everyone the effective freedom to copy and redistribute it,
                    798:      with or without modifying it, either commercially or
                    799:      noncommercially.  Secondarily, this License preserves for the
                    800:      author and publisher a way to get credit for their work, while not
                    801:      being considered responsible for modifications made by others.
                    802: 
                    803:      This License is a kind of "copyleft", which means that derivative
                    804:      works of the document must themselves be free in the same sense.
                    805:      It complements the GNU General Public License, which is a copyleft
                    806:      license designed for free software.
                    807: 
                    808:      We have designed this License in order to use it for manuals for
                    809:      free software, because free software needs free documentation: a
                    810:      free program should come with manuals providing the same freedoms
                    811:      that the software does.  But this License is not limited to
                    812:      software manuals; it can be used for any textual work, regardless
                    813:      of subject matter or whether it is published as a printed book.
                    814:      We recommend this License principally for works whose purpose is
                    815:      instruction or reference.
                    816: 
                    817:   1. APPLICABILITY AND DEFINITIONS
                    818: 
                    819:      This License applies to any manual or other work, in any medium,
                    820:      that contains a notice placed by the copyright holder saying it
                    821:      can be distributed under the terms of this License.  Such a notice
                    822:      grants a world-wide, royalty-free license, unlimited in duration,
                    823:      to use that work under the conditions stated herein.  The
                    824:      "Document", below, refers to any such manual or work.  Any member
                    825:      of the public is a licensee, and is addressed as "you".  You
                    826:      accept the license if you copy, modify or distribute the work in a
                    827:      way requiring permission under copyright law.
                    828: 
                    829:      A "Modified Version" of the Document means any work containing the
                    830:      Document or a portion of it, either copied verbatim, or with
                    831:      modifications and/or translated into another language.
                    832: 
                    833:      A "Secondary Section" is a named appendix or a front-matter section
                    834:      of the Document that deals exclusively with the relationship of the
                    835:      publishers or authors of the Document to the Document's overall
                    836:      subject (or to related matters) and contains nothing that could
                    837:      fall directly within that overall subject.  (Thus, if the Document
                    838:      is in part a textbook of mathematics, a Secondary Section may not
                    839:      explain any mathematics.)  The relationship could be a matter of
                    840:      historical connection with the subject or with related matters, or
                    841:      of legal, commercial, philosophical, ethical or political position
                    842:      regarding them.
                    843: 
                    844:      The "Invariant Sections" are certain Secondary Sections whose
                    845:      titles are designated, as being those of Invariant Sections, in
                    846:      the notice that says that the Document is released under this
                    847:      License.  If a section does not fit the above definition of
                    848:      Secondary then it is not allowed to be designated as Invariant.
                    849:      The Document may contain zero Invariant Sections.  If the Document
                    850:      does not identify any Invariant Sections then there are none.
                    851: 
                    852:      The "Cover Texts" are certain short passages of text that are
                    853:      listed, as Front-Cover Texts or Back-Cover Texts, in the notice
                    854:      that says that the Document is released under this License.  A
                    855:      Front-Cover Text may be at most 5 words, and a Back-Cover Text may
                    856:      be at most 25 words.
                    857: 
                    858:      A "Transparent" copy of the Document means a machine-readable copy,
                    859:      represented in a format whose specification is available to the
                    860:      general public, that is suitable for revising the document
                    861:      straightforwardly with generic text editors or (for images
                    862:      composed of pixels) generic paint programs or (for drawings) some
                    863:      widely available drawing editor, and that is suitable for input to
                    864:      text formatters or for automatic translation to a variety of
                    865:      formats suitable for input to text formatters.  A copy made in an
                    866:      otherwise Transparent file format whose markup, or absence of
                    867:      markup, has been arranged to thwart or discourage subsequent
                    868:      modification by readers is not Transparent.  An image format is
                    869:      not Transparent if used for any substantial amount of text.  A
                    870:      copy that is not "Transparent" is called "Opaque".
                    871: 
                    872:      Examples of suitable formats for Transparent copies include plain
                    873:      ASCII without markup, Texinfo input format, LaTeX input format,
                    874:      SGML or XML using a publicly available DTD, and
                    875:      standard-conforming simple HTML, PostScript or PDF designed for
                    876:      human modification.  Examples of transparent image formats include
                    877:      PNG, XCF and JPG.  Opaque formats include proprietary formats that
                    878:      can be read and edited only by proprietary word processors, SGML or
                    879:      XML for which the DTD and/or processing tools are not generally
                    880:      available, and the machine-generated HTML, PostScript or PDF
                    881:      produced by some word processors for output purposes only.
                    882: 
                    883:      The "Title Page" means, for a printed book, the title page itself,
                    884:      plus such following pages as are needed to hold, legibly, the
                    885:      material this License requires to appear in the title page.  For
                    886:      works in formats which do not have any title page as such, "Title
                    887:      Page" means the text near the most prominent appearance of the
                    888:      work's title, preceding the beginning of the body of the text.
                    889: 
                    890:      The "publisher" means any person or entity that distributes copies
                    891:      of the Document to the public.
                    892: 
                    893:      A section "Entitled XYZ" means a named subunit of the Document
                    894:      whose title either is precisely XYZ or contains XYZ in parentheses
                    895:      following text that translates XYZ in another language.  (Here XYZ
                    896:      stands for a specific section name mentioned below, such as
                    897:      "Acknowledgements", "Dedications", "Endorsements", or "History".)
                    898:      To "Preserve the Title" of such a section when you modify the
                    899:      Document means that it remains a section "Entitled XYZ" according
                    900:      to this definition.
                    901: 
                    902:      The Document may include Warranty Disclaimers next to the notice
                    903:      which states that this License applies to the Document.  These
                    904:      Warranty Disclaimers are considered to be included by reference in
                    905:      this License, but only as regards disclaiming warranties: any other
                    906:      implication that these Warranty Disclaimers may have is void and
                    907:      has no effect on the meaning of this License.
                    908: 
                    909:   2. VERBATIM COPYING
                    910: 
                    911:      You may copy and distribute the Document in any medium, either
                    912:      commercially or noncommercially, provided that this License, the
                    913:      copyright notices, and the license notice saying this License
                    914:      applies to the Document are reproduced in all copies, and that you
                    915:      add no other conditions whatsoever to those of this License.  You
                    916:      may not use technical measures to obstruct or control the reading
                    917:      or further copying of the copies you make or distribute.  However,
                    918:      you may accept compensation in exchange for copies.  If you
                    919:      distribute a large enough number of copies you must also follow
                    920:      the conditions in section 3.
                    921: 
                    922:      You may also lend copies, under the same conditions stated above,
                    923:      and you may publicly display copies.
                    924: 
                    925:   3. COPYING IN QUANTITY
                    926: 
                    927:      If you publish printed copies (or copies in media that commonly
                    928:      have printed covers) of the Document, numbering more than 100, and
                    929:      the Document's license notice requires Cover Texts, you must
                    930:      enclose the copies in covers that carry, clearly and legibly, all
                    931:      these Cover Texts: Front-Cover Texts on the front cover, and
                    932:      Back-Cover Texts on the back cover.  Both covers must also clearly
                    933:      and legibly identify you as the publisher of these copies.  The
                    934:      front cover must present the full title with all words of the
                    935:      title equally prominent and visible.  You may add other material
                    936:      on the covers in addition.  Copying with changes limited to the
                    937:      covers, as long as they preserve the title of the Document and
                    938:      satisfy these conditions, can be treated as verbatim copying in
                    939:      other respects.
                    940: 
                    941:      If the required texts for either cover are too voluminous to fit
                    942:      legibly, you should put the first ones listed (as many as fit
                    943:      reasonably) on the actual cover, and continue the rest onto
                    944:      adjacent pages.
                    945: 
                    946:      If you publish or distribute Opaque copies of the Document
                    947:      numbering more than 100, you must either include a
                    948:      machine-readable Transparent copy along with each Opaque copy, or
                    949:      state in or with each Opaque copy a computer-network location from
                    950:      which the general network-using public has access to download
                    951:      using public-standard network protocols a complete Transparent
                    952:      copy of the Document, free of added material.  If you use the
                    953:      latter option, you must take reasonably prudent steps, when you
                    954:      begin distribution of Opaque copies in quantity, to ensure that
                    955:      this Transparent copy will remain thus accessible at the stated
                    956:      location until at least one year after the last time you
                    957:      distribute an Opaque copy (directly or through your agents or
                    958:      retailers) of that edition to the public.
                    959: 
                    960:      It is requested, but not required, that you contact the authors of
                    961:      the Document well before redistributing any large number of
                    962:      copies, to give them a chance to provide you with an updated
                    963:      version of the Document.
                    964: 
                    965:   4. MODIFICATIONS
                    966: 
                    967:      You may copy and distribute a Modified Version of the Document
                    968:      under the conditions of sections 2 and 3 above, provided that you
                    969:      release the Modified Version under precisely this License, with
                    970:      the Modified Version filling the role of the Document, thus
                    971:      licensing distribution and modification of the Modified Version to
                    972:      whoever possesses a copy of it.  In addition, you must do these
                    973:      things in the Modified Version:
                    974: 
                    975:        A. Use in the Title Page (and on the covers, if any) a title
                    976:           distinct from that of the Document, and from those of
                    977:           previous versions (which should, if there were any, be listed
                    978:           in the History section of the Document).  You may use the
                    979:           same title as a previous version if the original publisher of
                    980:           that version gives permission.
                    981: 
                    982:        B. List on the Title Page, as authors, one or more persons or
                    983:           entities responsible for authorship of the modifications in
                    984:           the Modified Version, together with at least five of the
                    985:           principal authors of the Document (all of its principal
                    986:           authors, if it has fewer than five), unless they release you
                    987:           from this requirement.
                    988: 
                    989:        C. State on the Title page the name of the publisher of the
                    990:           Modified Version, as the publisher.
                    991: 
                    992:        D. Preserve all the copyright notices of the Document.
                    993: 
                    994:        E. Add an appropriate copyright notice for your modifications
                    995:           adjacent to the other copyright notices.
                    996: 
                    997:        F. Include, immediately after the copyright notices, a license
                    998:           notice giving the public permission to use the Modified
                    999:           Version under the terms of this License, in the form shown in
                   1000:           the Addendum below.
                   1001: 
                   1002:        G. Preserve in that license notice the full lists of Invariant
                   1003:           Sections and required Cover Texts given in the Document's
                   1004:           license notice.
                   1005: 
                   1006:        H. Include an unaltered copy of this License.
                   1007: 
                   1008:        I. Preserve the section Entitled "History", Preserve its Title,
                   1009:           and add to it an item stating at least the title, year, new
                   1010:           authors, and publisher of the Modified Version as given on
                   1011:           the Title Page.  If there is no section Entitled "History" in
                   1012:           the Document, create one stating the title, year, authors,
                   1013:           and publisher of the Document as given on its Title Page,
                   1014:           then add an item describing the Modified Version as stated in
                   1015:           the previous sentence.
                   1016: 
                   1017:        J. Preserve the network location, if any, given in the Document
                   1018:           for public access to a Transparent copy of the Document, and
                   1019:           likewise the network locations given in the Document for
                   1020:           previous versions it was based on.  These may be placed in
                   1021:           the "History" section.  You may omit a network location for a
                   1022:           work that was published at least four years before the
                   1023:           Document itself, or if the original publisher of the version
                   1024:           it refers to gives permission.
                   1025: 
                   1026:        K. For any section Entitled "Acknowledgements" or "Dedications",
                   1027:           Preserve the Title of the section, and preserve in the
                   1028:           section all the substance and tone of each of the contributor
                   1029:           acknowledgements and/or dedications given therein.
                   1030: 
                   1031:        L. Preserve all the Invariant Sections of the Document,
                   1032:           unaltered in their text and in their titles.  Section numbers
                   1033:           or the equivalent are not considered part of the section
                   1034:           titles.
                   1035: 
                   1036:        M. Delete any section Entitled "Endorsements".  Such a section
                   1037:           may not be included in the Modified Version.
                   1038: 
                   1039:        N. Do not retitle any existing section to be Entitled
                   1040:           "Endorsements" or to conflict in title with any Invariant
                   1041:           Section.
                   1042: 
                   1043:        O. Preserve any Warranty Disclaimers.
                   1044: 
                   1045:      If the Modified Version includes new front-matter sections or
                   1046:      appendices that qualify as Secondary Sections and contain no
                   1047:      material copied from the Document, you may at your option
                   1048:      designate some or all of these sections as invariant.  To do this,
                   1049:      add their titles to the list of Invariant Sections in the Modified
                   1050:      Version's license notice.  These titles must be distinct from any
                   1051:      other section titles.
                   1052: 
                   1053:      You may add a section Entitled "Endorsements", provided it contains
                   1054:      nothing but endorsements of your Modified Version by various
                   1055:      parties--for example, statements of peer review or that the text
                   1056:      has been approved by an organization as the authoritative
                   1057:      definition of a standard.
                   1058: 
                   1059:      You may add a passage of up to five words as a Front-Cover Text,
                   1060:      and a passage of up to 25 words as a Back-Cover Text, to the end
                   1061:      of the list of Cover Texts in the Modified Version.  Only one
                   1062:      passage of Front-Cover Text and one of Back-Cover Text may be
                   1063:      added by (or through arrangements made by) any one entity.  If the
                   1064:      Document already includes a cover text for the same cover,
                   1065:      previously added by you or by arrangement made by the same entity
                   1066:      you are acting on behalf of, you may not add another; but you may
                   1067:      replace the old one, on explicit permission from the previous
                   1068:      publisher that added the old one.
                   1069: 
                   1070:      The author(s) and publisher(s) of the Document do not by this
                   1071:      License give permission to use their names for publicity for or to
                   1072:      assert or imply endorsement of any Modified Version.
                   1073: 
                   1074:   5. COMBINING DOCUMENTS
                   1075: 
                   1076:      You may combine the Document with other documents released under
                   1077:      this License, under the terms defined in section 4 above for
                   1078:      modified versions, provided that you include in the combination
                   1079:      all of the Invariant Sections of all of the original documents,
                   1080:      unmodified, and list them all as Invariant Sections of your
                   1081:      combined work in its license notice, and that you preserve all
                   1082:      their Warranty Disclaimers.
                   1083: 
                   1084:      The combined work need only contain one copy of this License, and
                   1085:      multiple identical Invariant Sections may be replaced with a single
                   1086:      copy.  If there are multiple Invariant Sections with the same name
                   1087:      but different contents, make the title of each such section unique
                   1088:      by adding at the end of it, in parentheses, the name of the
                   1089:      original author or publisher of that section if known, or else a
                   1090:      unique number.  Make the same adjustment to the section titles in
                   1091:      the list of Invariant Sections in the license notice of the
                   1092:      combined work.
                   1093: 
                   1094:      In the combination, you must combine any sections Entitled
                   1095:      "History" in the various original documents, forming one section
                   1096:      Entitled "History"; likewise combine any sections Entitled
                   1097:      "Acknowledgements", and any sections Entitled "Dedications".  You
                   1098:      must delete all sections Entitled "Endorsements."
                   1099: 
                   1100:   6. COLLECTIONS OF DOCUMENTS
                   1101: 
                   1102:      You may make a collection consisting of the Document and other
                   1103:      documents released under this License, and replace the individual
                   1104:      copies of this License in the various documents with a single copy
                   1105:      that is included in the collection, provided that you follow the
                   1106:      rules of this License for verbatim copying of each of the
                   1107:      documents in all other respects.
                   1108: 
                   1109:      You may extract a single document from such a collection, and
                   1110:      distribute it individually under this License, provided you insert
                   1111:      a copy of this License into the extracted document, and follow
                   1112:      this License in all other respects regarding verbatim copying of
                   1113:      that document.
                   1114: 
                   1115:   7. AGGREGATION WITH INDEPENDENT WORKS
                   1116: 
                   1117:      A compilation of the Document or its derivatives with other
                   1118:      separate and independent documents or works, in or on a volume of
                   1119:      a storage or distribution medium, is called an "aggregate" if the
                   1120:      copyright resulting from the compilation is not used to limit the
                   1121:      legal rights of the compilation's users beyond what the individual
                   1122:      works permit.  When the Document is included in an aggregate, this
                   1123:      License does not apply to the other works in the aggregate which
                   1124:      are not themselves derivative works of the Document.
                   1125: 
                   1126:      If the Cover Text requirement of section 3 is applicable to these
                   1127:      copies of the Document, then if the Document is less than one half
                   1128:      of the entire aggregate, the Document's Cover Texts may be placed
                   1129:      on covers that bracket the Document within the aggregate, or the
                   1130:      electronic equivalent of covers if the Document is in electronic
                   1131:      form.  Otherwise they must appear on printed covers that bracket
                   1132:      the whole aggregate.
                   1133: 
                   1134:   8. TRANSLATION
                   1135: 
                   1136:      Translation is considered a kind of modification, so you may
                   1137:      distribute translations of the Document under the terms of section
                   1138:      4.  Replacing Invariant Sections with translations requires special
                   1139:      permission from their copyright holders, but you may include
                   1140:      translations of some or all Invariant Sections in addition to the
                   1141:      original versions of these Invariant Sections.  You may include a
                   1142:      translation of this License, and all the license notices in the
                   1143:      Document, and any Warranty Disclaimers, provided that you also
                   1144:      include the original English version of this License and the
                   1145:      original versions of those notices and disclaimers.  In case of a
                   1146:      disagreement between the translation and the original version of
                   1147:      this License or a notice or disclaimer, the original version will
                   1148:      prevail.
                   1149: 
                   1150:      If a section in the Document is Entitled "Acknowledgements",
                   1151:      "Dedications", or "History", the requirement (section 4) to
                   1152:      Preserve its Title (section 1) will typically require changing the
                   1153:      actual title.
                   1154: 
                   1155:   9. TERMINATION
                   1156: 
                   1157:      You may not copy, modify, sublicense, or distribute the Document
                   1158:      except as expressly provided under this License.  Any attempt
                   1159:      otherwise to copy, modify, sublicense, or distribute it is void,
                   1160:      and will automatically terminate your rights under this License.
                   1161: 
                   1162:      However, if you cease all violation of this License, then your
                   1163:      license from a particular copyright holder is reinstated (a)
                   1164:      provisionally, unless and until the copyright holder explicitly
                   1165:      and finally terminates your license, and (b) permanently, if the
                   1166:      copyright holder fails to notify you of the violation by some
                   1167:      reasonable means prior to 60 days after the cessation.
                   1168: 
                   1169:      Moreover, your license from a particular copyright holder is
                   1170:      reinstated permanently if the copyright holder notifies you of the
                   1171:      violation by some reasonable means, this is the first time you have
                   1172:      received notice of violation of this License (for any work) from
                   1173:      that copyright holder, and you cure the violation prior to 30 days
                   1174:      after your receipt of the notice.
                   1175: 
                   1176:      Termination of your rights under this section does not terminate
                   1177:      the licenses of parties who have received copies or rights from
                   1178:      you under this License.  If your rights have been terminated and
                   1179:      not permanently reinstated, receipt of a copy of some or all of
                   1180:      the same material does not give you any rights to use it.
                   1181: 
                   1182:  10. FUTURE REVISIONS OF THIS LICENSE
                   1183: 
                   1184:      The Free Software Foundation may publish new, revised versions of
                   1185:      the GNU Free Documentation License from time to time.  Such new
                   1186:      versions will be similar in spirit to the present version, but may
                   1187:      differ in detail to address new problems or concerns.  See
                   1188:      `http://www.gnu.org/copyleft/'.
                   1189: 
                   1190:      Each version of the License is given a distinguishing version
                   1191:      number.  If the Document specifies that a particular numbered
                   1192:      version of this License "or any later version" applies to it, you
                   1193:      have the option of following the terms and conditions either of
                   1194:      that specified version or of any later version that has been
                   1195:      published (not as a draft) by the Free Software Foundation.  If
                   1196:      the Document does not specify a version number of this License,
                   1197:      you may choose any version ever published (not as a draft) by the
                   1198:      Free Software Foundation.  If the Document specifies that a proxy
                   1199:      can decide which future versions of this License can be used, that
                   1200:      proxy's public statement of acceptance of a version permanently
                   1201:      authorizes you to choose that version for the Document.
                   1202: 
                   1203:  11. RELICENSING
                   1204: 
                   1205:      "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
                   1206:      World Wide Web server that publishes copyrightable works and also
                   1207:      provides prominent facilities for anybody to edit those works.  A
                   1208:      public wiki that anybody can edit is an example of such a server.
                   1209:      A "Massive Multiauthor Collaboration" (or "MMC") contained in the
                   1210:      site means any set of copyrightable works thus published on the MMC
                   1211:      site.
                   1212: 
                   1213:      "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
                   1214:      license published by Creative Commons Corporation, a not-for-profit
                   1215:      corporation with a principal place of business in San Francisco,
                   1216:      California, as well as future copyleft versions of that license
                   1217:      published by that same organization.
                   1218: 
                   1219:      "Incorporate" means to publish or republish a Document, in whole or
                   1220:      in part, as part of another Document.
                   1221: 
                   1222:      An MMC is "eligible for relicensing" if it is licensed under this
                   1223:      License, and if all works that were first published under this
                   1224:      License somewhere other than this MMC, and subsequently
                   1225:      incorporated in whole or in part into the MMC, (1) had no cover
                   1226:      texts or invariant sections, and (2) were thus incorporated prior
                   1227:      to November 1, 2008.
                   1228: 
                   1229:      The operator of an MMC Site may republish an MMC contained in the
                   1230:      site under CC-BY-SA on the same site at any time before August 1,
                   1231:      2009, provided the MMC is eligible for relicensing.
                   1232: 
                   1233: 
                   1234: ADDENDUM: How to use this License for your documents
                   1235: ====================================================
                   1236: 
                   1237: To use this License in a document you have written, include a copy of
                   1238: the License in the document and put the following copyright and license
                   1239: notices just after the title page:
                   1240: 
                   1241:        Copyright (C)  YEAR  YOUR NAME.
                   1242:        Permission is granted to copy, distribute and/or modify this document
                   1243:        under the terms of the GNU Free Documentation License, Version 1.3
                   1244:        or any later version published by the Free Software Foundation;
                   1245:        with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
                   1246:        Texts.  A copy of the license is included in the section entitled ``GNU
                   1247:        Free Documentation License''.
                   1248: 
                   1249:    If you have Invariant Sections, Front-Cover Texts and Back-Cover
                   1250: Texts, replace the "with...Texts." line with this:
                   1251: 
                   1252:          with the Invariant Sections being LIST THEIR TITLES, with
                   1253:          the Front-Cover Texts being LIST, and with the Back-Cover Texts
                   1254:          being LIST.
                   1255: 
                   1256:    If you have Invariant Sections without Cover Texts, or some other
                   1257: combination of the three, merge those two alternatives to suit the
                   1258: situation.
                   1259: 
                   1260:    If your document contains nontrivial examples of program code, we
                   1261: recommend releasing these examples in parallel under your choice of
                   1262: free software license, such as the GNU General Public License, to
                   1263: permit their use in free software.
                   1264: 
                   1265: 
                   1266: File: history.info,  Node: Concept Index,  Next: Function and Variable Index,  Prev: GNU Free Documentation License,  Up: Top
                   1267: 
                   1268: Appendix B Concept Index
                   1269: ************************
                   1270: 
                   1271: [index]
                   1272: * Menu:
                   1273: 
                   1274: * anchored search:                       Searching the History List.
                   1275:                                                                (line 10)
                   1276: * event designators:                     Event Designators.    (line  6)
                   1277: * history events:                        Event Designators.    (line  8)
                   1278: * history expansion:                     History Interaction.  (line  6)
                   1279: * History Searching:                     Searching the History List.
                   1280:                                                                (line  6)
                   1281: 
                   1282: 
                   1283: File: history.info,  Node: Function and Variable Index,  Prev: Concept Index,  Up: Top
                   1284: 
                   1285: Appendix C Function and Variable Index
                   1286: **************************************
                   1287: 
                   1288: [index]
                   1289: * Menu:
                   1290: 
                   1291: * add_history:                           History List Management.
                   1292:                                                                (line 10)
                   1293: * add_history_time:                      History List Management.
                   1294:                                                                (line 14)
                   1295: * append_history:                        Managing the History File.
                   1296:                                                                (line 29)
                   1297: * clear_history:                         History List Management.
                   1298:                                                                (line 35)
                   1299: * current_history:                       Information About the History List.
                   1300:                                                                (line 18)
                   1301: * free_history_entry:                    History List Management.
                   1302:                                                                (line 23)
                   1303: * get_history_event:                     History Expansion.    (line 31)
                   1304: * history_arg_extract:                   History Expansion.    (line 46)
                   1305: * history_base:                          History Variables.    (line 10)
                   1306: * history_comment_char:                  History Variables.    (line 38)
                   1307: * history_expand:                        History Expansion.    (line  9)
                   1308: * history_expansion_char:                History Variables.    (line 30)
                   1309: * history_get:                           Information About the History List.
                   1310:                                                                (line 23)
                   1311: * history_get_history_state:             Initializing History and State Management.
                   1312:                                                                (line 15)
                   1313: * history_get_time:                      Information About the History List.
                   1314:                                                                (line 29)
                   1315: * history_inhibit_expansion_function:    History Variables.    (line 62)
                   1316: * history_is_stifled:                    History List Management.
                   1317:                                                                (line 47)
                   1318: * history_length:                        History Variables.    (line 13)
                   1319: * history_list:                          Information About the History List.
                   1320:                                                                (line 10)
                   1321: * history_max_entries:                   History Variables.    (line 16)
                   1322: * history_no_expand_chars:               History Variables.    (line 53)
                   1323: * history_quotes_inhibit_expansion:      History Variables.    (line 58)
                   1324: * history_search:                        Searching the History List.
                   1325:                                                                (line 13)
                   1326: * history_search_delimiter_chars:        History Variables.    (line 48)
                   1327: * history_search_pos:                    Searching the History List.
                   1328:                                                                (line 33)
                   1329: * history_search_prefix:                 Searching the History List.
                   1330:                                                                (line 23)
                   1331: * history_set_history_state:             Initializing History and State Management.
                   1332:                                                                (line 19)
                   1333: * history_set_pos:                       Moving Around the History List.
                   1334:                                                                (line 10)
                   1335: * history_subst_char:                    History Variables.    (line 34)
                   1336: * history_tokenize:                      History Expansion.    (line 39)
                   1337: * history_total_bytes:                   Information About the History List.
                   1338:                                                                (line 32)
                   1339: * history_truncate_file:                 Managing the History File.
                   1340:                                                                (line 35)
                   1341: * history_word_delimiters:               History Variables.    (line 44)
                   1342: * history_write_timestamps:              History Variables.    (line 20)
                   1343: * next_history:                          Moving Around the History List.
                   1344:                                                                (line 20)
                   1345: * previous_history:                      Moving Around the History List.
                   1346:                                                                (line 15)
                   1347: * read_history:                          Managing the History File.
                   1348:                                                                (line 10)
                   1349: * read_history_range:                    Managing the History File.
                   1350:                                                                (line 16)
                   1351: * remove_history:                        History List Management.
                   1352:                                                                (line 18)
                   1353: * replace_history_entry:                 History List Management.
                   1354:                                                                (line 29)
                   1355: * stifle_history:                        History List Management.
                   1356:                                                                (line 38)
                   1357: * unstifle_history:                      History List Management.
                   1358:                                                                (line 41)
                   1359: * using_history:                         Initializing History and State Management.
                   1360:                                                                (line 11)
                   1361: * where_history:                         Information About the History List.
                   1362:                                                                (line 15)
                   1363: * write_history:                         Managing the History File.
                   1364:                                                                (line 23)
                   1365: 
                   1366: 
                   1367: 
                   1368: Tag Table:
                   1369: Node: Top891
                   1370: Node: Using History Interactively1536
                   1371: Node: History Interaction2044
                   1372: Node: Event Designators3468
                   1373: Node: Word Designators4610
                   1374: Node: Modifiers6249
                   1375: Node: Programming with GNU History7474
                   1376: Node: Introduction to History8217
                   1377: Node: History Storage9907
                   1378: Node: History Functions11042
                   1379: Node: Initializing History and State Management12031
                   1380: Node: History List Management12843
                   1381: Node: Information About the History List14875
                   1382: Node: Moving Around the History List16372
                   1383: Node: Searching the History List17373
                   1384: Node: Managing the History File19305
                   1385: Node: History Expansion21125
                   1386: Node: History Variables23034
                   1387: Node: History Programming Example26066
                   1388: Node: GNU Free Documentation License28743
                   1389: Node: Concept Index53934
                   1390: Node: Function and Variable Index54639
                   1391: 
                   1392: End Tag Table

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>