This is internal.info, produced by makeinfo version 4.13 from
internal.texi.
This manual (24 February 2014) is for the internals of Libmarpa
5.181.101.
Copyright (C) 2014 Jeffrey Kegler.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation. A copy of the license is included in the section
entitled "GNU Free Documentation License."
File: internal.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
Libmarpa internals
******************
This manual (24 February 2014) is for the internals of Libmarpa
5.181.101.
Copyright (C) 2014 Jeffrey Kegler.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation. A copy of the license is included in the section
entitled "GNU Free Documentation License."
* Menu:
* Copying::
* About this document::
* Internal Interface::
* GNU Free Documentation License::
--- The Detailed Node Listing ---
Internal Interface
* Symbol internal methods::
* Rule internals::
* Grammar internals::
* Recognizer internals::
* Bocage internals::
* Ordering internals::
* Tree internals::
* Valuator internals::
* Debugging methods::
File: internal.info, Node: Copying, Next: About this document, Prev: Top, Up: Top
GNU LESSER GENERAL PUBLIC LICENSE
*********************************
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU
Lesser General Public License, and the "GNU GPL" refers to version
3 of the GNU General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface
provided by the Library, but which is not otherwise based on the
Library. Defining a subclass of a class defined by the Library is
deemed a mode of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the
Library with which the Combined Work was made is also called the
"Linked Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source
code for portions of the Combined Work that, considered in
isolation, are based on the Application, and not on the Linked
Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any
data and utility programs needed for reproducing the Combined Work
from the Application, but excluding the System Libraries of the
Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this
License without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an
Application that uses the facility (other than as an argument
passed when the facility is invoked), then you may convey a copy
of the modified version:
a. under this License, provided that you make a good faith
effort to ensure that, in the event an Application does not
supply the function or data, the facility still operates, and
performs whatever part of its purpose remains meaningful, or
b. under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material
from a header file that is part of the Library. You may convey
such object code under terms of your choice, provided that, if the
incorporated material is not limited to numerical parameters, data
structure layouts and accessors, or small macros, inline functions
and templates (ten or fewer lines in length), you do both of the
following:
a. Give prominent notice with each copy of the object code that
the Library is used in it and that the Library and its use are
covered by this License.
b. Accompany the object code with a copy of the GNU GPL and this
license document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each
of the following:
a. Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b. Accompany the Combined Work with a copy of the GNU GPL and
this license document.
c. For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to
the copies of the GNU GPL and this license document.
d. Do one of the following:
0. Convey the Minimal Corresponding Source under the terms
of this License, and the Corresponding Application Code
in a form suitable for, and under terms that permit, the
user to recombine or relink the Application with a
modified version of the Linked Version to produce a
modified Combined Work, in the manner specified by
section 6 of the GNU GPL for conveying Corresponding
Source.
1. Use a suitable shared library mechanism for linking with
the Library. A suitable mechanism is one that (a) uses
at run time a copy of the Library already present on the
user's computer system, and (b) will operate properly
with a modified version of the Library that is
interface-compatible with the Linked Version.
e. Provide Installation Information, but only if you would
otherwise be required to provide such information under
section 6 of the GNU GPL, and only to the extent that such
information is necessary to install and execute a modified
version of the Combined Work produced by recombining or
relinking the Application with a modified version of the
Linked Version. (If you use option 4d0, the Installation
Information must accompany the Minimal Corresponding Source
and Corresponding Application Code. If you use option 4d1,
you must provide the Installation Information in the manner
specified by section 6 of the GNU GPL for conveying
Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other
library facilities that are not Applications and are not covered
by this License, and convey such a combined library under terms of
your choice, if you do both of the following:
a. Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities, conveyed under the terms of this License.
b. Give prominent notice with the combined library that part of
it is a work based on the Library, and explaining where to
find the accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new
versions of the GNU Lesser General Public License from time to
time. Such new versions will be similar in spirit to the present
version, but may differ in detail to address new problems or
concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered
version of the GNU Lesser General Public License "or any later
version" applies to it, you have the option of following the terms
and conditions either of that published version or of any later
version published by the Free Software Foundation. If the Library
as you received it does not specify a version number of the GNU
Lesser General Public License, you may choose any version of the
GNU Lesser General Public License ever published by the Free
Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License
shall apply, that proxy's public statement of acceptance of any
version is permanent authorization for you to choose that version
for the Library.
File: internal.info, Node: About this document, Next: Internal Interface, Prev: Copying, Up: Top
1 About this document
*********************
This manual is a tool for is those working on the Libmarpa internals.
Unless you are thoroughly familiar with Libmarpa already, it is not of
interest to you.
File: internal.info, Node: Internal Interface, Next: GNU Free Documentation License, Prev: About this document, Up: Top
2 Internal Interface
********************
Internal methods are only for testing and development of libmarpa.
They are listed here (and sometimes described) for the convenience of
those working on libmarpa's internals.
Internal methods are subject to change. Applications should not use
internal methods. If a description exists and might be helpful, it may
be included below, but all applications should treat these methods as
"undocumented".
* Menu:
* Symbol internal methods::
* Rule internals::
* Grammar internals::
* Recognizer internals::
* Bocage internals::
* Ordering internals::
* Tree internals::
* Valuator internals::
* Debugging methods::
File: internal.info, Node: Symbol internal methods, Next: Rule internals, Prev: Internal Interface, Up: Internal Interface
2.1 Symbol internal methods
===========================
-- Function: int _marpa_g_rule_first_child_set ( Marpa_Grammar G,
Marpa_Rule_ID RULE_ID)
If the desired semantics is simply to return the first child as
the value (not an uncommon case) Marpa could implement that as a
stack no-op. This stub may become part of the external interface
at some point, once I fully work out the implications of "first
child" semantics.
-- Function: int _marpa_g_nsy_is_start ( Marpa_Grammar G, Marpa_NSY_ID
NSY_ID)
-- Function: int _marpa_g_nsy_is_nulling ( Marpa_Grammar G,
Marpa_NSY_ID NSY_ID)
-- Function: int _marpa_g_nsy_is_lhs ( Marpa_Grammar G, Marpa_NSY_ID
NSY_ID)
-- Function: Marpa_NSY_ID _marpa_g_xsy_nulling_nsy ( Marpa_Grammar G,
Marpa_Symbol_ID SYMID)
-- Function: Marpa_NSY_ID _marpa_g_xsy_nsy ( Marpa_Grammar G,
Marpa_Symbol_ID SYMID)
-- Function: Marpa_Symbol_ID _marpa_g_symbol_proper_alias (
Marpa_Grammar G, Marpa_Symbol_ID SYMID)
-- Function: Marpa_Symbol_ID _marpa_g_symbol_null_alias (
Marpa_Grammar G, Marpa_Symbol_ID SYMID)
-- Function: int _marpa_g_nsy_is_semantic ( Marpa_Grammar G,
Marpa_NSY_ID NSY_ID)
-- Function: Marpa_Rule_ID _marpa_g_source_xsy ( Marpa_Grammar G,
Marpa_NSY_ID NSY_ID)
-- Function: Marpa_Rule_ID _marpa_g_nsy_lhs_xrl ( Marpa_Grammar G,
Marpa_NSY_ID NSY_ID)
-- Function: int _marpa_g_nsy_xrl_offset ( Marpa_Grammar G,
Marpa_NSY_ID NSY_ID )
File: internal.info, Node: Rule internals, Next: Grammar internals, Prev: Symbol internal methods, Up: Internal Interface
2.2 Rule internals
==================
-- Function: int _marpa_g_rule_is_keep_separation ( Marpa_Grammar G,
Marpa_Rule_ID RULE_ID)
This function does nothing but return an undocumented flag. At
some point, I may optimize cases where separators are discarded,
in which case this flag will be used. I may also remove this call
entirely. Return value: Returns 1 if the keep separation flag is
set, 0 if not. Returns 0 if RULE_ID is not a sequence rule. On
failure, returns -2.
-- Function: int _marpa_g_nsy_count ( Marpa_Grammar G)
-- Function: int _marpa_g_irl_count ( Marpa_Grammar G)
-- Function: Marpa_Symbol_ID _marpa_g_irl_lhs ( Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
Return value: On success, the LHS symbol of the IRL. On failure,
-2.
-- Function: int _marpa_g_irl_length ( Marpa_Grammar G, Marpa_IRL_ID
IRL_ID)
The length of a IRL is the number of symbols on its RHS.
Return value: On success, the IRL length. On failure, -2.
-- Function: Marpa_Symbol_ID _marpa_g_irl_rhs ( Marpa_Grammar G,
Marpa_IRL_ID IRL_ID, int IX)
The position in the IRL, IX, is zero-based. If IX is greater than
or equal the length of the IRL, it is a soft failure. This can be
used in loops, to avoid having to determine the IRL's length
explicitly.
Return value: On success, the symbol in position IX on the IRL's
RHS. If IX is greater than or equal to the length of the IRL, -1.
On other failures, -2.
-- Function: int _marpa_g_rule_is_used (Marpa_Grammar G, Marpa_Rule_ID
RULE_ID)
-- Function: int _marpa_g_irl_is_virtual_lhs (Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
-- Function: int _marpa_g_irl_is_virtual_rhs (Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
-- Function: `int' _marpa_g_virtual_start (Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
-- Function: `int' _marpa_g_virtual_end (Marpa_Grammar G, Marpa_IRL_ID
IRL_ID)
-- Function: Marpa_Rule_ID _marpa_g_source_xrl (Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
-- Function: int _marpa_g_real_symbol_count (Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
-- Function: Marpa_Rule_ID _marpa_g_irl_semantic_equivalent
(Marpa_Grammar G, Marpa_IRL_ID IRL_ID)
-- Function: Marpa_Rank _marpa_g_irl_rank ( Marpa_Grammar G,
Marpa_IRL_ID IRL_ID)
-- Function: Marpa_Rank _marpa_g_nsy_rank ( Marpa_Grammar G,
Marpa_IRL_ID NSY_ID)
File: internal.info, Node: Grammar internals, Next: Recognizer internals, Prev: Rule internals, Up: Internal Interface
2.3 Grammar internal methods
============================
The methods in this section are accessors for Libmarpa's AHMs. Their
use requires familiarity with Marpa's internals, as described in
`Marpa: The Program'.
-- Function: int _marpa_g_ahm_count (Marpa_Grammar G)
-- Function: Marpa_Rule_ID _marpa_g_ahm_irl (Marpa_Grammar G,
Marpa_AHM_ID ITEM_ID)
-- Function: int _marpa_g_ahm_position (Marpa_Grammar G, Marpa_AHM_ID
ITEM_ID)
-- Function: Marpa_Symbol_ID _marpa_g_ahm_postdot (Marpa_Grammar G,
Marpa_AHM_ID ITEM_ID)
-- Function: int _marpa_g_ahm_sort_key (Marpa_Grammar G, Marpa_AHM_ID
ITEM_ID)
File: internal.info, Node: Recognizer internals, Next: Bocage internals, Prev: Grammar internals, Up: Internal Interface
2.4 Recognizer internals
========================
-- Function: int _marpa_r_is_use_leo (Marpa_Recognizer R)
-- Function: int _marpa_r_is_use_leo_set ( Marpa_Recognizer R, int
VALUE)
Reports and sets, respectively, the "use Leo" flag. This flag
controls whether Joop Leo's method for fast parsing of right
recursion is used. By default, this value is 1 and Leo parsing is
in use. This default should be used except for testing, debugging
and development.
-- Function: Marpa_Earley_Set_ID _marpa_r_trace_earley_set
(Marpa_Recognizer R)
-- Function: int _marpa_r_earley_set_size (Marpa_Recognizer r,
Marpa_Earley_Set_ID SET_ID)
-- Function: Marpa_Earleme _marpa_r_earley_set_trace (Marpa_Recognizer
r, Marpa_Earley_Set_ID SET_ID)
-- Function: Marpa_AHM_ID _marpa_r_earley_item_trace (Marpa_Recognizer
r, Marpa_Earley_Item_ID ITEM_ID)
-- Function: Marpa_Earley_Set_ID _marpa_r_earley_item_origin
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_leo_predecessor_symbol
(Marpa_Recognizer R)
-- Function: Marpa_Earley_Set_ID _marpa_r_leo_base_origin
(Marpa_Recognizer R)
-- Function: Marpa_AHM_ID _marpa_r_leo_base_state (Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_postdot_symbol_trace
(Marpa_Recognizer r, Marpa_Symbol_ID SYMID)
-- Function: Marpa_Symbol_ID _marpa_r_first_postdot_item_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_next_postdot_item_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_postdot_item_symbol
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_first_token_link_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_next_token_link_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_first_completion_link_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_next_completion_link_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_first_leo_link_trace
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_next_leo_link_trace
(Marpa_Recognizer R)
-- Function: Marpa_AHM_ID _marpa_r_source_predecessor_state
(Marpa_Recognizer R)
-- Function: Marpa_Symbol_ID _marpa_r_source_token (Marpa_Recognizer
r, int *VALUE_P)
-- Function: Marpa_Symbol_ID _marpa_r_source_leo_transition_symbol
(Marpa_Recognizer R)
-- Function: Marpa_Earley_Set_ID _marpa_r_source_middle
(Marpa_Recognizer R)
File: internal.info, Node: Bocage internals, Next: Ordering internals, Prev: Recognizer internals, Up: Internal Interface
2.5 Bocage internals
====================
-- Function: int _marpa_b_and_node_count ( Marpa_Bocage B)
-- Function: Marpa_Earley_Set_ID _marpa_b_and_node_middle (
Marpa_Bocage B, Marpa_And_Node_ID AND_NODE_ID)
-- Function: int _marpa_b_and_node_parent ( Marpa_Bocage B,
Marpa_And_Node_ID AND_NODE_ID)
-- Function: int _marpa_b_and_node_predecessor ( Marpa_Bocage B,
Marpa_And_Node_ID AND_NODE_ID)
-- Function: int _marpa_b_and_node_cause ( Marpa_Bocage B,
Marpa_And_Node_ID AND_NODE_ID)
-- Function: int _marpa_b_and_node_symbol ( Marpa_Bocage B,
Marpa_And_Node_ID AND_NODE_ID)
-- Function: Marpa_Symbol_ID _marpa_b_and_node_token ( Marpa_Bocage B,
Marpa_And_Node_ID AND_NODE_ID, int* VALUE_P)
Returns the data for the token of the and-node. The symbol id is
the return value, and the token value is placed in the location
pointed to by VALUE_P, if that is non-null. If AND_NODE_ID is not
the ID of an and-node whose cause is a token, returns -1, without
changing VALUE_P. On failure, returns -2 without changing VALUE_P.
There is no function to simply return the token value - because of
the need to indicate errors, it is just as easy to return the
symbol ID as well.
-- Function: Marpa_Or_Node_ID _marpa_b_top_or_node ( Marpa_Bocage B)
Return the ID of the top or-node.
-- Function: int _marpa_b_or_node_set ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
Return the ordinal of the current (final) Earley set of the
or-node.
-- Function: int _marpa_b_or_node_origin ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: Marpa_IRL_ID _marpa_b_or_node_irl ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_b_or_node_position ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_b_or_node_is_whole ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_b_or_node_is_semantic ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_b_or_node_first_and ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_b_or_node_last_and ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_b_or_node_and_count ( Marpa_Bocage B,
Marpa_Or_Node_ID OR_NODE_ID)
File: internal.info, Node: Ordering internals, Next: Tree internals, Prev: Bocage internals, Up: Internal Interface
2.6 Ordering internals
======================
-- Function: Marpa_And_Node_ID _marpa_o_and_order_get ( Marpa_Order O,
Marpa_Or_Node_ID OR_NODE_ID, int IX)
-- Function: int _marpa_o_or_node_and_node_count ( Marpa_Order O,
Marpa_Or_Node_ID OR_NODE_ID)
-- Function: int _marpa_o_or_node_and_node_id_by_ix ( Marpa_Order O,
Marpa_Or_Node_ID OR_NODE_ID, int IX)
File: internal.info, Node: Tree internals, Next: Valuator internals, Prev: Ordering internals, Up: Internal Interface
2.7 Tree internals
==================
In Marpa, a nook is any node of a parse tree. The usual term is "node",
but within Marpa, the word "node" is already heavily overloaded. So
what most texts call "tree nodes" are here called "nooks". "Nook" can
be thought of as a pun on both "node" and "fork".
-- Function: int _marpa_t_size ( Marpa_Tree T)
Return the size of the parse tree. This is the number of nooks in
its stack. If there is a serious error, or if the tree is
uninitialized, return -2. If the tree is exhausted, return -1.
-- Function: Marpa_Or_Node_ID _marpa_t_nook_or_node ( Marpa_Tree T,
Marpa_Nook_ID NOOK_ID)
Return the ID of the or-node for NOOK_ID.
-- Function: int _marpa_t_nook_choice ( Marpa_Tree T, Marpa_Nook_ID
NOOK_ID )
Return the current choice for NOOK_ID.
-- Function: int _marpa_t_nook_parent ( Marpa_Tree T, Marpa_Nook_ID
NOOK_ID )
Return the parent nook's ID for NOOK_ID. As with the other nook
trace functions, -1 is returned if NOOK_ID is not the ID of a nook
on the stack, but -1 can also be a valid value. If that's an
issue, the NOOK_ID needs to be checked with one of the trace
functions where -1 is never a valid value -- for example,
`_marpa_t_nook_or_node'.
-- Function: int _marpa_t_nook_cause_is_ready ( Marpa_Tree T,
Marpa_Nook_ID NOOK_ID )
Return the cause-is-ready bit for NOOK_ID.
-- Function: int _marpa_t_nook_predecessor_is_ready ( Marpa_Tree T,
Marpa_Nook_ID NOOK_ID )
Return the predecessor-is-ready bit for NOOK_ID.
-- Function: int _marpa_t_nook_is_cause ( Marpa_Tree T, Marpa_Nook_ID
NOOK_ID )
Return the is-cause bit for NOOK_ID.
-- Function: int _marpa_t_nook_is_predecessor ( Marpa_Tree T,
Marpa_Nook_ID NOOK_ID )
Return the is-predecessor bit for NOOK_ID.
File: internal.info, Node: Valuator internals, Next: Debugging methods, Prev: Tree internals, Up: Internal Interface
2.8 Valuator internals
======================
-- Function: int _marpa_v_trace ( Marpa_Value V, int FLAG)
-- Function: Marpa_Nook_ID _marpa_v_nook ( Marpa_Value V)
File: internal.info, Node: Debugging methods, Prev: Valuator internals, Up: Internal Interface
2.9 Debugging methods
=====================
-- Function: int marpa_debug_level_set ( int LEVEL )
-- Function: void marpa_debug_handler_set ( int (*DEBUG_HANDLER)(const
char*, ...) )
File: internal.info, Node: GNU Free Documentation License, Prev: Internal Interface, Up: Top
Appendix A GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
`http://fsf.org/'
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book.
We recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it
can be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You
accept the license if you copy, modify or distribute the work in a
way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in
the notice that says that the Document is released under this
License. If a section does not fit the above definition of
Secondary then it is not allowed to be designated as Invariant.
The Document may contain zero Invariant Sections. If the Document
does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images
composed of pixels) generic paint programs or (for drawings) some
widely available drawing editor, and that is suitable for input to
text formatters or for automatic translation to a variety of
formats suitable for input to text formatters. A copy made in an
otherwise Transparent file format whose markup, or absence of
markup, has been arranged to thwart or discourage subsequent
modification by readers is not Transparent. An image format is
not Transparent if used for any substantial amount of text. A
copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and
standard-conforming simple HTML, PostScript or PDF designed for
human modification. Examples of transparent image formats include
PNG, XCF and JPG. Opaque formats include proprietary formats that
can be read and edited only by proprietary word processors, SGML or
XML for which the DTD and/or processing tools are not generally
available, and the machine-generated HTML, PostScript or PDF
produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow
the conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the
title equally prominent and visible. You may add other material
on the covers in addition. Copying with changes limited to the
covers, as long as they preserve the title of the Document and
satisfy these conditions, can be treated as verbatim copying in
other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or
state in or with each Opaque copy a computer-network location from
which the general network-using public has access to download
using public-standard network protocols a complete Transparent
copy of the Document, free of added material. If you use the
latter option, you must take reasonably prudent steps, when you
begin distribution of Opaque copies in quantity, to ensure that
this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you
distribute an Opaque copy (directly or through your agents or
retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of
copies, to give them a chance to provide you with an updated
version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with
the Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version to
whoever possesses a copy of it. In addition, you must do these
things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of
previous versions (which should, if there were any, be listed
in the History section of the Document). You may use the
same title as a previous version if the original publisher of
that version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on
the Title Page. If there is no section Entitled "History" in
the Document, create one stating the title, year, authors,
and publisher of the Document as given on its Title Page,
then add an item describing the Modified Version as stated in
the previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in
the "History" section. You may omit a network location for a
work that was published at least four years before the
Document itself, or if the original publisher of the version
it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the
section all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section
titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option
designate some or all of these sections as invariant. To do this,
add their titles to the list of Invariant Sections in the Modified
Version's license notice. These titles must be distinct from any
other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end
of the list of Cover Texts in the Modified Version. Only one
passage of Front-Cover Text and one of Back-Cover Text may be
added by (or through arrangements made by) any one entity. If the
Document already includes a cover text for the same cover,
previously added by you or by arrangement made by the same entity
you are acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination
all of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow
this License in all other respects regarding verbatim copying of
that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of
a storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly
and finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from
you under this License. If your rights have been terminated and
not permanently reinstated, receipt of a copy of some or all of
the same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
`http://www.gnu.org/copyleft/'.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by the
Free Software Foundation. If the Document specifies that a proxy
can decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.
Tag Table:
Node: Top513
Node: Copying1427
Node: About this document9863
Node: Internal Interface10171
Node: Symbol internal methods10961
Node: Rule internals12635
Node: Grammar internals15257
Node: Recognizer internals16036
Node: Bocage internals18781
Node: Ordering internals21306
Node: Tree internals21821
Node: Valuator internals23829
Node: Debugging methods24121
Node: GNU Free Documentation License24419
End Tag Table