Initial conversion to Sphinx generated documentation.

There are still many bugs in the documentation strings, but at least genration of documentaiton works.
author: Matěj Cepl <mcepl@cepl.eu> 2018-11-20 09:55:47 +0100
committer: Matěj Cepl <mcepl@cepl.eu> 2018-11-20 10:01:02 +0100
commit: a0b490366a2f218f111eb4c770bab2f0b9cce19c (patch)
tree: 45a7a53727dd3c219ad8c1a66336a8db23bf9628
parent: eb43d95fde4c967b0ce24b0faa082aa70e2a720b (diff)
download: pyparsing-git-a0b490366a2f218f111eb4c770bab2f0b9cce19c.tar.gz
18 files changed, 830 insertions, 1694 deletions
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
deleted file mode 100644
index 2128b0f..0000000
--- a/CODE_OF_CONDUCT.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, sex characteristics, gender identity and expression,
-level of experience, education, socio-economic status, nationality, personal
-appearance, race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-  advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at pyparsing@mail.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
-
diff --git a/CODE_OF_CONDUCT.rst b/CODE_OF_CONDUCT.rst
new file mode 100644
index 0000000..fe3f47a
--- /dev/null
+++ b/CODE_OF_CONDUCT.rst
@@ -0,0 +1,90 @@
+Contributor Covenant Code of Conduct 
+==================================== 
+ 
+Our Pledge 
+---------- 
+ 
+In the interest of fostering an open and welcoming environment, 
+we as contributors and maintainers pledge to making participation 
+in our project and our community a harassment-free experience for 
+everyone, regardless of age, body size, disability, ethnicity, 
+sex characteristics, gender identity and expression, level of 
+experience, education, socio-economic status, nationality, 
+personal appearance, race, religion, or sexual identity and 
+orientation. 
+ 
+Our Standards 
+------------- 
+ 
+Examples of behavior that contributes to creating a positive 
+environment include: 
+ 
+-  Using welcoming and inclusive language 
+-  Being respectful of differing viewpoints and experiences 
+-  Gracefully accepting constructive criticism 
+-  Focusing on what is best for the community 
+-  Showing empathy towards other community members 
+ 
+Examples of unacceptable behavior by participants include: 
+ 
+-  The use of sexualized language or imagery and unwelcome sexual 
+   attention or advances 
+-  Trolling, insulting/derogatory comments, and personal or political 
+   attacks 
+-  Public or private harassment 
+-  Publishing others’ private information, such as a physical or 
+   electronic address, without explicit permission 
+-  Other conduct which could reasonably be considered 
+   inappropriate in a professional setting 
+ 
+Our Responsibilities 
+-------------------- 
+ 
+Project maintainers are responsible for clarifying the standards 
+of acceptable behavior and are expected to take appropriate and 
+fair corrective action in response to any instances of 
+unacceptable behavior. 
+ 
+Project maintainers have the right and responsibility to remove, 
+edit, or reject comments, commits, code, wiki edits, issues, and 
+other contributions that are not aligned to this Code of Conduct, 
+or to ban temporarily or permanently any contributor for other 
+behaviors that they deem inappropriate, threatening, offensive, 
+or harmful. 
+ 
+Scope 
+----- 
+ 
+This Code of Conduct applies both within project spaces and in 
+public spaces when an individual is representing the project or 
+its community. Examples of representing a project or community 
+include using an official project e-mail address, posting via an 
+official social media account, or acting as an appointed 
+representative at an online or offline event. Representation of 
+a project may be further defined and clarified by project 
+maintainers. 
+ 
+Enforcement 
+----------- 
+ 
+Instances of abusive, harassing, or otherwise unacceptable 
+behavior may be reported by contacting the project team at 
+pyparsing@mail.com. All complaints will be reviewed and 
+investigated and will result in a response that is deemed 
+necessary and appropriate to the circumstances. The project team 
+is obligated to maintain confidentiality with regard to the 
+reporter of an incident. Further details of specific enforcement 
+policies may be posted separately. 
+ 
+Project maintainers who do not follow or enforce the Code of 
+Conduct in good faith may face temporary or permanent 
+repercussions as determined by other members of the project’s 
+leadership. 
+ 
+Attribution 
+----------- 
+ 
+This Code of Conduct is adapted from the `Contributor Covenant 
+<https://www.contributor-covenant.org>`__, version 1.4, available 
+at 
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 
diff --git a/HowToUsePyparsing.html b/HowToUsePyparsing.html
deleted file mode 100644
index 1bd180b..0000000
--- a/HowToUsePyparsing.html
+++ /dev/null
@@ -1,1289 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.8: http://docutils.sourceforge.net/" />
-<title>Using the pyparsing module</title>
-<meta name="author" content="Paul McGuire" />
-<meta name="date" content="June, 2011" />
-<meta name="copyright" content="Copyright © 2003-2011 Paul McGuire." />
-<style type="text/css">
-
-/*
-:Author: David Goodger (goodger@python.org)
-:Id: $Id: html4css1.css 6387 2010-08-13 12:23:41Z milde $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
-*/
-
-/* used to remove borders from tables and images */
-.borderless, table.borderless td, table.borderless th {
-  border: 0 }
-
-table.borderless td, table.borderless th {
-  /* Override padding for "table.docutils td" with "! important".
-     The right padding separates the table cells. */
-  padding: 0 0.5em 0 0 ! important }
-
-.first {
-  /* Override more specific margin styles with "! important". */
-  margin-top: 0 ! important }
-
-.last, .with-subtitle {
-  margin-bottom: 0 ! important }
-
-.hidden {
-  display: none }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-blockquote.epigraph {
-  margin: 2em 5em ; }
-
-dl.docutils dd {
-  margin-bottom: 0.5em }
-
-object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
-  overflow: hidden;
-}
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
-  font-weight: bold }
-*/
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
-   compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
-  margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
-  margin-top: 0.5em }
-*/
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-div.footer, div.header {
-  clear: both;
-  font-size: smaller }
-
-div.line-block {
-  display: block ;
-  margin-top: 1em ;
-  margin-bottom: 1em }
-
-div.line-block div.line-block {
-  margin-top: 0 ;
-  margin-bottom: 0 ;
-  margin-left: 1.5em }
-
-div.sidebar {
-  margin: 0 0 0.5em 1em ;
-  border: medium outset ;
-  padding: 1em ;
-  background-color: #ffffee ;
-  width: 40% ;
-  float: right ;
-  clear: right }
-
-div.sidebar p.rubric {
-  font-family: sans-serif ;
-  font-size: medium }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
-  margin-top: 0.4em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr.docutils {
-  width: 75% }
-
-img.align-left, .figure.align-left, object.align-left {
-  clear: left ;
-  float: left ;
-  margin-right: 1em }
-
-img.align-right, .figure.align-right, object.align-right {
-  clear: right ;
-  float: right ;
-  margin-left: 1em }
-
-img.align-center, .figure.align-center, object.align-center {
-  display: block;
-  margin-left: auto;
-  margin-right: auto;
-}
-
-.align-left {
-  text-align: left }
-
-.align-center {
-  clear: both ;
-  text-align: center }
-
-.align-right {
-  text-align: right }
-
-/* reset inner alignment in figures */
-div.align-right {
-  text-align: left }
-
-/* div.align-center * { */
-/*   text-align: left } */
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.attribution {
-  text-align: right ;
-  margin-left: 50% }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.rubric {
-  font-weight: bold ;
-  font-size: larger ;
-  color: maroon ;
-  text-align: center }
-
-p.sidebar-title {
-  font-family: sans-serif ;
-  font-weight: bold ;
-  font-size: larger }
-
-p.sidebar-subtitle {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font: inherit }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option {
-  white-space: nowrap }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-span.section-subtitle {
-  /* font-size relative to parent (h1..h6 element) */
-  font-size: 80% }
-
-table.citation {
-  border-left: solid 1px gray;
-  margin-left: 1px }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.docutils {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.footnote {
-  border-left: solid 1px black;
-  margin-left: 1px }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-table.docutils th.field-name, table.docinfo th.docinfo-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap ;
-  padding-left: 0 }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
-  font-size: 100% }
-
-ul.auto-toc {
-  list-style-type: none }
-
-</style>
-</head>
-<body>
-<div class="document" id="using-the-pyparsing-module">
-<h1 class="title">Using the pyparsing module</h1>
-<table class="docinfo" frame="void" rules="none">
-<col class="docinfo-name" />
-<col class="docinfo-content" />
-<tbody valign="top">
-<tr><th class="docinfo-name">Author:</th>
-<td>Paul McGuire</td></tr>
-<tr><th class="docinfo-name">Address:</th>
-<td><pre class="address">
-<a class="first last reference external" href="mailto:ptmcg&#64;users.sourceforge.net">ptmcg&#64;users.sourceforge.net</a>
-</pre>
-</td></tr>
-<tr><th class="docinfo-name">Revision:</th>
-<td>2.0.1</td></tr>
-<tr><th class="docinfo-name">Date:</th>
-<td>July, 2013</td></tr>
-<tr><th class="docinfo-name">Copyright:</th>
-<td>Copyright © 2003-2013 Paul McGuire.</td></tr>
-</tbody>
-</table>
-<table class="docutils field-list" frame="void" rules="none">
-<col class="field-name" />
-<col class="field-body" />
-<tbody valign="top">
-<tr class="field"><th class="field-name">abstract:</th><td class="field-body">This document provides how-to instructions for the
-pyparsing library, an easy-to-use Python module for constructing
-and executing basic text parsers.  The pyparsing module is useful
-for evaluating user-definable
-expressions, processing custom application language commands, or
-extracting data from formatted reports.</td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="contents">
-<p class="topic-title first">Contents</p>
-<ul class="auto-toc simple">
-<li><a class="reference internal" href="#steps-to-follow" id="id1">1&nbsp;&nbsp;&nbsp;Steps to follow</a><ul class="auto-toc">
-<li><a class="reference internal" href="#hello-world" id="id2">1.1&nbsp;&nbsp;&nbsp;Hello, World!</a></li>
-<li><a class="reference internal" href="#usage-notes" id="id3">1.2&nbsp;&nbsp;&nbsp;Usage notes</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#classes" id="id4">2&nbsp;&nbsp;&nbsp;Classes</a><ul class="auto-toc">
-<li><a class="reference internal" href="#classes-in-the-pyparsing-module" id="id5">2.1&nbsp;&nbsp;&nbsp;Classes in the pyparsing module</a></li>
-<li><a class="reference internal" href="#basic-parserelement-subclasses" id="id6">2.2&nbsp;&nbsp;&nbsp;Basic ParserElement subclasses</a></li>
-<li><a class="reference internal" href="#expression-subclasses" id="id7">2.3&nbsp;&nbsp;&nbsp;Expression subclasses</a></li>
-<li><a class="reference internal" href="#expression-operators" id="id8">2.4&nbsp;&nbsp;&nbsp;Expression operators</a></li>
-<li><a class="reference internal" href="#positional-subclasses" id="id9">2.5&nbsp;&nbsp;&nbsp;Positional subclasses</a></li>
-<li><a class="reference internal" href="#converter-subclasses" id="id10">2.6&nbsp;&nbsp;&nbsp;Converter subclasses</a></li>
-<li><a class="reference internal" href="#special-subclasses" id="id11">2.7&nbsp;&nbsp;&nbsp;Special subclasses</a></li>
-<li><a class="reference internal" href="#other-classes" id="id12">2.8&nbsp;&nbsp;&nbsp;Other classes</a></li>
-<li><a class="reference internal" href="#exception-classes-and-troubleshooting" id="id13">2.9&nbsp;&nbsp;&nbsp;Exception classes and Troubleshooting</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#miscellaneous-attributes-and-methods" id="id14">3&nbsp;&nbsp;&nbsp;Miscellaneous attributes and methods</a><ul class="auto-toc">
-<li><a class="reference internal" href="#helper-methods" id="id15">3.1&nbsp;&nbsp;&nbsp;Helper methods</a></li>
-<li><a class="reference internal" href="#helper-parse-actions" id="id16">3.2&nbsp;&nbsp;&nbsp;Helper parse actions</a></li>
-<li><a class="reference internal" href="#common-string-and-token-constants" id="id17">3.3&nbsp;&nbsp;&nbsp;Common string and token constants</a></li>
-</ul>
-</li>
-</ul>
-</div>
-<div class="section" id="steps-to-follow">
-<h1><a class="toc-backref" href="#id1">1&nbsp;&nbsp;&nbsp;Steps to follow</a></h1>
-<p>To parse an incoming data string, the client code must follow these steps:</p>
-<ol class="arabic simple">
-<li>First define the tokens and patterns to be matched, and assign
-this to a program variable.  Optional results names or parsing
-actions can also be defined at this time.</li>
-<li>Call <tt class="docutils literal">parseString()</tt> or <tt class="docutils literal">scanString()</tt> on this variable, passing in
-the string to
-be parsed.  During the matching process, whitespace between
-tokens is skipped by default (although this can be changed).
-When token matches occur, any defined parse action methods are
-called.</li>
-<li>Process the parsed results, returned as a list of strings.
-Matching results may also be accessed as named attributes of
-the returned results, if names are defined in the definition of
-the token pattern, using <tt class="docutils literal">setResultsName()</tt>.</li>
-</ol>
-<div class="section" id="hello-world">
-<h2><a class="toc-backref" href="#id2">1.1&nbsp;&nbsp;&nbsp;Hello, World!</a></h2>
-<p>The following complete Python program will parse the greeting &quot;Hello, World!&quot;,
-or any other greeting of the form &quot;&lt;salutation&gt;, &lt;addressee&gt;!&quot;:</p>
-<pre class="literal-block">
-from pyparsing import Word, alphas
-
-greet = Word( alphas ) + &quot;,&quot; + Word( alphas ) + &quot;!&quot;
-greeting = greet.parseString( &quot;Hello, World!&quot; )
-print greeting
-</pre>
-<p>The parsed tokens are returned in the following form:</p>
-<pre class="literal-block">
-['Hello', ',', 'World', '!']
-</pre>
-</div>
-<div class="section" id="usage-notes">
-<h2><a class="toc-backref" href="#id3">1.2&nbsp;&nbsp;&nbsp;Usage notes</a></h2>
-<ul>
-<li><p class="first">The pyparsing module can be used to interpret simple command
-strings or algebraic expressions, or can be used to extract data
-from text reports with complicated format and structure (&quot;screen
-or report scraping&quot;).  However, it is possible that your defined
-matching patterns may accept invalid inputs.  Use pyparsing to
-extract data from strings assumed to be well-formatted.</p>
-</li>
-<li><p class="first">To keep up the readability of your code, use <a class="reference internal" href="#operators">operators</a>  such as <tt class="docutils literal">+</tt>, <tt class="docutils literal">|</tt>,
-<tt class="docutils literal">^</tt>, and <tt class="docutils literal">~</tt> to combine expressions.  You can also combine
-string literals with ParseExpressions - they will be
-automatically converted to Literal objects.  For example:</p>
-<pre class="literal-block">
-integer  = Word( nums )            # simple unsigned integer
-variable = Word( alphas, max=1 )   # single letter variable, such as x, z, m, etc.
-arithOp  = Word( &quot;+-*/&quot;, max=1 )   # arithmetic operators
-equation = variable + &quot;=&quot; + integer + arithOp + integer    # will match &quot;x=2+2&quot;, etc.
-</pre>
-<p>In the definition of <tt class="docutils literal">equation</tt>, the string <tt class="docutils literal">&quot;=&quot;</tt> will get added as
-a <tt class="docutils literal"><span class="pre">Literal(&quot;=&quot;)</span></tt>, but in a more readable way.</p>
-</li>
-<li><p class="first">The pyparsing module's default behavior is to ignore whitespace.  This is the
-case for 99% of all parsers ever written.  This allows you to write simple, clean,
-grammars, such as the above <tt class="docutils literal">equation</tt>, without having to clutter it up with
-extraneous <tt class="docutils literal">ws</tt> markers.  The <tt class="docutils literal">equation</tt> grammar will successfully parse all of the
-following statements:</p>
-<pre class="literal-block">
-x=2+2
-x = 2+2
-a = 10   *   4
-r= 1234/ 100000
-</pre>
-<p>Of course, it is quite simple to extend this example to support more elaborate expressions, with
-nesting with parentheses, floating point numbers, scientific notation, and named constants
-(such as <tt class="docutils literal">e</tt> or <tt class="docutils literal">pi</tt>).  See <tt class="docutils literal">fourFn.py</tt>, included in the examples directory.</p>
-</li>
-<li><p class="first">To modify pyparsing's default whitespace skipping, you can use one or
-more of the following methods:</p>
-<ul>
-<li><p class="first">use the static method <tt class="docutils literal">ParserElement.setDefaultWhitespaceChars</tt>
-to override the normal set of whitespace chars (' tn').  For instance
-when defining a grammar in which newlines are significant, you should
-call <tt class="docutils literal">ParserElement.setDefaultWhitespaceChars(' \t')</tt> to remove
-newline from the set of skippable whitespace characters.  Calling
-this method will affect all pyparsing expressions defined afterward.</p>
-</li>
-<li><p class="first">call <tt class="docutils literal">leaveWhitespace()</tt> on individual expressions, to suppress the
-skipping of whitespace before trying to match the expression</p>
-</li>
-<li><p class="first">use <tt class="docutils literal">Combine</tt> to require that successive expressions must be
-adjacent in the input string.  For instance, this expression:</p>
-<pre class="literal-block">
-real = Word(nums) + '.' + Word(nums)
-</pre>
-<p>will match &quot;3.14159&quot;, but will also match &quot;3 . 12&quot;.  It will also
-return the matched results as ['3', '.', '14159'].  By changing this
-expression to:</p>
-<pre class="literal-block">
-real = Combine( Word(nums) + '.' + Word(nums) )
-</pre>
-<p>it will not match numbers with embedded spaces, and it will return a
-single concatenated string '3.14159' as the parsed token.</p>
-</li>
-</ul>
-</li>
-<li><p class="first">Repetition of expressions can be indicated using the '*' operator.  An
-expression may be multiplied by an integer value (to indicate an exact
-repetition count), or by a tuple containing
-two integers, or None and an integer, representing min and max repetitions
-(with None representing no min or no max, depending whether it is the first or
-second tuple element).  See the following examples, where n is used to
-indicate an integer value:</p>
-<ul class="simple">
-<li><tt class="docutils literal">expr*3</tt> is equivalent to <tt class="docutils literal">expr + expr + expr</tt></li>
-<li><tt class="docutils literal"><span class="pre">expr*(2,3)</span></tt> is equivalent to <tt class="docutils literal">expr + expr + Optional(expr)</tt></li>
-<li><tt class="docutils literal"><span class="pre">expr*(n,None)</span></tt> or <tt class="docutils literal"><span class="pre">expr*(n,)</span></tt> is equivalent
-to <tt class="docutils literal">expr*n + ZeroOrMore(expr)</tt> (read as &quot;at least n instances of expr&quot;)</li>
-<li><tt class="docutils literal"><span class="pre">expr*(None,n)</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">expr*(0,n)</span></tt>
-(read as &quot;0 to n instances of expr&quot;)</li>
-<li><tt class="docutils literal"><span class="pre">expr*(None,None)</span></tt> is equivalent to <tt class="docutils literal">ZeroOrMore(expr)</tt></li>
-<li><tt class="docutils literal"><span class="pre">expr*(1,None)</span></tt> is equivalent to <tt class="docutils literal">OneOrMore(expr)</tt></li>
-</ul>
-<p>Note that <tt class="docutils literal"><span class="pre">expr*(None,n)</span></tt> does not raise an exception if
-more than n exprs exist in the input stream; that is,
-<tt class="docutils literal"><span class="pre">expr*(None,n)</span></tt> does not enforce a maximum number of expr
-occurrences.  If this behavior is desired, then write
-<tt class="docutils literal"><span class="pre">expr*(None,n)</span> + ~expr</tt>.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">MatchFirst</tt> expressions are matched left-to-right, and the first
-match found will skip all later expressions within, so be sure
-to define less-specific patterns after more-specific patterns.
-If you are not sure which expressions are most specific, use Or
-expressions (defined using the <tt class="docutils literal">^</tt> operator) - they will always
-match the longest expression, although they are more
-compute-intensive.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">Or</tt> expressions will evaluate all of the specified subexpressions
-to determine which is the &quot;best&quot; match, that is, which matches
-the longest string in the input data.  In case of a tie, the
-left-most expression in the <tt class="docutils literal">Or</tt> list will win.</p>
-</li>
-<li><p class="first">If parsing the contents of an entire file, pass it to the
-<tt class="docutils literal">parseFile</tt> method using:</p>
-<pre class="literal-block">
-expr.parseFile( sourceFile )
-</pre>
-</li>
-<li><p class="first"><tt class="docutils literal">ParseExceptions</tt> will report the location where an expected token
-or expression failed to match.  For example, if we tried to use our
-&quot;Hello, World!&quot; parser to parse &quot;Hello World!&quot; (leaving out the separating
-comma), we would get an exception, with the message:</p>
-<pre class="literal-block">
-pyparsing.ParseException: Expected &quot;,&quot; (6), (1,7)
-</pre>
-<p>In the case of complex
-expressions, the reported location may not be exactly where you
-would expect.  See more information under <a class="reference internal" href="#parseexception">ParseException</a> .</p>
-</li>
-<li><p class="first">Use the <tt class="docutils literal">Group</tt> class to enclose logical groups of tokens within a
-sublist.  This will help organize your results into more
-hierarchical form (the default behavior is to return matching
-tokens as a flat list of matching input strings).</p>
-</li>
-<li><p class="first">Punctuation may be significant for matching, but is rarely of
-much interest in the parsed results.  Use the <tt class="docutils literal">suppress()</tt> method
-to keep these tokens from cluttering up your returned lists of
-tokens.  For example, <tt class="docutils literal">delimitedList()</tt> matches a succession of
-one or more expressions, separated by delimiters (commas by
-default), but only returns a list of the actual expressions -
-the delimiters are used for parsing, but are suppressed from the
-returned output.</p>
-</li>
-<li><p class="first">Parse actions can be used to convert values from strings to
-other data types (ints, floats, booleans, etc.).</p>
-</li>
-<li><p class="first">Results names are recommended for retrieving tokens from complex
-expressions.  It is much easier to access a token using its field
-name than using a positional index, especially if the expression
-contains optional elements.  You can also shortcut
-the <tt class="docutils literal">setResultsName</tt> call:</p>
-<pre class="literal-block">
-stats = &quot;AVE:&quot; + realNum.setResultsName(&quot;average&quot;) + \
-        &quot;MIN:&quot; + realNum.setResultsName(&quot;min&quot;) + \
-        &quot;MAX:&quot; + realNum.setResultsName(&quot;max&quot;)
-</pre>
-<p>can now be written as this:</p>
-<pre class="literal-block">
-stats = &quot;AVE:&quot; + realNum(&quot;average&quot;) + \
-        &quot;MIN:&quot; + realNum(&quot;min&quot;) + \
-        &quot;MAX:&quot; + realNum(&quot;max&quot;)
-</pre>
-</li>
-<li><p class="first">Be careful when defining parse actions that modify global variables or
-data structures (as in <tt class="docutils literal">fourFn.py</tt>), especially for low level tokens
-or expressions that may occur within an <tt class="docutils literal">And</tt> expression; an early element
-of an <tt class="docutils literal">And</tt> may match, but the overall expression may fail.</p>
-</li>
-<li><p class="first">Performance of pyparsing may be slow for complex grammars and/or large
-input strings.  The <a class="reference external" href="http://psyco.sourceforge.net/">psyco</a> package can be used to improve the speed of the
-pyparsing module with no changes to grammar or program logic - observed
-improvments have been in the 20-50% range.</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="section" id="classes">
-<h1><a class="toc-backref" href="#id4">2&nbsp;&nbsp;&nbsp;Classes</a></h1>
-<div class="section" id="classes-in-the-pyparsing-module">
-<h2><a class="toc-backref" href="#id5">2.1&nbsp;&nbsp;&nbsp;Classes in the pyparsing module</a></h2>
-<p><tt class="docutils literal">ParserElement</tt> - abstract base class for all pyparsing classes;
-methods for code to use are:</p>
-<ul>
-<li><p class="first"><tt class="docutils literal">parseString( sourceString, parseAll=False )</tt> - only called once, on the overall
-matching pattern; returns a <a class="reference internal" href="#parseresults">ParseResults</a> object that makes the
-matched tokens available as a list, and optionally as a dictionary,
-or as an object with named attributes; if parseAll is set to True, then
-parseString will raise a ParseException if the grammar does not process
-the complete input string.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">parseFile( sourceFile )</tt> - a convenience function, that accepts an
-input file object or filename.  The file contents are passed as a
-string to <tt class="docutils literal">parseString()</tt>.  <tt class="docutils literal">parseFile</tt> also supports the <tt class="docutils literal">parseAll</tt> argument.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">scanString( sourceString )</tt> - generator function, used to find and
-extract matching text in the given source string; for each matched text,
-returns a tuple of:</p>
-<ul class="simple">
-<li>matched tokens (packaged as a <a class="reference internal" href="#parseresults">ParseResults</a> object)</li>
-<li>start location of the matched text in the given source string</li>
-<li>end location in the given source string</li>
-</ul>
-<p><tt class="docutils literal">scanString</tt> allows you to scan through the input source string for
-random matches, instead of exhaustively defining the grammar for the entire
-source text (as would be required with <tt class="docutils literal">parseString</tt>).</p>
-</li>
-<li><p class="first"><tt class="docutils literal">transformString( sourceString )</tt> - convenience wrapper function for
-<tt class="docutils literal">scanString</tt>, to process the input source string, and replace matching
-text with the tokens returned from parse actions defined in the grammar
-(see <a class="reference internal" href="#setparseaction">setParseAction</a>).</p>
-</li>
-<li><p class="first"><tt class="docutils literal">searchString( sourceString )</tt> - another convenience wrapper function for
-<tt class="docutils literal">scanString</tt>, returns a list of the matching tokens returned from each
-call to <tt class="docutils literal">scanString</tt>.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">setName( name )</tt> - associate a short descriptive name for this
-element, useful in displaying exceptions and trace information</p>
-</li>
-<li><p class="first"><tt class="docutils literal">setResultsName( string, listAllMatches=False )</tt> - name to be given
-to tokens matching
-the element; if multiple tokens within
-a repetition group (such as <tt class="docutils literal">ZeroOrMore</tt> or <tt class="docutils literal">delimitedList</tt>) the
-default is to return only the last matching token - if listAllMatches
-is set to True, then a list of all the matching tokens is returned.
-(New in 1.5.6 - a results name with a trailing '*' character will be
-interpreted as setting listAllMatches to True.)
-Note:
-<tt class="docutils literal">setResultsName</tt> returns a <em>copy</em> of the element so that a single
-basic element can be referenced multiple times and given
-different names within a complex grammar.</p>
-</li>
-</ul>
-<ul id="setparseaction">
-<li><p class="first"><tt class="docutils literal">setParseAction( *fn )</tt> - specify one or more functions to call after successful
-matching of the element; each function is defined as <tt class="docutils literal">fn( s,
-loc, toks )</tt>, where:</p>
-<ul class="simple">
-<li><tt class="docutils literal">s</tt> is the original parse string</li>
-<li><tt class="docutils literal">loc</tt> is the location in the string where matching started</li>
-<li><tt class="docutils literal">toks</tt> is the list of the matched tokens, packaged as a <a class="reference internal" href="#parseresults">ParseResults</a> object</li>
-</ul>
-<p>Multiple functions can be attached to a ParserElement by specifying multiple
-arguments to setParseAction, or by calling setParseAction multiple times.</p>
-<p>Each parse action function can return a modified <tt class="docutils literal">toks</tt> list, to perform conversion, or
-string modifications.  For brevity, <tt class="docutils literal">fn</tt> may also be a
-lambda - here is an example of using a parse action to convert matched
-integer tokens from strings to integers:</p>
-<pre class="literal-block">
-intNumber = Word(nums).setParseAction( lambda s,l,t: [ int(t[0]) ] )
-</pre>
-<p>If <tt class="docutils literal">fn</tt> does not modify the <tt class="docutils literal">toks</tt> list, it does not need to return
-anything at all.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">setBreak( breakFlag=True )</tt> - if breakFlag is True, calls pdb.set_break()
-as this expression is about to be parsed</p>
-</li>
-<li><p class="first"><tt class="docutils literal">copy()</tt> - returns a copy of a ParserElement; can be used to use the same
-parse expression in different places in a grammar, with different parse actions
-attached to each</p>
-</li>
-<li><p class="first"><tt class="docutils literal">leaveWhitespace()</tt> - change default behavior of skipping
-whitespace before starting matching (mostly used internally to the
-pyparsing module, rarely used by client code)</p>
-</li>
-<li><p class="first"><tt class="docutils literal">setWhitespaceChars( chars )</tt> - define the set of chars to be ignored
-as whitespace before trying to match a specific ParserElement, in place of the
-default set of whitespace (space, tab, newline, and return)</p>
-</li>
-<li><p class="first"><tt class="docutils literal">setDefaultWhitespaceChars( chars )</tt> - class-level method to override
-the default set of whitespace chars for all subsequently created ParserElements
-(including copies); useful when defining grammars that treat one or more of the
-default whitespace characters as significant (such as a line-sensitive grammar, to
-omit newline from the list of ignorable whitespace)</p>
-</li>
-<li><p class="first"><tt class="docutils literal">suppress()</tt> - convenience function to suppress the output of the
-given element, instead of wrapping it with a Suppress object.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">ignore( expr )</tt> - function to specify parse expression to be
-ignored while matching defined patterns; can be called
-repeatedly to specify multiple expressions; useful to specify
-patterns of comment syntax, for example</p>
-</li>
-<li><p class="first"><tt class="docutils literal">setDebug( dbgFlag=True )</tt> - function to enable/disable tracing output
-when trying to match this element</p>
-</li>
-<li><p class="first"><tt class="docutils literal">validate()</tt> - function to verify that the defined grammar does not
-contain infinitely recursive constructs</p>
-</li>
-</ul>
-<ul class="simple" id="parsewithtabs">
-<li><tt class="docutils literal">parseWithTabs()</tt> - function to override default behavior of converting
-tabs to spaces before parsing the input string; rarely used, except when
-specifying whitespace-significant grammars using the <a class="reference internal" href="#white">White</a> class.</li>
-<li><tt class="docutils literal">enablePackrat()</tt> - a class-level static method to enable a memoizing
-performance enhancement, known as &quot;packrat parsing&quot;.  packrat parsing is
-disabled by default, since it may conflict with some user programs that use
-parse actions.  To activate the packrat feature, your
-program must call the class method ParserElement.enablePackrat().  If
-your program uses psyco to &quot;compile as you go&quot;, you must call
-enablePackrat before calling psyco.full().  If you do not do this,
-Python will crash.  For best results, call enablePackrat() immediately
-after importing pyparsing.</li>
-</ul>
-</div>
-<div class="section" id="basic-parserelement-subclasses">
-<h2><a class="toc-backref" href="#id6">2.2&nbsp;&nbsp;&nbsp;Basic ParserElement subclasses</a></h2>
-<ul class="simple">
-<li><tt class="docutils literal">Literal</tt> - construct with a string to be matched exactly</li>
-<li><tt class="docutils literal">CaselessLiteral</tt> - construct with a string to be matched, but
-without case checking; results are always returned as the
-defining literal, NOT as they are found in the input string</li>
-<li><tt class="docutils literal">Keyword</tt> - similar to Literal, but must be immediately followed by
-whitespace, punctuation, or other non-keyword characters; prevents
-accidental matching of a non-keyword that happens to begin with a
-defined keyword</li>
-<li><tt class="docutils literal">CaselessKeyword</tt> - similar to Keyword, but with caseless matching
-behavior</li>
-</ul>
-<ul id="word">
-<li><p class="first"><tt class="docutils literal">Word</tt> - one or more contiguous characters; construct with a
-string containing the set of allowed initial characters, and an
-optional second string of allowed body characters; for instance,
-a common Word construct is to match a code identifier - in C, a
-valid identifier must start with an alphabetic character or an
-underscore ('_'), followed by a body that can also include numeric
-digits.  That is, <tt class="docutils literal">a</tt>, <tt class="docutils literal">i</tt>, <tt class="docutils literal">MAX_LENGTH</tt>, <tt class="docutils literal">_a1</tt>, <tt class="docutils literal">b_109_</tt>, and
-<tt class="docutils literal">plan9FromOuterSpace</tt>
-are all valid identifiers; <tt class="docutils literal">9b7z</tt>, <tt class="docutils literal">$a</tt>, <tt class="docutils literal">.section</tt>, and <tt class="docutils literal">0debug</tt>
-are not.  To
-define an identifier using a Word, use either of the following:</p>
-<pre class="literal-block">
-- Word( alphas+&quot;_&quot;, alphanums+&quot;_&quot; )
-- Word( srange(&quot;[a-zA-Z_]&quot;), srange(&quot;[a-zA-Z0-9_]&quot;) )
-</pre>
-<p>If only one
-string given, it specifies that the same character set defined
-for the initial character is used for the word body; for instance, to
-define an identifier that can only be composed of capital letters and
-underscores, use:</p>
-<pre class="literal-block">
-- Word( &quot;ABCDEFGHIJKLMNOPQRSTUVWXYZ_&quot; )
-- Word( srange(&quot;[A-Z_]&quot;) )
-</pre>
-<p>A Word may
-also be constructed with any of the following optional parameters:</p>
-<ul class="simple">
-<li><tt class="docutils literal">min</tt> - indicating a minimum length of matching characters</li>
-<li><tt class="docutils literal">max</tt> - indicating a maximum length of matching characters</li>
-<li><tt class="docutils literal">exact</tt> - indicating an exact length of matching characters</li>
-</ul>
-<p>If exact is specified, it will override any values for min or max.</p>
-<p>New in 1.5.6 - Sometimes you want to define a word using all
-characters in a range except for one or two of them; you can do this
-with the new <tt class="docutils literal">excludeChars</tt> argument. This is helpful if you want to define
-a word with all printables except for a single delimiter character, such
-as '.'. Previously, you would have to create a custom string to pass to <tt class="docutils literal">Word</tt>.
-With this change, you can just create <tt class="docutils literal">Word(printables, <span class="pre">excludeChars='.')</span></tt>.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">CharsNotIn</tt> - similar to <a class="reference internal" href="#word">Word</a>, but matches characters not
-in the given constructor string (accepts only one string for both
-initial and body characters); also supports min, max, and exact
-optional parameters.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">Regex</tt> - a powerful construct, that accepts a regular expression
-to be matched at the current parse position; accepts an optional
-flags parameter, corresponding to the flags parameter in the re.compile
-method; if the expression includes named sub-fields, they will be
-represented in the returned <a class="reference internal" href="#parseresults">ParseResults</a></p>
-</li>
-<li><p class="first"><tt class="docutils literal">QuotedString</tt> - supports the definition of custom quoted string
-formats, in addition to pyparsing's built-in dblQuotedString and
-sglQuotedString.  QuotedString allows you to specify the following
-parameters:</p>
-<ul class="simple">
-<li><tt class="docutils literal">quoteChar</tt> - string of one or more characters defining the quote delimiting string</li>
-<li><tt class="docutils literal">escChar</tt> - character to escape quotes, typically backslash (default=None)</li>
-<li><tt class="docutils literal">escQuote</tt> - special quote sequence to escape an embedded quote string (such as SQL's &quot;&quot; to escape an embedded &quot;) (default=None)</li>
-<li><tt class="docutils literal">multiline</tt> - boolean indicating whether quotes can span multiple lines (default=<tt class="docutils literal">False</tt>)</li>
-<li><tt class="docutils literal">unquoteResults</tt> - boolean indicating whether the matched text should be unquoted (default=<tt class="docutils literal">True</tt>)</li>
-<li><tt class="docutils literal">endQuoteChar</tt> - string of one or more characters defining the end of the quote delimited string (default=None =&gt; same as quoteChar)</li>
-</ul>
-</li>
-<li><p class="first"><tt class="docutils literal">SkipTo</tt> - skips ahead in the input string, accepting any
-characters up to the specified pattern; may be constructed with
-the following optional parameters:</p>
-<ul class="simple">
-<li><tt class="docutils literal">include</tt> - if set to true, also consumes the match expression
-(default is <tt class="docutils literal">False</tt>)</li>
-<li><tt class="docutils literal">ignore</tt> - allows the user to specify patterns to not be matched,
-to prevent false matches</li>
-<li><tt class="docutils literal">failOn</tt> - if a literal string or expression is given for this argument, it defines an expression that
-should cause the <tt class="docutils literal">SkipTo</tt> expression to fail, and not skip over that expression</li>
-</ul>
-</li>
-</ul>
-<ul class="simple" id="white">
-<li><tt class="docutils literal">White</tt> - also similar to <a class="reference internal" href="#word">Word</a>, but matches whitespace
-characters.  Not usually needed, as whitespace is implicitly
-ignored by pyparsing.  However, some grammars are whitespace-sensitive,
-such as those that use leading tabs or spaces to indicating grouping
-or hierarchy.  (If matching on tab characters, be sure to call
-<a class="reference internal" href="#parsewithtabs">parseWithTabs</a> on the top-level parse element.)</li>
-<li><tt class="docutils literal">Empty</tt> - a null expression, requiring no characters - will always
-match; useful for debugging and for specialized grammars</li>
-<li><tt class="docutils literal">NoMatch</tt> - opposite of Empty, will never match; useful for debugging
-and for specialized grammars</li>
-</ul>
-</div>
-<div class="section" id="expression-subclasses">
-<h2><a class="toc-backref" href="#id7">2.3&nbsp;&nbsp;&nbsp;Expression subclasses</a></h2>
-<ul>
-<li><p class="first"><tt class="docutils literal">And</tt> - construct with a list of ParserElements, all of which must
-match for And to match; can also be created using the '+'
-operator; multiple expressions can be Anded together using the '*'
-operator as in:</p>
-<pre class="literal-block">
-ipAddress = Word(nums) + ('.'+Word(nums))*3
-</pre>
-<p>A tuple can be used as the multiplier, indicating a min/max:</p>
-<pre class="literal-block">
-usPhoneNumber = Word(nums) + ('-'+Word(nums))*(1,2)
-</pre>
-<p>A special form of <tt class="docutils literal">And</tt> is created if the '-' operator is used
-instead of the '+' operator.  In the ipAddress example above, if
-no trailing '.' and Word(nums) are found after matching the initial
-Word(nums), then pyparsing will back up in the grammar and try other
-alternatives to ipAddress.  However, if ipAddress is defined as:</p>
-<pre class="literal-block">
-strictIpAddress = Word(nums) - ('.'+Word(nums))*3
-</pre>
-<p>then no backing up is done.  If the first Word(nums) of strictIpAddress
-is matched, then any mismatch after that will raise a ParseSyntaxException,
-which will halt the parsing process immediately.  By careful use of the
-'-' operator, grammars can provide meaningful error messages close to
-the location where the incoming text does not match the specified
-grammar.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">Or</tt> - construct with a list of ParserElements, any of which must
-match for Or to match; if more than one expression matches, the
-expression that makes the longest match will be used; can also
-be created using the '^' operator</p>
-</li>
-<li><p class="first"><tt class="docutils literal">MatchFirst</tt> - construct with a list of ParserElements, any of
-which must match for MatchFirst to match; matching is done
-left-to-right, taking the first expression that matches; can
-also be created using the '|' operator</p>
-</li>
-<li><p class="first"><tt class="docutils literal">Each</tt> - similar to And, in that all of the provided expressions
-must match; however, Each permits matching to be done in any order;
-can also be created using the '&amp;' operator</p>
-</li>
-<li><p class="first"><tt class="docutils literal">Optional</tt> - construct with a ParserElement, but this element is
-not required to match; can be constructed with an optional <tt class="docutils literal">default</tt> argument,
-containing a default string or object to be supplied if the given optional
-parse element is not found in the input string; parse action will only
-be called if a match is found, or if a default is specified</p>
-</li>
-<li><p class="first"><tt class="docutils literal">ZeroOrMore</tt> - similar to Optional, but can be repeated</p>
-</li>
-<li><p class="first"><tt class="docutils literal">OneOrMore</tt> - similar to ZeroOrMore, but at least one match must
-be present</p>
-</li>
-<li><p class="first"><tt class="docutils literal">FollowedBy</tt> - a lookahead expression, requires matching of the given
-expressions, but does not advance the parsing position within the input string</p>
-</li>
-<li><p class="first"><tt class="docutils literal">NotAny</tt> - a negative lookahead expression, prevents matching of named
-expressions, does not advance the parsing position within the input string;
-can also be created using the unary '~' operator</p>
-</li>
-</ul>
-</div>
-<div class="section" id="expression-operators">
-<span id="operators"></span><h2><a class="toc-backref" href="#id8">2.4&nbsp;&nbsp;&nbsp;Expression operators</a></h2>
-<ul class="simple">
-<li><tt class="docutils literal">~</tt> - creates NotAny using the expression after the operator</li>
-<li><tt class="docutils literal">+</tt> - creates And using the expressions before and after the operator</li>
-<li><tt class="docutils literal">|</tt> - creates MatchFirst (first left-to-right match) using the expressions before and after the operator</li>
-<li><tt class="docutils literal">^</tt> - creates Or (longest match) using the expressions before and after the operator</li>
-<li><tt class="docutils literal">&amp;</tt> - creates Each using the expressions before and after the operator</li>
-<li><tt class="docutils literal">*</tt> - creates And by multiplying the expression by the integer operand; if
-expression is multiplied by a 2-tuple, creates an And of (min,max)
-expressions (similar to &quot;{min,max}&quot; form in regular expressions); if
-min is None, intepret as (0,max); if max is None, interpret as
-expr*min + ZeroOrMore(expr)</li>
-<li><tt class="docutils literal">-</tt> - like <tt class="docutils literal">+</tt> but with no backup and retry of alternatives</li>
-<li><tt class="docutils literal">*</tt> - repetition of expression</li>
-<li><tt class="docutils literal">==</tt> - matching expression to string; returns True if the string matches the given expression</li>
-<li><tt class="docutils literal">&lt;&lt;=</tt> - inserts the expression following the operator as the body of the
-Forward expression before the operator (formerly &lt;&lt;, which is now deprecated)</li>
-</ul>
-</div>
-<div class="section" id="positional-subclasses">
-<h2><a class="toc-backref" href="#id9">2.5&nbsp;&nbsp;&nbsp;Positional subclasses</a></h2>
-<ul class="simple">
-<li><tt class="docutils literal">StringStart</tt> - matches beginning of the text</li>
-<li><tt class="docutils literal">StringEnd</tt> - matches the end of the text</li>
-<li><tt class="docutils literal">LineStart</tt> - matches beginning of a line (lines delimited by <tt class="docutils literal">\n</tt> characters)</li>
-<li><tt class="docutils literal">LineEnd</tt> - matches the end of a line</li>
-<li><tt class="docutils literal">WordStart</tt> - matches a leading word boundary</li>
-<li><tt class="docutils literal">WordEnd</tt> - matches a trailing word boundary</li>
-</ul>
-</div>
-<div class="section" id="converter-subclasses">
-<h2><a class="toc-backref" href="#id10">2.6&nbsp;&nbsp;&nbsp;Converter subclasses</a></h2>
-<ul class="simple">
-<li><tt class="docutils literal">Upcase</tt> - converts matched tokens to uppercase (deprecated -
-use <tt class="docutils literal">upcaseTokens</tt> parse action instead)</li>
-<li><tt class="docutils literal">Combine</tt> - joins all matched tokens into a single string, using
-specified joinString (default <tt class="docutils literal"><span class="pre">joinString=&quot;&quot;</span></tt>); expects
-all matching tokens to be adjacent, with no intervening
-whitespace (can be overridden by specifying <tt class="docutils literal">adjacent=False</tt> in constructor)</li>
-<li><tt class="docutils literal">Suppress</tt> - clears matched tokens; useful to keep returned
-results from being cluttered with required but uninteresting
-tokens (such as list delimiters)</li>
-</ul>
-</div>
-<div class="section" id="special-subclasses">
-<h2><a class="toc-backref" href="#id11">2.7&nbsp;&nbsp;&nbsp;Special subclasses</a></h2>
-<ul class="simple">
-<li><tt class="docutils literal">Group</tt> - causes the matched tokens to be enclosed in a list;
-useful in repeated elements like <tt class="docutils literal">ZeroOrMore</tt> and <tt class="docutils literal">OneOrMore</tt> to
-break up matched tokens into groups for each repeated pattern</li>
-<li><tt class="docutils literal">Dict</tt> - like <tt class="docutils literal">Group</tt>, but also constructs a dictionary, using the
-[0]'th elements of all enclosed token lists as the keys, and
-each token list as the value</li>
-<li><tt class="docutils literal">SkipTo</tt> - catch-all matching expression that accepts all characters
-up until the given pattern is found to match; useful for specifying
-incomplete grammars</li>
-<li><tt class="docutils literal">Forward</tt> - placeholder token used to define recursive token
-patterns; when defining the actual expression later in the
-program, insert it into the <tt class="docutils literal">Forward</tt> object using the <tt class="docutils literal">&lt;&lt;=</tt>
-operator (see <tt class="docutils literal">fourFn.py</tt> for an example).</li>
-</ul>
-</div>
-<div class="section" id="other-classes">
-<h2><a class="toc-backref" href="#id12">2.8&nbsp;&nbsp;&nbsp;Other classes</a></h2>
-<ul id="parseresults">
-<li><p class="first"><tt class="docutils literal">ParseResults</tt> - class used to contain and manage the lists of tokens
-created from parsing the input using the user-defined parse
-expression.  ParseResults can be accessed in a number of ways:</p>
-<ul class="simple">
-<li>as a list<ul>
-<li>total list of elements can be found using len()</li>
-<li>individual elements can be found using [0], [1], [-1], etc.</li>
-<li>elements can be deleted using <tt class="docutils literal">del</tt></li>
-<li>the -1th element can be extracted and removed in a single operation
-using <tt class="docutils literal">pop()</tt>, or any element can be extracted and removed
-using <tt class="docutils literal">pop(n)</tt></li>
-</ul>
-</li>
-<li>as a dictionary<ul>
-<li>if <tt class="docutils literal">setResultsName()</tt> is used to name elements within the
-overall parse expression, then these fields can be referenced
-as dictionary elements or as attributes</li>
-<li>the Dict class generates dictionary entries using the data of the
-input text - in addition to ParseResults listed as <tt class="docutils literal">[ [ a1, b1, c1, <span class="pre">...],</span> [ a2, b2, c2, <span class="pre">...]</span>&nbsp; ]</tt>
-it also acts as a dictionary with entries defined as <tt class="docutils literal">{ a1 : [ b1, c1, ... ] }, { a2 : [ b2, c2, ... ] }</tt>;
-this is especially useful when processing tabular data where the first column contains a key
-value for that line of data</li>
-<li>list elements that are deleted using <tt class="docutils literal">del</tt> will still be accessible by their
-dictionary keys</li>
-<li>supports <tt class="docutils literal">get()</tt>, <tt class="docutils literal">items()</tt> and <tt class="docutils literal">keys()</tt> methods, similar to a dictionary</li>
-<li>a keyed item can be extracted and removed using <tt class="docutils literal">pop(key)</tt>.  Here
-key must be non-numeric (such as a string), in order to use dict
-extraction instead of list extraction.</li>
-<li>new named elements can be added (in a parse action, for instance), using the same
-syntax as adding an item to a dict (<tt class="docutils literal"><span class="pre">parseResults[&quot;X&quot;]=&quot;new</span> item&quot;</tt>); named elements can be removed using <tt class="docutils literal">del <span class="pre">parseResults[&quot;X&quot;]</span></tt></li>
-</ul>
-</li>
-<li>as a nested list<ul>
-<li>results returned from the Group class are encapsulated within their
-own list structure, so that the tokens can be handled as a hierarchical
-tree</li>
-</ul>
-</li>
-</ul>
-<p>ParseResults can also be converted to an ordinary list of strings
-by calling <tt class="docutils literal">asList()</tt>.  Note that this will strip the results of any
-field names that have been defined for any embedded parse elements.
-(The <tt class="docutils literal">pprint</tt> module is especially good at printing out the nested contents
-given by <tt class="docutils literal">asList()</tt>.)</p>
-<p>Finally, ParseResults can be converted to an XML string by calling <tt class="docutils literal">asXML()</tt>. Where
-possible, results will be tagged using the results names defined for the respective
-ParseExpressions.  <tt class="docutils literal">asXML()</tt> takes two optional arguments:</p>
-<ul class="simple">
-<li><tt class="docutils literal">doctagname</tt> - for ParseResults that do not have a defined name, this argument
-will wrap the resulting XML in a set of opening and closing tags <tt class="docutils literal">&lt;doctagname&gt;</tt>
-and <tt class="docutils literal">&lt;/doctagname&gt;</tt>.</li>
-<li><tt class="docutils literal">namedItemsOnly</tt> (default=<tt class="docutils literal">False</tt>) - flag to indicate if the generated XML should
-skip items that do not have defined names.  If a nested group item is named, then all
-embedded items will be included, whether they have names or not.</li>
-</ul>
-</li>
-</ul>
-</div>
-<div class="section" id="exception-classes-and-troubleshooting">
-<h2><a class="toc-backref" href="#id13">2.9&nbsp;&nbsp;&nbsp;Exception classes and Troubleshooting</a></h2>
-<ul id="parseexception">
-<li><p class="first"><tt class="docutils literal">ParseException</tt> - exception returned when a grammar parse fails;
-ParseExceptions have attributes loc, msg, line, lineno, and column; to view the
-text line and location where the reported ParseException occurs, use:</p>
-<pre class="literal-block">
-except ParseException, err:
-    print err.line
-    print &quot; &quot;*(err.column-1) + &quot;^&quot;
-    print err
-</pre>
-</li>
-<li><p class="first"><tt class="docutils literal">RecursiveGrammarException</tt> - exception returned by <tt class="docutils literal">validate()</tt> if
-the grammar contains a recursive infinite loop, such as:</p>
-<pre class="literal-block">
-badGrammar = Forward()
-goodToken = Literal(&quot;A&quot;)
-badGrammar &lt;&lt;= Optional(goodToken) + badGrammar
-</pre>
-</li>
-<li><p class="first"><tt class="docutils literal">ParseFatalException</tt> - exception that parse actions can raise to stop parsing
-immediately.  Should be used when a semantic error is found in the input text, such
-as a mismatched XML tag.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">ParseSyntaxException</tt> - subclass of <tt class="docutils literal">ParseFatalException</tt> raised when a
-syntax error is found, based on the use of the '-' operator when defining
-a sequence of expressions in an <tt class="docutils literal">And</tt> expression.</p>
-</li>
-</ul>
-<p>You can also get some insights into the parsing logic using diagnostic parse actions,
-and setDebug(), or test the matching of expression fragments by testing them using
-scanString().</p>
-</div>
-</div>
-<div class="section" id="miscellaneous-attributes-and-methods">
-<h1><a class="toc-backref" href="#id14">3&nbsp;&nbsp;&nbsp;Miscellaneous attributes and methods</a></h1>
-<div class="section" id="helper-methods">
-<h2><a class="toc-backref" href="#id15">3.1&nbsp;&nbsp;&nbsp;Helper methods</a></h2>
-<ul>
-<li><p class="first"><tt class="docutils literal">delimitedList( expr, <span class="pre">delim=',')</span></tt> - convenience function for
-matching one or more occurrences of expr, separated by delim.
-By default, the delimiters are suppressed, so the returned results contain
-only the separate list elements.  Can optionally specify <tt class="docutils literal">combine=True</tt>,
-indicating that the expressions and delimiters should be returned as one
-combined value (useful for scoped variables, such as &quot;a.b.c&quot;, or
-&quot;a::b::c&quot;, or paths such as &quot;a/b/c&quot;).</p>
-</li>
-<li><p class="first"><tt class="docutils literal">countedArray( expr )</tt> - convenience function for a pattern where an list of
-instances of the given expression are preceded by an integer giving the count of
-elements in the list.  Returns an expression that parses the leading integer,
-reads exactly that many expressions, and returns the array of expressions in the
-parse results - the leading integer is suppressed from the results (although it
-is easily reconstructed by using len on the returned array).</p>
-</li>
-<li><p class="first"><tt class="docutils literal">oneOf( string, caseless=False )</tt> - convenience function for quickly declaring an
-alternative set of <tt class="docutils literal">Literal</tt> tokens, by splitting the given string on
-whitespace boundaries.  The tokens are sorted so that longer
-matches are attempted first; this ensures that a short token does
-not mask a longer one that starts with the same characters. If <tt class="docutils literal">caseless=True</tt>,
-will create an alternative set of CaselessLiteral tokens.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">dictOf( key, value )</tt> - convenience function for quickly declaring a
-dictionary pattern of <tt class="docutils literal">Dict( ZeroOrMore( Group( key + value ) ) )</tt>.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">makeHTMLTags( tagName )</tt> and <tt class="docutils literal">makeXMLTags( tagName )</tt> - convenience
-functions to create definitions of opening and closing tag expressions.  Returns
-a pair of expressions, for the corresponding &lt;tag&gt; and &lt;/tag&gt; strings.  Includes
-support for attributes in the opening tag, such as &lt;tag attr1=&quot;abc&quot;&gt; - attributes
-are returned as keyed tokens in the returned ParseResults.  <tt class="docutils literal">makeHTMLTags</tt> is less
-restrictive than <tt class="docutils literal">makeXMLTags</tt>, especially with respect to case sensitivity.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">infixNotation(baseOperand, operatorList)</tt> - (formerly named <tt class="docutils literal">operatorPrecedence</tt>) convenience function to define a
-grammar for parsing infix notation
-expressions with a hierarchical precedence of operators. To use the <tt class="docutils literal">infixNotation</tt>
-helper:</p>
-<ol class="arabic simple">
-<li>Define the base &quot;atom&quot; operand term of the grammar.
-For this simple grammar, the smallest operand is either
-and integer or a variable.  This will be the first argument
-to the <tt class="docutils literal">infixNotation</tt> method.</li>
-<li>Define a list of tuples for each level of operator
-precendence.  Each tuple is of the form
-<tt class="docutils literal">(opExpr, numTerms, rightLeftAssoc, parseAction)</tt>, where:<ul>
-<li><tt class="docutils literal">opExpr</tt> is the pyparsing expression for the operator;
-may also be a string, which will be converted to a Literal; if
-None, indicates an empty operator, such as the implied
-multiplication operation between 'm' and 'x' in &quot;y = mx + b&quot;.
-If <tt class="docutils literal">numTerms</tt> parameter is 3, this must be a 2-tuple containing the 2 delimiting operators.</li>
-<li><tt class="docutils literal">numTerms</tt> is the number of terms for this operator (must
-be 1,2, or 3)</li>
-<li><tt class="docutils literal">rightLeftAssoc</tt> is the indicator whether the operator is
-right or left associative, using the pyparsing-defined
-constants <tt class="docutils literal">opAssoc.RIGHT</tt> and <tt class="docutils literal">opAssoc.LEFT</tt>.</li>
-<li><tt class="docutils literal">parseAction</tt> is the parse action to be associated with
-expressions matching this operator expression (the
-parse action tuple member may be omitted)</li>
-</ul>
-</li>
-<li>Call <tt class="docutils literal">infixNotation</tt> passing the operand expression and
-the operator precedence list, and save the returned value
-as the generated pyparsing expression.  You can then use
-this expression to parse input strings, or incorporate it
-into a larger, more complex grammar.</li>
-</ol>
-</li>
-<li><p class="first"><tt class="docutils literal">matchPreviousLiteral</tt> and <tt class="docutils literal">matchPreviousExpr</tt> - function to define and
-expression that matches the same content
-as was parsed in a previous parse expression.  For instance:</p>
-<pre class="literal-block">
-first = Word(nums)
-matchExpr = first + &quot;:&quot; + matchPreviousLiteral(first)
-</pre>
-<p>will match &quot;1:1&quot;, but not &quot;1:2&quot;.  Since this matches at the literal
-level, this will also match the leading &quot;1:1&quot; in &quot;1:10&quot;.</p>
-<p>In contrast:</p>
-<pre class="literal-block">
-first = Word(nums)
-matchExpr = first + &quot;:&quot; + matchPreviousExpr(first)
-</pre>
-<p>will <em>not</em> match the leading &quot;1:1&quot; in &quot;1:10&quot;; the expressions are
-evaluated first, and then compared, so &quot;1&quot; is compared with &quot;10&quot;.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">nestedExpr(opener, closer, content=None, ignoreExpr=quotedString)</tt> - method for defining nested
-lists enclosed in opening and closing delimiters.</p>
-<ul class="simple">
-<li><tt class="docutils literal">opener</tt> - opening character for a nested list (default=&quot;(&quot;); can also be a pyparsing expression</li>
-<li><tt class="docutils literal">closer</tt> - closing character for a nested list (default=&quot;)&quot;); can also be a pyparsing expression</li>
-<li><tt class="docutils literal">content</tt> - expression for items within the nested lists (default=None)</li>
-<li><tt class="docutils literal">ignoreExpr</tt> - expression for ignoring opening and closing delimiters (default=quotedString)</li>
-</ul>
-<p>If an expression is not provided for the content argument, the nested
-expression will capture all whitespace-delimited content between delimiters
-as a list of separate values.</p>
-<p>Use the <tt class="docutils literal">ignoreExpr</tt> argument to define expressions that may contain
-opening or closing characters that should not be treated as opening
-or closing characters for nesting, such as quotedString or a comment
-expression.  Specify multiple expressions using an Or or MatchFirst.
-The default is quotedString, but if no expressions are to be ignored,
-then pass None for this argument.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">indentedBlock( statementExpr, indentationStackVar, indent=True)</tt> -
-function to define an indented block of statements, similar to
-indentation-based blocking in Python source code:</p>
-<ul class="simple">
-<li><tt class="docutils literal">statementExpr</tt> - the expression defining a statement that
-will be found in the indented block; a valid indentedBlock
-must contain at least 1 matching statementExpr</li>
-<li><tt class="docutils literal">indentationStackVar</tt> - a Python list variable; this variable
-should be common to all <tt class="docutils literal">indentedBlock</tt> expressions defined
-within the same grammar, and should be reinitialized to [1]
-each time the grammar is to be used</li>
-<li><tt class="docutils literal">indent</tt> - a boolean flag indicating whether the expressions
-within the block must be indented from the current parse
-location; if using indentedBlock to define the left-most
-statements (all starting in column 1), set indent to False</li>
-</ul>
-</li>
-</ul>
-<ul id="originaltextfor">
-<li><p class="first"><tt class="docutils literal">originalTextFor( expr )</tt> - helper function to preserve the originally parsed text, regardless of any
-token processing or conversion done by the contained expression.  For instance, the following expression:</p>
-<pre class="literal-block">
-fullName = Word(alphas) + Word(alphas)
-</pre>
-<p>will return the parse of &quot;John Smith&quot; as ['John', 'Smith'].  In some applications, the actual name as it
-was given in the input string is what is desired.  To do this, use <tt class="docutils literal">originalTextFor</tt>:</p>
-<pre class="literal-block">
-fullName = originalTextFor(Word(alphas) + Word(alphas))
-</pre>
-</li>
-<li><p class="first"><tt class="docutils literal">ungroup( expr )</tt> - function to &quot;ungroup&quot; returned tokens; useful
-to undo the default behavior of And to always group the returned tokens, even
-if there is only one in the list. (New in 1.5.6)</p>
-</li>
-<li><p class="first"><tt class="docutils literal">lineno( loc, string )</tt> - function to give the line number of the
-location within the string; the first line is line 1, newlines
-start new rows</p>
-</li>
-<li><p class="first"><tt class="docutils literal">col( loc, string )</tt> - function to give the column number of the
-location within the string; the first column is column 1,
-newlines reset the column number to 1</p>
-</li>
-<li><p class="first"><tt class="docutils literal">line( loc, string )</tt> - function to retrieve the line of text
-representing <tt class="docutils literal">lineno( loc, string )</tt>; useful when printing out diagnostic
-messages for exceptions</p>
-</li>
-<li><p class="first"><tt class="docutils literal">srange( rangeSpec )</tt> - function to define a string of characters,
-given a string of the form used by regexp string ranges, such as <tt class="docutils literal"><span class="pre">&quot;[0-9]&quot;</span></tt> for
-all numeric digits, <tt class="docutils literal"><span class="pre">&quot;[A-Z_]&quot;</span></tt> for uppercase characters plus underscore, and
-so on (note that rangeSpec does not include support for generic regular
-expressions, just string range specs)</p>
-</li>
-<li><p class="first"><tt class="docutils literal">getTokensEndLoc()</tt> - function to call from within a parse action to get
-the ending location for the matched tokens</p>
-</li>
-<li><p class="first"><tt class="docutils literal">traceParseAction(fn)</tt> - decorator function to debug parse actions. Lists
-each call, called arguments, and return value or exception</p>
-</li>
-</ul>
-</div>
-<div class="section" id="helper-parse-actions">
-<h2><a class="toc-backref" href="#id16">3.2&nbsp;&nbsp;&nbsp;Helper parse actions</a></h2>
-<ul>
-<li><p class="first"><tt class="docutils literal">removeQuotes</tt> - removes the first and last characters of a quoted string;
-useful to remove the delimiting quotes from quoted strings</p>
-</li>
-<li><p class="first"><tt class="docutils literal">replaceWith(replString)</tt> - returns a parse action that simply returns the
-replString; useful when using transformString, or converting HTML entities, as in:</p>
-<pre class="literal-block">
-nbsp = Literal(&quot;&amp;nbsp;&quot;).setParseAction( replaceWith(&quot;&lt;BLANK&gt;&quot;) )
-</pre>
-</li>
-<li><p class="first"><tt class="docutils literal">keepOriginalText</tt>- (deprecated, use <a class="reference internal" href="#originaltextfor">originalTextFor</a> instead) restores any internal whitespace or suppressed
-text within the tokens for a matched parse
-expression.  This is especially useful when defining expressions
-for scanString or transformString applications.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">withAttribute( *args, **kwargs )</tt> - helper to create a validating parse action to be used with start tags created
-with <tt class="docutils literal">makeXMLTags</tt> or <tt class="docutils literal">makeHTMLTags</tt>. Use <tt class="docutils literal">withAttribute</tt> to qualify a starting tag
-with a required attribute value, to avoid false matches on common tags such as
-<tt class="docutils literal">&lt;TD&gt;</tt> or <tt class="docutils literal">&lt;DIV&gt;</tt>.</p>
-<p><tt class="docutils literal">withAttribute</tt> can be called with:</p>
-<ul class="simple">
-<li>keyword arguments, as in <tt class="docutils literal"><span class="pre">(class=&quot;Customer&quot;,align=&quot;right&quot;)</span></tt>, or</li>
-<li>a list of name-value tuples, as in <tt class="docutils literal">( (&quot;ns1:class&quot;, <span class="pre">&quot;Customer&quot;),</span> <span class="pre">(&quot;ns2:align&quot;,&quot;right&quot;)</span> )</tt></li>
-</ul>
-<p>An attribute can be specified to have the special value
-<tt class="docutils literal">withAttribute.ANY_VALUE</tt>, which will match any value - use this to
-ensure that an attribute is present but any attribute value is
-acceptable.</p>
-</li>
-<li><p class="first"><tt class="docutils literal">downcaseTokens</tt> - converts all matched tokens to lowercase</p>
-</li>
-<li><p class="first"><tt class="docutils literal">upcaseTokens</tt> - converts all matched tokens to uppercase</p>
-</li>
-<li><p class="first"><tt class="docutils literal">matchOnlyAtCol( columnNumber )</tt> - a parse action that verifies that
-an expression was matched at a particular column, raising a
-ParseException if matching at a different column number; useful when parsing
-tabular data</p>
-</li>
-</ul>
-</div>
-<div class="section" id="common-string-and-token-constants">
-<h2><a class="toc-backref" href="#id17">3.3&nbsp;&nbsp;&nbsp;Common string and token constants</a></h2>
-<ul>
-<li><p class="first"><tt class="docutils literal">alphas</tt> - same as <tt class="docutils literal">string.letters</tt></p>
-</li>
-<li><p class="first"><tt class="docutils literal">nums</tt> - same as <tt class="docutils literal">string.digits</tt></p>
-</li>
-<li><p class="first"><tt class="docutils literal">alphanums</tt> - a string containing <tt class="docutils literal">alphas + nums</tt></p>
-</li>
-<li><p class="first"><tt class="docutils literal">alphas8bit</tt> - a string containing alphabetic 8-bit characters:</p>
-<pre class="literal-block">
-ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ
-</pre>
-</li>
-<li><p class="first"><tt class="docutils literal">printables</tt> - same as <tt class="docutils literal">string.printable</tt>, minus the space (<tt class="docutils literal">' '</tt>) character</p>
-</li>
-<li><p class="first"><tt class="docutils literal">empty</tt> - a global <tt class="docutils literal">Empty()</tt>; will always match</p>
-</li>
-<li><p class="first"><tt class="docutils literal">sglQuotedString</tt> - a string of characters enclosed in 's; may
-include whitespace, but not newlines</p>
-</li>
-<li><p class="first"><tt class="docutils literal">dblQuotedString</tt> - a string of characters enclosed in &quot;s; may
-include whitespace, but not newlines</p>
-</li>
-<li><p class="first"><tt class="docutils literal">quotedString</tt> - <tt class="docutils literal">sglQuotedString | dblQuotedString</tt></p>
-</li>
-<li><p class="first"><tt class="docutils literal">cStyleComment</tt> - a comment block delimited by <tt class="docutils literal"><span class="pre">'/*'</span></tt> and <tt class="docutils literal"><span class="pre">'*/'</span></tt> sequences; can span
-multiple lines, but does not support nesting of comments</p>
-</li>
-<li><p class="first"><tt class="docutils literal">htmlComment</tt> - a comment block delimited by <tt class="docutils literal"><span class="pre">'&lt;!--'</span></tt> and <tt class="docutils literal"><span class="pre">'--&gt;'</span></tt> sequences; can span
-multiple lines, but does not support nesting of comments</p>
-</li>
-<li><p class="first"><tt class="docutils literal">commaSeparatedList</tt> - similar to <tt class="docutils literal">delimitedList</tt>, except that the
-list expressions can be any text value, or a quoted string; quoted strings can
-safely include commas without incorrectly breaking the string into two tokens</p>
-</li>
-<li><p class="first"><tt class="docutils literal">restOfLine</tt> - all remaining printable characters up to but not including the next
-newline</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-</body>
-</html>
diff --git a/MANIFEST.in b/MANIFEST.in
index 47dcbae..a89ff0c 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -2,7 +2,5 @@ include pyparsing.py
 include HowToUsePyparsing.html pyparsingClassDiagram.*
 include README.md CODE_OF_CONDUCT.md CHANGES LICENSE
 include examples/*.py examples/Setup.ini examples/*.dfm examples/*.ics examples/*.html
-include htmldoc/*
-include docs/*
 include test/*
 include simple_unit_tests.py unitTests.py
diff --git a/MANIFEST.in_bdist b/MANIFEST.in_bdist
index 5f2b98b..57ce301 100644
--- a/MANIFEST.in_bdist
+++ b/MANIFEST.in_bdist
@@ -1,7 +1,6 @@
 include pyparsing.py
 include HowToUsePyparsing.html pyparsingClassDiagram.*
 include README CHANGES LICENSE
-include examples/*.py examples/Setup.ini examples/*.dfm examples/*.ics examples/*.html
-include htmldoc/*.*
-include docs/*.*
-include robots.txt
+include examples/*.py examples/Setup.ini examples/*.dfm examples/*.ics examples/*.html
+include docs/*
+include robots.txt
diff --git a/README.md b/README.md
deleted file mode 100644
index 4761512..0000000
--- a/README.md
+++ /dev/null
@@ -1,54 +0,0 @@
-PyParsing -- A Python Parsing Module
-====================================
-[![Build Status](https://travis-ci.org/pyparsing/pyparsing.svg?branch=master)](https://travis-ci.org/pyparsing/pyparsing)
-
-Introduction
-============
-
-The pyparsing module is an alternative approach to creating and executing 
-simple grammars, vs. the traditional lex/yacc approach, or the use of 
-regular expressions.  The pyparsing module provides a library of classes 
-that client code uses to construct the grammar directly in Python code.
-
-Here is a program to parse "Hello, World!" (or any greeting of the form 
-"salutation, addressee!"):
-
-```python
-from pyparsing import Word, alphas
-greet = Word( alphas ) + "," + Word( alphas ) + "!"
-hello = "Hello, World!"
-print(hello, "->", greet.parseString( hello ))
-```
-
-The program outputs the following:
-
-    Hello, World! -> ['Hello', ',', 'World', '!']
-
-The Python representation of the grammar is quite readable, owing to the 
-self-explanatory class names, and the use of '+', '|' and '^' operator 
-definitions.
-
-The parsed results returned from parseString() can be accessed as a 
-nested list, a dictionary, or an object with named attributes.
-
-The pyparsing module handles some of the problems that are typically 
-vexing when writing text parsers:
-- extra or missing whitespace (the above program will also handle 
-  "Hello,World!", "Hello  ,  World  !", etc.)
-- quoted strings
-- embedded comments
-
-The examples directory includes a simple SQL parser, simple CORBA IDL 
-parser, a config file parser, a chemical formula parser, and a four-
-function algebraic notation parser, among many others.
-
-
-License
-=======
-
-    MIT License. See header of pyparsing.py
-
-History
-=======
-
-    See CHANGES file.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..0d702d7
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,56 @@
+PyParsing – A Python Parsing Module
+===================================
+
+|Build Status|
+
+Introduction
+============
+
+The pyparsing module is an alternative approach to creating and
+executing simple grammars, vs. the traditional lex/yacc approach, or the
+use of regular expressions. The pyparsing module provides a library of
+classes that client code uses to construct the grammar directly in
+Python code.
+
+Here is a program to parse “Hello, World!” (or any greeting of the form
+“salutation, addressee!”):
+
+.. code:: python
+
+    from pyparsing import Word, alphas
+    greet = Word( alphas ) + "," + Word( alphas ) + "!"
+    hello = "Hello, World!"
+    print(hello, "->", greet.parseString( hello ))
+
+The program outputs the following::
+
+    Hello, World! -> ['Hello', ',', 'World', '!']
+
+The Python representation of the grammar is quite readable, owing to the
+self-explanatory class names, and the use of ‘+’, ‘\|’ and ‘^’ operator
+definitions.
+
+The parsed results returned from parseString() can be accessed as a
+nested list, a dictionary, or an object with named attributes.
+
+The pyparsing module handles some of the problems that are typically
+vexing when writing text parsers: - extra or missing whitespace (the
+above program will also handle “Hello,World!”, “Hello , World !”, etc.)
+- quoted strings - embedded comments
+
+The examples directory includes a simple SQL parser, simple CORBA IDL
+parser, a config file parser, a chemical formula parser, and a four-
+function algebraic notation parser, among many others.
+
+License
+=======
+
+    MIT License. See header of pyparsing.py
+
+History
+=======
+
+    See CHANGES file.
+
+.. |Build Status| image:: https://travis-ci.org/pyparsing/pyparsing.svg?branch=master
+   :target: https://travis-ci.org/pyparsing/pyparsing
diff --git a/docs/CODE_OF_CONDUCT.rst b/docs/CODE_OF_CONDUCT.rst
new file mode 100644
index 0000000..96e0ba2
--- /dev/null
+++ b/docs/CODE_OF_CONDUCT.rst
@@ -0,0 +1 @@
+.. include:: ../CODE_OF_CONDUCT.rst
diff --git a/HowToUsePyparsing.rst b/docs/HowToUsePyparsing.rst
index 01b5026..01b5026 100644
--- a/HowToUsePyparsing.rst
+++ b/docs/HowToUsePyparsing.rst
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d039bc2
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = PyParsing
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+\ No newline at end of file
diff --git a/pyparsingClassDiagram.JPG b/docs/_static/pyparsingClassDiagram.jpg
index ef10424..ef10424 100644
--- a/pyparsingClassDiagram.JPG
+++ b/docs/_static/pyparsingClassDiagram.jpg
diff --git a/pyparsingClassDiagram.PNG b/docs/_static/pyparsingClassDiagram.png
index f59baaf..f59baaf 100644
--- a/pyparsingClassDiagram.PNG
+++ b/docs/_static/pyparsingClassDiagram.png
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..b4a411c
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
+
+from pyparsing import __version__ as pyparsing_version
+
+# -- Project information -----------------------------------------------------
+
+project = 'PyParsing'
+copyright = '2018, Paul T. McGuire'
+author = 'Paul T. McGuire'
+
+# The short X.Y version
+version = pyparsing_version
+# The full version, including alpha/beta/rc tags
+release = pyparsing_version
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PyParsingdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'PyParsing.tex', 'PyParsing Documentation',
+     'Paul T. McGuire', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pyparsing', 'PyParsing Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'PyParsing', 'PyParsing Documentation',
+     author, 'PyParsing', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+epub_author = author
+epub_publisher = author
+epub_copyright = copyright
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------
diff --git a/docs/conf_old.py b/docs/conf_old.py
new file mode 100644
index 0000000..776a8b7
--- /dev/null
+++ b/docs/conf_old.py
@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'PyParsing'
+copyright = '2018, Paul T. McGuire'
+author = 'Paul T. McGuire'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+# language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'conf.py']
+
+# The name of the Pygments (syntax highlighting) style to use.
+# pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'PyParsingdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'PyParsing.tex', 'PyParsing Documentation',
+     'Paul T. McGuire', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pyparsing', 'PyParsing Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'PyParsing', 'PyParsing Documentation',
+     author, 'PyParsing', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Extension configuration -------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..e5abc7c
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,23 @@
+.. PyParsing documentation master file, created by
+   sphinx-quickstart on Mon Nov 19 15:06:52 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to PyParsing's documentation!
+=====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   HowToUsePyparsing
+   modules
+   CODE_OF_CONDUCT
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/modules.rst b/docs/modules.rst
new file mode 100644
index 0000000..6163a45
--- /dev/null
+++ b/docs/modules.rst
@@ -0,0 +1,7 @@
+pyparsing
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   pyparsing
diff --git a/docs/pyparsing.rst b/docs/pyparsing.rst
new file mode 100644
index 0000000..6d9d44c
--- /dev/null
+++ b/docs/pyparsing.rst
@@ -0,0 +1,7 @@
+pyparsing module
+================
+
+.. automodule:: pyparsing
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/pyparsing.py b/pyparsing.py
index c20f2a0..7844f12 100644
--- a/pyparsing.py
+++ b/pyparsing.py
@@ -28,16 +28,18 @@ __doc__ = \
 pyparsing module - Classes and methods to define and execute parsing grammars
 =============================================================================
 
-The pyparsing module is an alternative approach to creating and executing simple grammars,
-vs. the traditional lex/yacc approach, or the use of regular expressions.  With pyparsing, you
-don't need to learn a new syntax for defining grammars or matching expressions - the parsing module
-provides a library of classes that you use to construct the grammar directly in Python.
+The pyparsing module is an alternative approach to creating and
+executing simple grammars, vs. the traditional lex/yacc approach, or the
+use of regular expressions.  With pyparsing, you don't need to learn
+a new syntax for defining grammars or matching expressions - the parsing
+module provides a library of classes that you use to construct the
+grammar directly in Python.
 
 Here is a program to parse "Hello, World!" (or any greeting of the form
-C{"<salutation>, <addressee>!"}), built up using :class:`Word`, :class:`Literal`, and :class:`And` elements
-(:class:`'+'<ParserElement.__add__>` operator gives :class:`And` expressions, strings are auto-converted to
-:class:`Literal` expressions)::
-
+:code:`"<salutation>, <addressee>!"`), built up using :class:`Word`,
+:class:`Literal`, and :class:`And` elements
+(:code:`ParserElement.__add__` operator gives :class:`And` expressions,
+strings are auto-converted to :class:`Literal` expressions)::
     from pyparsing import Word, alphas
 
     # define grammar of a greeting
@@ -47,7 +49,6 @@ C{"<salutation>, <addressee>!"}), built up using :class:`Word`, :class:`Literal`
     print (hello, "->", greet.parseString(hello))
 
 The program outputs the following::
-
     Hello, World! -> ['Hello', ',', 'World', '!']
 
 The Python representation of the grammar is quite readable, owing to the self-explanatory
@@ -278,6 +279,7 @@ class ParseException(ParseBaseException):
      - line - returns the line containing the exception text
 
     Example::
+
         try:
             Word(nums).setName("integer").parseString("ABC")
         except ParseException as pe:
@@ -285,6 +287,7 @@ class ParseException(ParseBaseException):
             print("column: {}".format(pe.col))
 
     prints::
+
        Expected integer (at char 0), (line:1, col:1)
         column: 1
     """
@@ -335,11 +338,12 @@ class _ParseResultsWithOffset(object):
 class ParseResults(object):
     """
     Structured parse results, to provide multiple means of access to the parsed data:
-       - as a list (C{len(results)})
-       - by list index (C{results[0], results[1]}, etc.)
-       - by attribute (C{results.<resultsName>} - see :class:`ParserElement.setResultsName`)
+       - as a list (:code:`len(results)`)
+       - by list index (:code:`results[0], results[1]`, etc.)
+       - by attribute (:code:`results.<resultsName>` - see :class:`ParserElement.setResultsName`)
 
     Example::
+
         integer = Word(nums)
         date_str = (integer.setResultsName("year") + '/'
                         + integer.setResultsName("month") + '/'
@@ -359,7 +363,9 @@ class ParseResults(object):
         test("'month' in result")
         test("'minutes' in result")
         test("result.dump()", str)
+
     prints::
+
         list(result) -> ['1999', '/', '12', '/', '31']
         result[0] -> '1999'
         result['month'] -> '12'
@@ -521,14 +527,14 @@ class ParseResults(object):
 
     def pop( self, *args, **kwargs):
         """
-        Removes and returns item at specified index (default=C{last}).
-        Supports both ``list`` and ``dict`` semantics for C{pop()}. If passed no
-        argument or an integer argument, it will use ``list`` semantics
-        and pop tokens from the list of parsed tokens. If passed a
-        non-integer argument (most likely a string), it will use ``dict``
-        semantics and pop the corresponding value from any defined
-        results names. A second default return value argument is
-        supported, just as in C{dict.pop()}.
+        Removes and returns item at specified index (default=:code:`last`).
+        Supports both ``list`` and ``dict`` semantics for :code:`pop()`. If
+        passed no argument or an integer argument, it will use ``list``
+        semantics and pop tokens from the list of parsed tokens. If passed
+        a non-integer argument (most likely a string), it will use ``dict``
+        semantics and pop the corresponding value from any defined results
+        names. A second default return value argument is supported, just as in
+        :code:`dict.pop()`.
 
         Example::
             def remove_first(tokens):
@@ -574,10 +580,10 @@ class ParseResults(object):
     def get(self, key, defaultValue=None):
         """
         Returns named result matching the given key, or if there is no
-        such name, then returns the given C{defaultValue} or ``None`` if no
-        C{defaultValue} is specified.
+        such name, then returns the given :code:`defaultValue` or ``None`` if no
+        :code:`defaultValue` is specified.
 
-        Similar to C{dict.get()}.
+        Similar to :code:`dict.get()`.
 
         Example::
             integer = Word(nums)
@@ -597,7 +603,7 @@ class ParseResults(object):
         """
         Inserts new element at location index in the list of parsed tokens.
 
-        Similar to C{list.insert()}.
+        Similar to :code:`list.insert()`.
 
         Example::
             print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']
@@ -765,7 +771,7 @@ class ParseResults(object):
 
     def copy( self ):
         """
-        Returns a new copy of a C{ParseResults} object.
+        Returns a new copy of a :code:`ParseResults` object.
         """
         ret = ParseResults( self.__toklist )
         ret.__tokdict = dict(self.__tokdict.items())
@@ -881,9 +887,9 @@ class ParseResults(object):
 
     def dump(self, indent='', depth=0, full=True):
         """
-        Diagnostic method for listing out the contents of a C{ParseResults}.
-        Accepts an optional C{indent} argument so that this string can be embedded
-        in a nested display of other data.
+        Diagnostic method for listing out the contents of
+        a :code:`ParseResults`. Accepts an optional :code:`indent` argument so
+        that this string can be embedded in a nested display of other data.
 
         Example::
             integer = Word(nums)
@@ -926,9 +932,9 @@ class ParseResults(object):
 
     def pprint(self, *args, **kwargs):
         """
-        Pretty-printer for parsed results as a list, using the C{pprint} module.
+        Pretty-printer for parsed results as a list, using the :code:`pprint` module.
         Accepts additional positional or keyword args as defined for the
-        C{pprint.pprint} method. (U{http://docs.python.org/3/library/pprint.html#pprint.pprint})
+        `:code:`pprint.pprint` method<http://docs.python.org/3/library/pprint.html#pprint.pprint>`__.
 
         Example::
             ident = Word(alphas, alphanums)
@@ -981,10 +987,11 @@ def col (loc,strg):
    The first column is number 1.
 
    Note: the default parsing behavior is to expand tabs in the input string
-   before starting the parsing process.  See :class:`I{ParserElement.parseString`<ParserElement.parseString>} for more information
-   on parsing strings containing C{<TAB>}s, and suggested methods to maintain a
-   consistent view of the parsed string, the parse location, and line and column
-   positions within the parsed string.
+   before starting the parsing process.  See
+   :class:`ParserElement.parseString` for more
+   information on parsing strings containing :code:`<TAB>`s, and suggested
+   methods to maintain a consistent view of the parsed string, the parse
+   location, and line and column positions within the parsed string.
    """
     s = strg
     return 1 if 0<loc<len(s) and s[loc-1] == '\n' else loc - s.rfind("\n", 0, loc)
@@ -994,10 +1001,10 @@ def lineno(loc,strg):
    The first line is number 1.
 
    Note: the default parsing behavior is to expand tabs in the input string
-   before starting the parsing process.  See :class:`I{ParserElement.parseString`<ParserElement.parseString>} for more information
-   on parsing strings containing C{<TAB>}s, and suggested methods to maintain a
-   consistent view of the parsed string, the parse location, and line and column
-   positions within the parsed string.
+   before starting the parsing process.  See :class:`ParserElement.parseString`
+   for more information on parsing strings containing :code:`<TAB>`s, and
+   suggested methods to maintain a consistent view of the parsed string, the
+   parse location, and line and column positions within the parsed string.
    """
     return strg.count("\n",0,loc) + 1
 
@@ -1177,8 +1184,9 @@ class ParserElement(object):
 
     def copy( self ):
         """
-        Make a copy of this C{ParserElement}.  Useful for defining different parse actions
-        for the same parsing pattern, using copies of the original parse element.
+        Make a copy of this :code:`ParserElement`.  Useful for defining
+        different parse actions for the same parsing pattern, using copies of
+        the original parse element.
 
         Example::
             integer = Word(nums).setParseAction(lambda toks: int(toks[0]))
@@ -1188,7 +1196,7 @@ class ParserElement(object):
             print(OneOrMore(integerK | integerM | integer).parseString("5K 100 640K 256M"))
         prints::
             [5120, 100, 655360, 268435456]
-        Equivalent form of C{expr.copy()} is just C{expr()}::
+        Equivalent form of :code:`expr.copy()` is just :code:`expr()`::
             integerM = integer().addParseAction(lambda toks: toks[0]*1024*1024) + Suppress("M")
         """
         cpy = copy.copy( self )
@@ -1216,13 +1224,13 @@ class ParserElement(object):
         """
         Define name for referencing matching tokens as a nested attribute
         of the returned parse results.
-        NOTE: this returns a *copy* of the original C{ParserElement} object;
+        NOTE: this returns a *copy* of the original :code:`ParserElement` object;
         this is so that the client can define a basic element, such as an
         integer, and reference it in multiple places with different names.
 
         You can also set results names using the abbreviated syntax,
-        C{expr("name")} in place of C{expr.setResultsName("name")} -
-        see :class:`I{__call__`<__call__>}.
+        :code:`expr("name")` in place of :code:`expr.setResultsName("name")`
+        - see :class:`__call__`.
 
         Example::
             date_str = (integer.setResultsName("year") + '/'
@@ -1242,7 +1250,7 @@ class ParserElement(object):
 
     def setBreak(self,breakFlag = True):
         """Method to invoke the Python pdb debugger when this element is
-           about to be parsed. Set C{breakFlag} to True to enable, False to
+           about to be parsed. Set :code:`breakFlag` to True to enable, False to
            disable.
         """
         if breakFlag:
@@ -1261,23 +1269,23 @@ class ParserElement(object):
     def setParseAction( self, *fns, **kwargs ):
         """
         Define one or more actions to perform when successfully matching parse element definition.
-        Parse action fn is a callable method with 0-3 arguments, called as C{fn(s,loc,toks)},
-        C{fn(loc,toks)}, C{fn(toks)}, or just C{fn()}, where:
+        Parse action fn is a callable method with 0-3 arguments, called as :code:`fn(s,loc,toks)`,
+        :code:`fn(loc,toks)`, :code:`fn(toks)`, or just :code:`fn()`, where:
          - s   = the original string being parsed (see note below)
          - loc = the location of the matching substring
-         - toks = a list of the matched tokens, packaged as a C{:class:`ParseResults`} object
+         - toks = a list of the matched tokens, packaged as a :code:`:class:`ParseResults`` object
         If the functions in fns modify the tokens, they can return them as the return
         value from fn, and the modified list of tokens will replace the original.
         Otherwise, fn does not need to return any value.
 
         Optional keyword arguments:
-         - callDuringTry = (default=C{False}) indicate if parse action should be run during lookaheads and alternate testing
+         - callDuringTry = (default=:code:`False`) indicate if parse action should be run during lookaheads and alternate testing
 
         Note: the default parsing behavior is to expand tabs in the input string
-        before starting the parsing process.  See :class:`I{parseString`<parseString>} for more information
-        on parsing strings containing C{<TAB>}s, and suggested methods to maintain a
-        consistent view of the parsed string, the parse location, and line and column
-        positions within the parsed string.
+        before starting the parsing process.  See :class:`parseString for more
+        information on parsing strings containing :code:`<TAB>`s, and suggested
+        methods to maintain a consistent view of the parsed string, the parse
+        location, and line and column positions within the parsed string.
 
         Example::
             integer = Word(nums)
@@ -1298,9 +1306,9 @@ class ParserElement(object):
 
     def addParseAction( self, *fns, **kwargs ):
         """
-        Add one or more parse actions to expression's list of parse actions. See :class:`I{setParseAction`<setParseAction>}.
+        Add one or more parse actions to expression's list of parse actions. See :class:`setParseAction`.
 
-        See examples in :class:`I{copy`<copy>}.
+        See examples in :class:`copy`.
         """
         self.parseAction += list(map(_trim_arity, list(fns)))
         self.callDuringTry = self.callDuringTry or kwargs.get("callDuringTry", False)
@@ -1308,8 +1316,8 @@ class ParserElement(object):
 
     def addCondition(self, *fns, **kwargs):
         """Add a boolean predicate function to expression's list of parse actions. See
-        :class:`I{setParseAction`<setParseAction>} for function call signatures. Unlike C{setParseAction},
-        functions passed to C{addCondition} need to return boolean success/fail of the condition.
+        :class:`setParseAction` for function call signatures. Unlike :code:`setParseAction`,
+        functions passed to :code:`addCondition` need to return boolean success/fail of the condition.
 
         Optional keyword arguments:
          - message = define a custom message to be used in the raised exception
@@ -1336,12 +1344,12 @@ class ParserElement(object):
     def setFailAction( self, fn ):
         """Define action to perform if parsing fails at this expression.
            Fail acton fn is a callable function that takes the arguments
-           C{fn(s,loc,expr,err)} where:
+           :code:`fn(s,loc,expr,err)` where:
             - s = string being parsed
             - loc = location where expression match was attempted and failed
             - expr = the parse expression that failed
             - err = the exception thrown
-           The function returns no value.  It may throw C{:class:`ParseFatalException`}
+           The function returns no value.  It may throw :code:`:class:`ParseFatalException``
            if it is desired to stop parsing immediately."""
         self.failAction = fn
         return self
@@ -1602,7 +1610,7 @@ class ParserElement(object):
            both valid results and parsing exceptions.
 
            Parameters:
-            - cache_size_limit - (default=C{128}) - if an integer value is provided
+            - cache_size_limit - (default=:code:`128`) - if an integer value is provided
               will limit the size of the packrat cache; if None is passed, then
               the cache size will be unbounded; if 0 is passed, the cache will
               be effectively disabled.
@@ -1610,10 +1618,10 @@ class ParserElement(object):
            This speedup may break existing programs that use parse actions that
            have side-effects.  For this reason, packrat parsing is disabled when
            you first import pyparsing.  To activate the packrat feature, your
-           program must call the class method C{ParserElement.enablePackrat()}.  If
-           your program uses C{psyco} to "compile as you go", you must call
-           C{enablePackrat} before calling C{psyco.full()}.  If you do not do this,
-           Python will crash.  For best results, call C{enablePackrat()} immediately
+           program must call the class method :code:`ParserElement.enablePackrat()`.  If
+           your program uses :code:`psyco` to "compile as you go", you must call
+           :code:`enablePackrat` before calling :code:`psyco.full()`.  If you do not do this,
+           Python will crash.  For best results, call :code:`enablePackrat()` immediately
            after importing pyparsing.
 
            Example::
@@ -1635,21 +1643,21 @@ class ParserElement(object):
         expression has been built.
 
         If you want the grammar to require that the entire input string be
-        successfully parsed, then set C{parseAll} to True (equivalent to ending
-        the grammar with C{:class:`StringEnd()`}).
+        successfully parsed, then set :code:`parseAll` to True (equivalent to ending
+        the grammar with :code:`:class:`StringEnd()``).
 
-        Note: C{parseString} implicitly calls C{expandtabs()} on the input string,
+        Note: :code:`parseString` implicitly calls :code:`expandtabs()` on the input string,
         in order to report proper column numbers in parse actions.
         If the input string contains tabs and
-        the grammar uses parse actions that use the C{loc} argument to index into the
+        the grammar uses parse actions that use the :code:`loc` argument to index into the
         string being parsed, you can ensure you have a consistent view of the input
         string by:
-         - calling C{parseWithTabs} on your grammar before calling C{parseString}
-           (see :class:`I{parseWithTabs`<parseWithTabs>})
-         - define your parse action using the full C{(s,loc,toks)} signature, and
-           reference the input string using the parse action's C{s} argument
+         - calling :code:`parseWithTabs` on your grammar before calling :code:`parseString`
+           (see :class:`parseWithTabs`)
+         - define your parse action using the full :code:`(s,loc,toks)` signature, and
+           reference the input string using the parse action's :code:`s` argument
          - explictly expand the tabs in your input string before calling
-           C{parseString}
+           :code:`parseString`
 
         Example::
             Word('a').parseString('aaaaabaaa')  # -> ['aaaaa']
@@ -1682,11 +1690,11 @@ class ParserElement(object):
         """
         Scan the input string for expression matches.  Each match will return the
         matching tokens, start location, and end location.  May be called with optional
-        C{maxMatches} argument, to clip scanning after 'n' matches are found.  If
-        C{overlap} is specified, then overlapping matches will be reported.
+        :code:`maxMatches` argument, to clip scanning after 'n' matches are found.  If
+        :code:`overlap` is specified, then overlapping matches will be reported.
 
         Note that the start and end locations are reported relative to the string
-        being parsed.  See :class:`I{parseString`<parseString>} for more information on parsing
+        being parsed.  See :class:`parseString` for more information on parsing
         strings with embedded tabs.
 
         Example::
@@ -1751,12 +1759,12 @@ class ParserElement(object):
 
     def transformString( self, instring ):
         """
-        Extension to C{:class:`scanString`}, to modify matching text with modified tokens that may
-        be returned from a parse action.  To use C{transformString}, define a grammar and
+        Extension to :code:`:class:`scanString``, to modify matching text with modified tokens that may
+        be returned from a parse action.  To use :code:`transformString`, define a grammar and
         attach a parse action to it that modifies the returned token list.
-        Invoking C{transformString()} on a target string will then scan for matches,
+        Invoking :code:`transformString()` on a target string will then scan for matches,
         and replace the matched text patterns according to the logic in the parse
-        action.  C{transformString()} returns the resulting transformed string.
+        action.  :code:`transformString()` returns the resulting transformed string.
 
         Example::
             wd = Word(alphas)
@@ -1794,9 +1802,9 @@ class ParserElement(object):
 
     def searchString( self, instring, maxMatches=_MAX_INT ):
         """
-        Another extension to C{:class:`scanString`}, simplifying the access to the tokens found
+        Another extension to :code:`:class:`scanString``, simplifying the access to the tokens found
         to match the given parse expression.  May be called with optional
-        C{maxMatches} argument, to clip searching after 'n' matches are found.
+        :code:`maxMatches` argument, to clip searching after 'n' matches are found.
 
         Example::
             # a capitalized word starts with an uppercase letter, followed by zero or more lowercase letters
@@ -1822,8 +1830,8 @@ class ParserElement(object):
     def split(self, instring, maxsplit=_MAX_INT, includeSeparators=False):
         """
         Generator method to split a string using the given expression as a separator.
-        May be called with optional C{maxsplit} argument, to limit the number of splits;
-        and the optional C{includeSeparators} argument (default=C{False}), if the separating
+        May be called with optional :code:`maxsplit` argument, to limit the number of splits;
+        and the optional :code:`includeSeparators` argument (default=:code:`False`), if the separating
         matching text should be included in the split results.
 
         Example::
@@ -1843,7 +1851,7 @@ class ParserElement(object):
 
     def __add__(self, other ):
         """
-        Implementation of + operator - returns C{:class:`And`}. Adding strings to a ParserElement
+        Implementation of + operator - returns :code:`:class:`And``. Adding strings to a ParserElement
         converts them to :class:`Literal`s by default.
 
         Example::
@@ -1863,7 +1871,7 @@ class ParserElement(object):
 
     def __radd__(self, other ):
         """
-        Implementation of + operator when left operand is not a C{:class:`ParserElement`}
+        Implementation of + operator when left operand is not a :code:`:class:`ParserElement``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -1875,7 +1883,7 @@ class ParserElement(object):
 
     def __sub__(self, other):
         """
-        Implementation of - operator, returns C{:class:`And`} with error stop
+        Implementation of - operator, returns :code:`:class:`And`` with error stop
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -1887,7 +1895,7 @@ class ParserElement(object):
 
     def __rsub__(self, other ):
         """
-        Implementation of - operator when left operand is not a C{:class:`ParserElement`}
+        Implementation of - operator when left operand is not a :code:`:class:`ParserElement``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -1899,23 +1907,23 @@ class ParserElement(object):
 
     def __mul__(self,other):
         """
-        Implementation of * operator, allows use of C{expr * 3} in place of
-        C{expr + expr + expr}.  Expressions may also me multiplied by a 2-integer
-        tuple, similar to C{{min,max}} multipliers in regular expressions.  Tuples
+        Implementation of * operator, allows use of :code:`expr * 3` in place of
+        :code:`expr + expr + expr`.  Expressions may also me multiplied by a 2-integer
+        tuple, similar to :code:`{min,max`} multipliers in regular expressions.  Tuples
         may also include ``None`` as in:
-         - C{expr*(n,None)} or C{expr*(n,)} is equivalent
-              to C{expr*n + :class:`ZeroOrMore`(expr)}
-              (read as "at least n instances of C{expr}")
-         - C{expr*(None,n)} is equivalent to C{expr*(0,n)}
-              (read as "0 to n instances of C{expr}")
-         - C{expr*(None,None)} is equivalent to C{:class:`ZeroOrMore`(expr)}
-         - C{expr*(1,None)} is equivalent to C{:class:`OneOrMore`(expr)}
-
-        Note that C{expr*(None,n)} does not raise an exception if
+         - :code:`expr*(n,None)` or :code:`expr*(n,)` is equivalent
+              to :code:`expr*n + :class:`ZeroOrMore`(expr)`
+              (read as "at least n instances of :code:`expr`")
+         - :code:`expr*(None,n)` is equivalent to :code:`expr*(0,n)`
+              (read as "0 to n instances of :code:`expr`")
+         - :code:`expr*(None,None)` is equivalent to :code:`:class:`ZeroOrMore`(expr)`
+         - :code:`expr*(1,None)` is equivalent to :code:`:class:`OneOrMore`(expr)`
+
+        Note that :code:`expr*(None,n)` does not raise an exception if
         more than n exprs exist in the input stream; that is,
-        C{expr*(None,n)} does not enforce a maximum number of expr
+        :code:`expr*(None,n)` does not enforce a maximum number of expr
         occurrences.  If this behavior is desired, then write
-        C{expr*(None,n) + ~expr}
+        :code:`expr*(None,n) + ~expr`
         """
         if isinstance(other,int):
             minElements, optElements = other,0
@@ -1970,7 +1978,7 @@ class ParserElement(object):
 
     def __or__(self, other ):
         """
-        Implementation of | operator - returns C{:class:`MatchFirst`}
+        Implementation of | operator - returns :code:`:class:`MatchFirst``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -1982,7 +1990,7 @@ class ParserElement(object):
 
     def __ror__(self, other ):
         """
-        Implementation of | operator when left operand is not a C{:class:`ParserElement`}
+        Implementation of | operator when left operand is not a :code:`:class:`ParserElement``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -1994,7 +2002,7 @@ class ParserElement(object):
 
     def __xor__(self, other ):
         """
-        Implementation of ^ operator - returns C{:class:`Or`}
+        Implementation of ^ operator - returns :code:`:class:`Or``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -2006,7 +2014,7 @@ class ParserElement(object):
 
     def __rxor__(self, other ):
         """
-        Implementation of ^ operator when left operand is not a C{:class:`ParserElement`}
+        Implementation of ^ operator when left operand is not a :code:`:class:`ParserElement``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -2018,7 +2026,7 @@ class ParserElement(object):
 
     def __and__(self, other ):
         """
-        Implementation of & operator - returns C{:class:`Each`}
+        Implementation of & operator - returns :code:`:class:`Each``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -2030,7 +2038,7 @@ class ParserElement(object):
 
     def __rand__(self, other ):
         """
-        Implementation of & operator when left operand is not a C{:class:`ParserElement`}
+        Implementation of & operator when left operand is not a :code:`:class:`ParserElement``
         """
         if isinstance( other, basestring ):
             other = ParserElement._literalStringClass( other )
@@ -2042,18 +2050,18 @@ class ParserElement(object):
 
     def __invert__( self ):
         """
-        Implementation of ~ operator - returns C{:class:`NotAny`}
+        Implementation of ~ operator - returns :code:`:class:`NotAny``
         """
         return NotAny( self )
 
     def __call__(self, name=None):
         """
-        Shortcut for C{:class:`setResultsName`}, with C{listAllMatches=False}.
+        Shortcut for :code:`:class:`setResultsName``, with :code:`listAllMatches=False`.
 
-        If C{name} is given with a trailing C{'*'} character, then C{listAllMatches} will be
-        passed as C{True}.
+        If :code:`name` is given with a trailing :code:`'*'` character, then :code:`listAllMatches` will be
+        passed as :code:`True`.
 
-        If C{name} is omitted, same as calling C{:class:`copy`}.
+        If :code:`name` is omitted, same as calling :code:`:class:`copy``.
 
         Example::
             # these are equivalent
@@ -2067,7 +2075,7 @@ class ParserElement(object):
 
     def suppress( self ):
         """
-        Suppresses the output of this C{ParserElement}; useful to keep punctuation from
+        Suppresses the output of this :code:`ParserElement`; useful to keep punctuation from
         cluttering up returned output.
         """
         return Suppress( self )
@@ -2075,7 +2083,7 @@ class ParserElement(object):
     def leaveWhitespace( self ):
         """
         Disables the skipping of whitespace before matching the characters in the
-        C{ParserElement}'s defined pattern.  This is normally only used internally by
+        :code:`ParserElement`'s defined pattern.  This is normally only used internally by
         the pyparsing module, but may be needed in some whitespace-sensitive grammars.
         """
         self.skipWhitespace = False
@@ -2092,9 +2100,9 @@ class ParserElement(object):
 
     def parseWithTabs( self ):
         """
-        Overrides default behavior to expand C{<TAB>}s to spaces before parsing the input string.
-        Must be called before C{parseString} when the input grammar contains elements that
-        match C{<TAB>} characters.
+        Overrides default behavior to expand :code:`<TAB>`s to spaces before parsing the input string.
+        Must be called before :code:`parseString` when the input grammar contains elements that
+        match :code:`<TAB>` characters.
         """
         self.keepTabs = True
         return self
@@ -2135,7 +2143,7 @@ class ParserElement(object):
     def setDebug( self, flag=True ):
         """
         Enable display of debugging messages while doing pattern matching.
-        Set C{flag} to True to enable, False to disable.
+        Set :code:`flag` to True to enable, False to disable.
 
         Example::
             wd = Word(alphas).setName("alphaword")
@@ -2161,11 +2169,11 @@ class ParserElement(object):
 
         The output shown is that produced by the default debug actions - custom debug actions can be
         specified using :class:`setDebugActions`. Prior to attempting
-        to match the C{wd} expression, the debugging message C{"Match <exprname> at loc <n>(<line>,<col>)"}
-        is shown. Then if the parse succeeds, a C{"Matched"} message is shown, or an C{"Exception raised"}
+        to match the :code:`wd` expression, the debugging message :code:`"Match <exprname> at loc <n>(<line>,<col>)"`
+        is shown. Then if the parse succeeds, a :code:`"Matched"` message is shown, or an :code:`"Exception raised"`
         message is shown. Also note the use of :class:`setName` to assign a human-readable name to the expression,
         which makes debugging and exception messages easier to understand - for instance, the default
-        name created for the C{Word} expression without calling C{setName} is C{"W:(ABCD...)"}.
+        name created for the :code:`Word` expression without calling :code:`setName` is :code:`"W:(ABCD...)"`.
         """
         if flag:
             self.setDebugActions( _defaultStartDebugAction, _defaultSuccessDebugAction, _defaultExceptionDebugAction )
@@ -2240,7 +2248,7 @@ class ParserElement(object):
 
         Parameters:
          - testString - to test against this expression for a match
-         - parseAll - (default=C{True}) - flag to pass to C{:class:`parseString`} when running tests
+         - parseAll - (default=:code:`True`) - flag to pass to :code:`:class:`parseString`` when running tests
 
         Example::
             expr = Word(nums)
@@ -2260,16 +2268,16 @@ class ParserElement(object):
 
         Parameters:
          - tests - a list of separate test strings, or a multiline string of test strings
-         - parseAll - (default=C{True}) - flag to pass to C{:class:`parseString`} when running tests
-         - comment - (default=C{'#'}) - expression for indicating embedded comments in the test
+         - parseAll - (default=:code:`True`) - flag to pass to :code:`:class:`parseString`` when running tests
+         - comment - (default=:code:`'#'`) - expression for indicating embedded comments in the test
               string; pass None to disable comment filtering
-         - fullDump - (default=C{True}) - dump results as list followed by results names in nested outline;
+         - fullDump - (default=:code:`True`) - dump results as list followed by results names in nested outline;
               if False, only dump nested list
-         - printResults - (default=C{True}) prints test output to stdout
-         - failureTests - (default=C{False}) indicates if these tests are expected to fail parsing
+         - printResults - (default=:code:`True`) prints test output to stdout
+         - failureTests - (default=:code:`False`) indicates if these tests are expected to fail parsing
 
         Returns: a (success, results) tuple, where success indicates that all tests succeeded
-        (or failed if C{failureTests} is True), and the results contain a list of lines of each
+        (or failed if :code:`failureTests` is True), and the results contain a list of lines of each
         test's output
 
         Example::
@@ -2386,7 +2394,7 @@ class ParserElement(object):
 
 class Token(ParserElement):
     """
-    Abstract C{ParserElement} subclass, for defining atomic matching patterns.
+    Abstract :code:`ParserElement` subclass, for defining atomic matching patterns.
     """
     def __init__( self ):
         super(Token,self).__init__( savelist=False )
@@ -2462,13 +2470,13 @@ ParserElement._literalStringClass = Literal
 class Keyword(Token):
     """
     Token to exactly match a specified string as a keyword, that is, it must be
-    immediately followed by a non-keyword character.  Compare with C{:class:`Literal`}:
-     - C{Literal("if")} will match the leading C{'if'} in C{'ifAndOnlyIf'}.
-     - C{Keyword("if")} will not; it will only match the leading C{'if'} in C{'if x=1'}, or C{'if(y==2)'}
+    immediately followed by a non-keyword character.  Compare with :code:`:class:`Literal``:
+     - :code:`Literal("if")` will match the leading :code:`'if'` in :code:`'ifAndOnlyIf'`.
+     - :code:`Keyword("if")` will not; it will only match the leading :code:`'if'` in :code:`'if x=1'`, or :code:`'if(y==2)'`
     Accepts two optional constructor arguments in addition to the keyword string:
-     - C{identChars} is a string of characters that would be valid identifier characters,
+     - :code:`identChars` is a string of characters that would be valid identifier characters,
           defaulting to all alphanumerics + "_" and "$"
-     - C{caseless} allows case-insensitive matching, default is C{False}.
+     - :code:`caseless` allows case-insensitive matching, default is :code:`False`.
 
     Example::
         Keyword("start").parseString("start")  # -> ['start']
@@ -2568,15 +2576,15 @@ class CaselessKeyword(Keyword):
 class CloseMatch(Token):
     """
     A variation on :class:`Literal` which matches "close" matches, that is,
-    strings with at most 'n' mismatching characters. C{CloseMatch} takes parameters:
-     - C{match_string} - string to be matched
-     - C{maxMismatches} - (C{default=1}) maximum number of mismatches allowed to count as a match
+    strings with at most 'n' mismatching characters. :code:`CloseMatch` takes parameters:
+     - :code:`match_string` - string to be matched
+     - :code:`maxMismatches` - (:code:`default=1`) maximum number of mismatches allowed to count as a match
 
     The results from a successful parse will contain the matched text from the input string and the following named results:
-     - C{mismatches} - a list of the positions within the match_string where mismatches were found
-     - C{original} - the original match_string used to compare against the input string
+     - :code:`mismatches` - a list of the positions within the match_string where mismatches were found
+     - :code:`original` - the original match_string used to compare against the input string
 
-    If C{mismatches} is an empty list, then the match was an exact match.
+    If :code:`mismatches` is an empty list, then the match was an exact match.
 
     Example::
         patt = CloseMatch("ATCATCGAATGGA")
@@ -2632,19 +2640,19 @@ class Word(Token):
     Defined with string containing all allowed initial characters,
     an optional string containing allowed body characters (if omitted,
     defaults to the initial character set), and an optional minimum,
-    maximum, and/or exact length.  The default value for C{min} is 1 (a
-    minimum value < 1 is not valid); the default values for C{max} and C{exact}
+    maximum, and/or exact length.  The default value for :code:`min` is 1 (a
+    minimum value < 1 is not valid); the default values for :code:`max` and :code:`exact`
     are 0, meaning no maximum or exact length restriction. An optional
-    C{excludeChars} parameter can list characters that might be found in
-    the input C{bodyChars} string; useful to define a word of all printables
+    :code:`excludeChars` parameter can list characters that might be found in
+    the input :code:`bodyChars` string; useful to define a word of all printables
     except for one or two characters, for instance.
 
     :class:`srange` is useful for defining custom character set strings for defining
-    C{Word} expressions, using range notation from regular expression character sets.
+    :code:`Word` expressions, using range notation from regular expression character sets.
 
-    A common mistake is to use C{Word} to match a specific literal string, as in
-    C{Word("Address")}. Remember that C{Word} uses the string argument to define
-    I{sets} of matchable characters. This expression would match "Add", "AAA",
+    A common mistake is to use :code:`Word` to match a specific literal string, as in
+    :code:`Word("Address")`. Remember that :code:`Word` uses the string argument to define
+    *sets* of matchable characters. This expression would match "Add", "AAA",
     "dAred", or any other word made up of the characters 'A', 'd', 'r', 'e', and 's'.
     To match an exact literal string, use :class:`Literal` or :class:`Keyword`.
 
@@ -2787,7 +2795,7 @@ class Word(Token):
 
 class Char(Word):
     """
-    A short-cut class for defining C{Word(characters, exact=1)},
+    A short-cut class for defining :code:`Word(characters, exact=1)`,
     when defining a match of any single character in a string of characters.
     """
     def __init__(self, charset):
@@ -2800,14 +2808,14 @@ class Regex(Token):
     r"""
     Token for matching strings that match a given regular expression.
     Defined with string specifying the regular expression in a form recognized by the inbuilt Python re module.
-    If the given regex contains named groups (defined using C{(?P<name>...)}), these will be preserved as
+    If the given regex contains named groups (defined using :code:`(?P<name>...)`), these will be preserved as
     named parse results.
 
     Example::
         realnum = Regex(r"[+-]?\d+\.\d*")
         date = Regex(r'(?P<year>\d{4})-(?P<month>\d\d?)-(?P<day>\d\d?)')
         # ref: http://stackoverflow.com/questions/267399/how-do-you-match-only-valid-roman-numerals-with-a-regular-expression
-        roman = Regex(r"M{0,4}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})")
+        roman = Regex(r"M{0,4}(CM|CD|D?:code:`0,3`)(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})")
 
         make_html = Regex(r"(\w+):(.*?):").sub(r"<\1>\2</\1>")
         print(make_html.transformString("h1:main title:"))
@@ -2815,7 +2823,7 @@ class Regex(Token):
     """
     compiledREtype = type(re.compile("[A-Z]"))
     def __init__( self, pattern, flags=0, asGroupList=False, asMatch=False):
-        """The parameters C{pattern} and C{flags} are passed to the C{re.compile()} function as-is. See the Python C{re} module for an explanation of the acceptable patterns and flags."""
+        """The parameters :code:`pattern` and :code:`flags` are passed to the :code:`re.compile()` function as-is. See the Python :code:`re` module for an explanation of the acceptable patterns and flags."""
         super(Regex,self).__init__()
 
         if isinstance(pattern, basestring):
@@ -2882,7 +2890,7 @@ class Regex(Token):
     def sub(self, repl):
         """
         Return Regex with an attached parse action to transform the parsed
-        result as if called using C{re.sub(expr, repl, string)}.
+        result as if called using :code:`re.sub(expr, repl, string)`.
         """
         if self.asGroupList:
             warnings.warn("cannot use sub() with Regex(asGroupList=True)",
@@ -2910,10 +2918,10 @@ class QuotedString(Token):
         - quoteChar - string of one or more characters defining the quote delimiting string
         - escChar - character to escape quotes, typically backslash (default=``None``)
         - escQuote - special quote sequence to escape an embedded quote string (such as SQL's "" to escape an embedded ") (default=``None``)
-        - multiline - boolean indicating whether quotes can span multiple lines (default=C{False})
-        - unquoteResults - boolean indicating whether the matched text should be unquoted (default=C{True})
+        - multiline - boolean indicating whether quotes can span multiple lines (default=:code:`False`)
+        - unquoteResults - boolean indicating whether the matched text should be unquoted (default=:code:`True`)
         - endQuoteChar - string of one or more characters defining the end of the quote delimited string (default=``None`` => same as quoteChar)
-        - convertWhitespaceEscapes - convert escaped whitespace (C{'\t'}, C{'\n'}, etc.) to actual whitespace (default=C{True})
+        - convertWhitespaceEscapes - convert escaped whitespace (:code:`'\t'`, :code:`'\n'`, etc.) to actual whitespace (default=:code:`True`)
 
     Example::
         qs = QuotedString('"')
@@ -3041,11 +3049,11 @@ class QuotedString(Token):
 
 class CharsNotIn(Token):
     """
-    Token for matching words composed of characters I{not} in a given set (will
+    Token for matching words composed of characters *not* in a given set (will
     include whitespace in matched characters if not listed in the provided exclusion set - see example).
     Defined with string containing all disallowed characters, and an optional
-    minimum, maximum, and/or exact length.  The default value for C{min} is 1 (a
-    minimum value < 1 is not valid); the default values for C{max} and C{exact}
+    minimum, maximum, and/or exact length.  The default value for :code:`min` is 1 (a
+    minimum value < 1 is not valid); the default values for :code:`max` and :code:`exact`
     are 0, meaning no maximum or exact length restriction.
 
     Example::
@@ -3115,8 +3123,8 @@ class White(Token):
     Special matching class for matching whitespace.  Normally, whitespace is ignored
     by pyparsing grammars.  This class is included when some whitespace structures
     are significant.  Define with a string containing the whitespace characters to be
-    matched; default is C{" \\t\\r\\n"}.  Also takes optional C{min}, C{max}, and C{exact} arguments,
-    as defined for the C{:class:`Word`} class.
+    matched; default is :code:`" \\t\\r\\n"`.  Also takes optional :code:`min`, :code:`max`, and :code:`exact` arguments,
+    as defined for the :code:`:class:`Word`` class.
     """
     whiteStrs = {
         " " : "<SPC>",
@@ -3280,9 +3288,9 @@ class StringEnd(_PositionToken):
 class WordStart(_PositionToken):
     """
     Matches if the current position is at the beginning of a Word, and
-    is not preceded by any character in a given set of C{wordChars}
-    (default=C{printables}). To emulate the C{\b} behavior of regular expressions,
-    use C{WordStart(alphanums)}. C{WordStart} will also match at the beginning of
+    is not preceded by any character in a given set of :code:`wordChars`
+    (default=:code:`printables`). To emulate the :code:`\b` behavior of regular expressions,
+    use :code:`WordStart(alphanums)`. :code:`WordStart` will also match at the beginning of
     the string being parsed, or at the beginning of a line.
     """
     def __init__(self, wordChars = printables):
@@ -3300,9 +3308,9 @@ class WordStart(_PositionToken):
 class WordEnd(_PositionToken):
     """
     Matches if the current position is at the end of a Word, and
-    is not followed by any character in a given set of C{wordChars}
-    (default=C{printables}). To emulate the C{\b} behavior of regular expressions,
-    use C{WordEnd(alphanums)}. C{WordEnd} will also match at the end of
+    is not followed by any character in a given set of :code:`wordChars`
+    (default=:code:`printables`). To emulate the :code:`\b` behavior of regular expressions,
+    use :code:`WordEnd(alphanums)`. :code:`WordEnd` will also match at the end of
     the string being parsed, or at the end of a line.
     """
     def __init__(self, wordChars = printables):
@@ -3353,7 +3361,7 @@ class ParseExpression(ParserElement):
         return self
 
     def leaveWhitespace( self ):
-        """Extends C{leaveWhitespace} defined in base class, and also invokes C{leaveWhitespace} on
+        """Extends :code:`leaveWhitespace` defined in base class, and also invokes :code:`leaveWhitespace` on
            all contained expressions."""
         self.skipWhitespace = False
         self.exprs = [ e.copy() for e in self.exprs ]
@@ -3434,10 +3442,10 @@ class ParseExpression(ParserElement):
 
 class And(ParseExpression):
     """
-    Requires all given C{ParseExpression}s to be found in the given order.
+    Requires all given :code:`ParseExpression`s to be found in the given order.
     Expressions may be separated by whitespace.
-    May be constructed using the C{'+'} operator.
-    May also be constructed using the C{'-'} operator, which will suppress backtracking.
+    May be constructed using the :code:`'+'` operator.
+    May also be constructed using the :code:`'-'` operator, which will suppress backtracking.
 
     Example::
         integer = Word(nums)
@@ -3510,9 +3518,9 @@ class And(ParseExpression):
 
 class Or(ParseExpression):
     """
-    Requires that at least one C{ParseExpression} is found.
+    Requires that at least one :code:`ParseExpression` is found.
     If two expressions match, the expression that matches the longest string will be used.
-    May be constructed using the C{'^'} operator.
+    May be constructed using the :code:`'^'` operator.
 
     Example::
         # construct Or using '^' operator
@@ -3589,9 +3597,9 @@ class Or(ParseExpression):
 
 class MatchFirst(ParseExpression):
     """
-    Requires that at least one C{ParseExpression} is found.
+    Requires that at least one :code:`ParseExpression` is found.
     If two expressions match, the first one listed is the one that will match.
-    May be constructed using the C{'|'} operator.
+    May be constructed using the :code:`'|'` operator.
 
     Example::
         # construct MatchFirst using '|' operator
@@ -3657,9 +3665,9 @@ class MatchFirst(ParseExpression):
 
 class Each(ParseExpression):
     """
-    Requires all given C{ParseExpression}s to be found, but in any order.
+    Requires all given :code:`ParseExpression`s to be found, but in any order.
     Expressions may be separated by whitespace.
-    May be constructed using the C{'&'} operator.
+    May be constructed using the :code:`'&'` operator.
 
     Example::
         color = oneOf("RED ORANGE YELLOW GREEN BLUE PURPLE BLACK WHITE BROWN")
@@ -3781,7 +3789,7 @@ class Each(ParseExpression):
 
 class ParseElementEnhance(ParserElement):
     """
-    Abstract subclass of C{ParserElement}, for combining and post-processing parsed tokens.
+    Abstract subclass of :code:`ParserElement`, for combining and post-processing parsed tokens.
     """
     def __init__( self, expr, savelist=False ):
         super(ParseElementEnhance,self).__init__(savelist)
@@ -3858,10 +3866,10 @@ class ParseElementEnhance(ParserElement):
 
 class FollowedBy(ParseElementEnhance):
     """
-    Lookahead matching of the given parse expression.  C{FollowedBy}
-    does I{not} advance the parsing position within the input string, it only
+    Lookahead matching of the given parse expression.  :code:`FollowedBy`
+    does *not* advance the parsing position within the input string, it only
     verifies that the specified parse expression matches at the current
-    position.  C{FollowedBy} always returns a null token list. If any
+    position.  :code:`FollowedBy` always returns a null token list. If any
     results names are defined in the lookahead expression, those *will* be
     returned for access by name.
 
@@ -3887,10 +3895,10 @@ class FollowedBy(ParseElementEnhance):
 
 class PrecededBy(ParseElementEnhance):
     """
-    Lookbehind matching of the given parse expression.  C{PrecededBy}
+    Lookbehind matching of the given parse expression.  :code:`PrecededBy`
     does not advance the parsing position within the input string, it only
     verifies that the specified parse expression matches prior to the current
-    position.  C{PrecededBy} always returns a null token list, but if
+    position.  :code:`PrecededBy` always returns a null token list, but if
     a results name is defined on the given expression, it is returned.
 
     Parameters:
@@ -3960,10 +3968,10 @@ class PrecededBy(ParseElementEnhance):
 
 class NotAny(ParseElementEnhance):
     """
-    Lookahead to disallow matching with the given parse expression.  C{NotAny}
-    does I{not} advance the parsing position within the input string, it only
-    verifies that the specified parse expression does I{not} match at the current
-    position.  Also, C{NotAny} does I{not} skip over leading whitespace. C{NotAny}
+    Lookahead to disallow matching with the given parse expression.  :code:`NotAny`
+    does *not* advance the parsing position within the input string, it only
+    verifies that the specified parse expression does *not* match at the current
+    position.  Also, :code:`NotAny` does *not* skip over leading whitespace. :code:`NotAny`
     always returns a null token list.  May be constructed using the '~' operator.
 
     Example::
@@ -4183,7 +4191,7 @@ class SkipTo(ParseElementEnhance):
 
     Parameters:
      - expr - target expression marking the end of the data to be skipped
-     - include - (default=C{False}) if True, the target expression is also parsed
+     - include - (default=:code:`False`) if True, the target expression is also parsed
           (the skipped text and target expression are returned as a 2-element list).
      - ignore - (default=``None``) used to define grammars (typically quoted strings and
           comments) that might contain false matches to the target expression
@@ -4296,20 +4304,23 @@ class Forward(ParseElementEnhance):
     """
     Forward declaration of an expression to be defined later -
     used for recursive grammars, such as algebraic infix notation.
-    When the expression is known, it is assigned to the C{Forward} variable using the '<<' operator.
+    When the expression is known, it is assigned to the :code:`Forward` variable using the '<<' operator.
 
-    Note: take care when assigning to C{Forward} not to overlook precedence of operators.
+    Note: take care when assigning to :code:`Forward` not to overlook precedence of operators.
     Specifically, '|' has a lower precedence than '<<', so that::
         fwdExpr << a | b | c
+
     will actually be evaluated as::
         (fwdExpr << a) | b | c
+
     thereby leaving b and c out as parseable alternatives.  It is recommended that you
-    explicitly group the values inserted into the C{Forward}::
+    explicitly group the values inserted into the :code:`Forward`::
         fwdExpr << (a | b | c)
+
     Converting to use the '<<=' operator instead will avoid this problem.
 
     See :class:`ParseResults.pprint` for an example of a recursive parser created using
-    C{Forward}.
+    :code:`Forward`.
     """
     def __init__( self, other=None ):
         super(Forward,self).__init__( other, savelist=False )
@@ -4379,7 +4390,7 @@ class _ForwardNoRecurse(Forward):
 
 class TokenConverter(ParseElementEnhance):
     """
-    Abstract subclass of C{ParseExpression}, for converting parsed results.
+    Abstract subclass of :code:`ParseExpression`, for converting parsed results.
     """
     def __init__( self, expr, savelist=False ):
         super(TokenConverter,self).__init__( expr )#, savelist )
@@ -4389,7 +4400,7 @@ class Combine(TokenConverter):
     """
     Converter to concatenate all matching tokens to a single string.
     By default, the matching patterns must also be contiguous in the input string;
-    this can be disabled by specifying C{'adjacent=False'} in the constructor.
+    this can be disabled by specifying :code:`'adjacent=False'` in the constructor.
 
     Example::
         real = Word(nums) + '.' + Word(nums)
@@ -4431,7 +4442,7 @@ class Combine(TokenConverter):
 
 class Group(TokenConverter):
     """
-    Converter to return the matched tokens as a list - useful for returning tokens of C{:class:`ZeroOrMore`} and C{:class:`OneOrMore`} expressions.
+    Converter to return the matched tokens as a list - useful for returning tokens of :code:`:class:`ZeroOrMore`` and :code:`:class:`OneOrMore`` expressions.
 
     Example::
         ident = Word(alphas)
@@ -4561,8 +4572,9 @@ def traceParseAction(f):
     """
     Decorator for debugging parse actions.
 
-    When the parse action is called, this decorator will print C{">> entering I{method-name}(line:I{current_source_line}, I{parse_location}, I{matched_tokens})".}
-    When the parse action completes, the decorator will print C{"<<"} followed by the returned value, or any exception that the parse action raised.
+    When the parse action is called, this decorator will print :code:`">>
+    entering :code:`method-name`(line:*current_source_line*, *parse_location*, *matched_tokens*)".
+    When the parse action completes, the decorator will print :code:`"<<"` followed by the returned value, or any exception that the parse action raised.
 
     Example::
         wd = Word(alphas)
@@ -4605,8 +4617,8 @@ def delimitedList( expr, delim=",", combine=False ):
     """
     Helper to define a delimited list of expressions - the delimiter defaults to ','.
     By default, the list elements and delimiters can have intervening whitespace, and
-    comments, but this can be overridden by passing C{combine=True} in the constructor.
-    If C{combine} is set to C{True}, the matching tokens are returned as a single token
+    comments, but this can be overridden by passing :code:`combine=True` in the constructor.
+    If :code:`combine` is set to :code:`True`, the matching tokens are returned as a single token
     string, with the delimiters included; otherwise, the matching tokens are returned
     as a list of tokens, with the delimiters suppressed.
 
@@ -4628,7 +4640,7 @@ def countedArray( expr, intExpr=None ):
     where the leading integer tells how many expr expressions follow.
     The matched tokens returns the array of expr tokens as a list - the leading count token is suppressed.
 
-    If C{intExpr} is specified, it should be a pyparsing expression that produces an integer value.
+    If :code:`intExpr` is specified, it should be a pyparsing expression that produces an integer value.
 
     Example::
         countedArray(Word(alphas)).parseString('2 ab cd ef')  # -> ['ab', 'cd']
@@ -4668,10 +4680,10 @@ def matchPreviousLiteral(expr):
         first = Word(nums)
         second = matchPreviousLiteral(first)
         matchExpr = first + ":" + second
-    will match C{"1:1"}, but not C{"1:2"}.  Because this matches a
-    previous literal, will also match the leading C{"1:1"} in C{"1:10"}.
-    If this is not desired, use C{matchPreviousExpr}.
-    Do I{not} use with packrat parsing enabled.
+    will match :code:`"1:1"`, but not :code:`"1:2"`.  Because this matches a
+    previous literal, will also match the leading :code:`"1:1"` in :code:`"1:10"`.
+    If this is not desired, use :code:`matchPreviousExpr`.
+    Do *not* use with packrat parsing enabled.
     """
     rep = Forward()
     def copyTokenToRepeater(s,l,t):
@@ -4696,11 +4708,11 @@ def matchPreviousExpr(expr):
         first = Word(nums)
         second = matchPreviousExpr(first)
         matchExpr = first + ":" + second
-    will match C{"1:1"}, but not C{"1:2"}.  Because this matches by
-    expressions, will I{not} match the leading C{"1:1"} in C{"1:10"};
+    will match :code:`"1:1"`, but not :code:`"1:2"`.  Because this matches by
+    expressions, will *not* match the leading :code:`"1:1"` in :code:`"1:10"`;
     the expressions are evaluated first, and then compared, so
-    C{"1"} is compared with C{"10"}.
-    Do I{not} use with packrat parsing enabled.
+    :code:`"1"` is compared with :code:`"10"`.
+    Do *not* use with packrat parsing enabled.
     """
     rep = Forward()
     e2 = expr.copy()
@@ -4728,14 +4740,14 @@ def oneOf( strs, caseless=False, useRegex=True ):
     """
     Helper to quickly define a set of alternative Literals, and makes sure to do
     longest-first testing when there is a conflict, regardless of the input order,
-    but returns a C{:class:`MatchFirst`} for best performance.
+    but returns a :code:`:class:`MatchFirst`` for best performance.
 
     Parameters:
      - strs - a string of space-delimited literals, or a collection of string literals
-     - caseless - (default=C{False}) - treat all literals as caseless
-     - useRegex - (default=C{True}) - as an optimization, will generate a Regex
-          object; otherwise, will generate a C{MatchFirst} object (if C{caseless=True}, or
-          if creating a C{Regex} raises an exception)
+     - caseless - (default=:code:`False`) - treat all literals as caseless
+     - useRegex - (default=:code:`True`) - as an optimization, will generate a Regex
+          object; otherwise, will generate a :code:`MatchFirst` object (if :code:`caseless=True`, or
+          if creating a :code:`Regex` raises an exception)
 
     Example::
         comp_oper = oneOf("< = > <= >= !=")
@@ -4800,10 +4812,10 @@ def oneOf( strs, caseless=False, useRegex=True ):
 def dictOf( key, value ):
     """
     Helper to easily and clearly define a dictionary by specifying the respective patterns
-    for the key and value.  Takes care of defining the C{:class:`Dict`}, C{:class:`ZeroOrMore`}, and C{:class:`Group`} tokens
+    for the key and value.  Takes care of defining the :code:`:class:`Dict``, :code:`:class:`ZeroOrMore``, and :code:`:class:`Group`` tokens
     in the proper order.  The key pattern can include delimiting markers or punctuation,
     as long as they are suppressed, thereby leaving the significant key text.  The value
-    pattern can include named results, so that the C{Dict} results can include named token
+    pattern can include named results, so that the :code:`Dict` results can include named token
     fields.
 
     Example::
@@ -4839,11 +4851,11 @@ def originalTextFor(expr, asString=True):
     revert separate tokens with intervening whitespace back to the original matching
     input text. By default, returns astring containing the original parsed text.
 
-    If the optional C{asString} argument is passed as C{False}, then the return value is a
-    C{:class:`ParseResults`} containing any results names that were originally matched, and a
+    If the optional :code:`asString` argument is passed as :code:`False`, then the return value is a
+    :code:`:class:`ParseResults`` containing any results names that were originally matched, and a
     single token containing the original matched text from the input string.  So if
-    the expression passed to C{:class:`originalTextFor`} contains expressions with defined
-    results names, you must set C{asString} to C{False} if you want to preserve those
+    the expression passed to :code:`:class:`originalTextFor`` contains expressions with defined
+    results names, you must set :code:`asString` to :code:`False` if you want to preserve those
     results name values.
 
     Example::
@@ -4884,8 +4896,8 @@ def locatedExpr(expr):
      - locn_end = location where matched expression ends
      - value = the actual parsed results
 
-    Be careful if the input text contains C{<TAB>} characters, you may want to call
-    C{:class:`ParserElement.parseWithTabs`}
+    Be careful if the input text contains :code:`<TAB>` characters, you may want to call
+    :code:`:class:`ParserElement.parseWithTabs``
 
     Example::
         wd = Word(alphas)
@@ -4925,12 +4937,12 @@ def srange(s):
     character set joined into a single string.
     The values enclosed in the []'s may be:
      - a single character
-     - an escaped character with a leading backslash (such as C{\-} or C{\]})
-     - an escaped hex character with a leading C{'\x'} (C{\x21}, which is a C{'!'} character)
-         (C{\0x##} is also supported for backwards compatibility)
-     - an escaped octal character with a leading C{'\0'} (C{\041}, which is a C{'!'} character)
-     - a range of any of the above, separated by a dash (C{'a-z'}, etc.)
-     - any combination of the above (C{'aeiouy'}, C{'a-zA-Z0-9_$'}, etc.)
+     - an escaped character with a leading backslash (such as :code:`\-` or :code:`\]`)
+     - an escaped hex character with a leading :code:`'\x'` (:code:`\x21`, which is a :code:`'!'` character)
+         (:code:`\0x##` is also supported for backwards compatibility)
+     - an escaped octal character with a leading :code:`'\0'` (:code:`\041`, which is a :code:`'!'` character)
+     - a range of any of the above, separated by a dash (:code:`'a-z'`, etc.)
+     - any combination of the above (:code:`'aeiouy'`, :code:`'a-zA-Z0-9_$'`, etc.)
     """
     _expanded = lambda p: p if not isinstance(p,ParseResults) else ''.join(unichr(c) for c in range(ord(p[0]),ord(p[1])+1))
     try:
@@ -4951,7 +4963,7 @@ def matchOnlyAtCol(n):
 def replaceWith(replStr):
     """
     Helper method for common parse actions that simply return a literal value.  Especially
-    useful when used with C{:class:`transformString<ParserElement.transformString>`()}.
+    useful when used with :code:`:class:`transformString<ParserElement.transformString>`()`.
 
     Example::
         num = Word(nums).setParseAction(lambda toks: int(toks[0]))
@@ -4980,7 +4992,7 @@ def tokenMap(func, *args):
     """
     Helper to define a parse action by mapping a function to all elements of a ParseResults list.If any additional
     args are passed, they are forwarded to the given function as additional arguments after
-    the token, as in C{hex_integer = Word(hexnums).setParseAction(tokenMap(int, 16))}, which will convert the
+    the token, as in :code:`hex_integer = Word(hexnums).setParseAction(tokenMap(int, 16))`, which will convert the
     parsed data to an integer using base 16.
 
     Example (compare the last to example in :class:`ParserElement.transformString`::
@@ -5086,23 +5098,23 @@ def makeXMLTags(tagStr):
 def withAttribute(*args,**attrDict):
     """
     Helper to create a validating parse action to be used with start tags created
-    with C{:class:`makeXMLTags`} or C{:class:`makeHTMLTags`}. Use C{withAttribute} to qualify a starting tag
+    with :code:`:class:`makeXMLTags`` or :code:`:class:`makeHTMLTags``. Use :code:`withAttribute` to qualify a starting tag
     with a required attribute value, to avoid false matches on common tags such as
-    C{<TD>} or C{<DIV>}.
+    :code:`<TD>` or :code:`<DIV>`.
 
-    Call C{withAttribute} with a series of attribute names and values. Specify the list
+    Call :code:`withAttribute` with a series of attribute names and values. Specify the list
     of filter attributes names and values as:
-     - keyword arguments, as in C{(align="right")}, or
-     - as an explicit dict with C{**} operator, when an attribute name is also a Python
-          reserved word, as in C{**{"class":"Customer", "align":"right"}}
+     - keyword arguments, as in :code:`(align="right")`, or
+     - as an explicit dict with :code:`**` operator, when an attribute name is also a Python
+          reserved word, as in :code:`**{"class":"Customer", "align":"right"`}
      - a list of name-value tuples, as in ( ("ns1:class", "Customer"), ("ns2:align","right") )
     For attribute names with a namespace prefix, you must use the second form.  Attribute
     names are matched insensitive to upper/lower case.
 
-    If just testing for C{class} (with or without a namespace), use C{:class:`withClass`}.
+    If just testing for :code:`class` (with or without a namespace), use :code:`:class:`withClass``.
 
     To verify that the attribute exists, but without specifying a value, pass
-    C{withAttribute.ANY_VALUE} as the value.
+    :code:`withAttribute.ANY_VALUE` as the value.
 
     Example::
         html = '''
@@ -5150,8 +5162,8 @@ withAttribute.ANY_VALUE = object()
 
 def withClass(classname, namespace=''):
     """
-    Simplified version of C{:class:`withAttribute`} when matching on a div class - made
-    difficult because C{class} is a reserved word in Python.
+    Simplified version of :code:`:class:`withAttribute`` when matching on a div class - made
+    difficult because :code:`class` is a reserved word in Python.
 
     Example::
         html = '''
@@ -5212,14 +5224,14 @@ def infixNotation( baseExpr, opList, lpar=Suppress('('), rpar=Suppress(')') ):
           be 1, 2, or 3)
        - rightLeftAssoc is the indicator whether the operator is
           right or left associative, using the pyparsing-defined
-          constants C{opAssoc.RIGHT} and C{opAssoc.LEFT}.
+          constants :code:`opAssoc.RIGHT` and :code:`opAssoc.LEFT`.
        - parseAction is the parse action to be associated with
           expressions matching this operator expression (the
           parse action tuple member may be omitted); if the parse action
           is passed a tuple or list of functions, this is equivalent to
-          calling C{setParseAction(*fn)} (:class:`ParserElement.setParseAction`)
-     - lpar - expression for matching left-parentheses (default=C{Suppress('(')})
-     - rpar - expression for matching right-parentheses (default=C{Suppress(')')})
+          calling :code:`setParseAction(*fn)` (:class:`ParserElement.setParseAction`)
+     - lpar - expression for matching left-parentheses (default=:code:`Suppress('(')`)
+     - rpar - expression for matching right-parentheses (default=:code:`Suppress(')')`)
 
     Example::
         # simple example of four-function arithmetic with ints and variable names
@@ -5306,7 +5318,7 @@ def infixNotation( baseExpr, opList, lpar=Suppress('('), rpar=Suppress(')') ):
     return ret
 
 operatorPrecedence = infixNotation
-"""(Deprecated) Former name of C{:class:`infixNotation`}, will be dropped in a future release."""
+"""(Deprecated) Former name of :code:`:class:`infixNotation``, will be dropped in a future release."""
 
 dblQuotedString = Combine(Regex(r'"(?:[^"\n\r\\]|(?:"")|(?:\\(?:[^x]|x[0-9a-fA-F]+)))*')+'"').setName("string enclosed in double quotes")
 sglQuotedString = Combine(Regex(r"'(?:[^'\n\r\\]|(?:'')|(?:\\(?:[^x]|x[0-9a-fA-F]+)))*")+"'").setName("string enclosed in single quotes")
@@ -5320,19 +5332,19 @@ def nestedExpr(opener="(", closer=")", content=None, ignoreExpr=quotedString.cop
     delimiters ("(" and ")" are the default).
 
     Parameters:
-     - opener - opening character for a nested list (default=C{"("}); can also be a pyparsing expression
-     - closer - closing character for a nested list (default=C{")"}); can also be a pyparsing expression
+     - opener - opening character for a nested list (default=:code:`"("`); can also be a pyparsing expression
+     - closer - closing character for a nested list (default=:code:`")"`); can also be a pyparsing expression
      - content - expression for items within the nested lists (default=``None``)
-     - ignoreExpr - expression for ignoring opening and closing delimiters (default=C{quotedString})
+     - ignoreExpr - expression for ignoring opening and closing delimiters (default=:code:`quotedString`)
 
     If an expression is not provided for the content argument, the nested
     expression will capture all whitespace-delimited content between delimiters
     as a list of separate values.
 
-    Use the C{ignoreExpr} argument to define expressions that may contain
+    Use the :code:`ignoreExpr` argument to define expressions that may contain
     opening or closing characters that should not be treated as opening
     or closing characters for nesting, such as quotedString or a comment
-    expression.  Specify multiple expressions using an C{:class:`Or`} or C{:class:`MatchFirst`}.
+    expression.  Specify multiple expressions using an :code:`:class:`Or`` or :code:`:class:`MatchFirst``.
     The default is :class:`quotedString`, but if no expressions are to be ignored,
     then pass ``None`` for this argument.
 
@@ -5417,9 +5429,9 @@ def indentedBlock(blockStatementExpr, indentStack, indent=True):
             should share a common indentStack)
      - indent - boolean indicating whether block must be indented beyond the
             the current level; set to False for block of left-most statements
-            (default=C{True})
+            (default=:code:`True`)
 
-    A valid block must contain at least one C{blockStatement}.
+    A valid block must contain at least one :code:`blockStatement`.
 
     Example::
         data = '''
@@ -5530,23 +5542,23 @@ def replaceHTMLEntity(t):
 
 # it's easy to get these comment structures wrong - they're very common, so may as well make them available
 cStyleComment = Combine(Regex(r"/\*(?:[^*]|\*(?!/))*") + '*/').setName("C style comment")
-"Comment of the form C{/* ... */}"
+"Comment of the form :code:`/* ... */`"
 
 htmlComment = Regex(r"<!--[\s\S]*?-->").setName("HTML comment")
-"Comment of the form C{<!-- ... -->}"
+"Comment of the form :code:`<!-- ... -->`"
 
 restOfLine = Regex(r".*").leaveWhitespace().setName("rest of line")
 dblSlashComment = Regex(r"//(?:\\\n|[^\n])*").setName("// comment")
-"Comment of the form C{// ... (to end of line)}"
+"Comment of the form :code:`// ... (to end of line)`"
 
 cppStyleComment = Combine(Regex(r"/\*(?:[^*]|\*(?!/))*") + '*/'| dblSlashComment).setName("C++ style comment")
-"Comment of either form C{:class:`cStyleComment`} or C{:class:`dblSlashComment`}"
+"Comment of either form :code:`:class:`cStyleComment`` or :code:`:class:`dblSlashComment``"
 
 javaStyleComment = cppStyleComment
-"Same as C{:class:`cppStyleComment`}"
+"Same as :code:`:class:`cppStyleComment``"
 
 pythonStyleComment = Regex(r"#.*").setName("Python style comment")
-"Comment of the form C{# ... (to end of line)}"
+"Comment of the form :code:`# ... (to end of line)`"
 
 _commasepitem = Combine(OneOrMore(Word(printables, excludeChars=',') +
                                   Optional( Word(" \t") +
@@ -5566,13 +5578,13 @@ class pyparsing_common:
      - :class:`UUID<uuid>`
      - :class:`comma-separated list<comma_separated_list>`
     Parse actions:
-     - C{:class:`convertToInteger`}
-     - C{:class:`convertToFloat`}
-     - C{:class:`convertToDate`}
-     - C{:class:`convertToDatetime`}
-     - C{:class:`stripHTMLTags`}
-     - C{:class:`upcaseTokens`}
-     - C{:class:`downcaseTokens`}
+     - :code:`:class:`convertToInteger``
+     - :code:`:class:`convertToFloat``
+     - :code:`:class:`convertToDate``
+     - :code:`:class:`convertToDatetime``
+     - :code:`:class:`stripHTMLTags``
+     - :code:`:class:`upcaseTokens``
+     - :code:`:class:`downcaseTokens``
 
     Example::
         pyparsing_common.number.runTests('''
@@ -5736,7 +5748,7 @@ class pyparsing_common:
     """typical code identifier (leading alpha or '_', followed by 0 or more alphas, nums, or '_')"""
 
     ipv4_address = Regex(r'(25[0-5]|2[0-4][0-9]|1?[0-9]{1,2})(\.(25[0-5]|2[0-4][0-9]|1?[0-9]{1,2})){3}').setName("IPv4 address")
-    "IPv4 address (C{0.0.0.0 - 255.255.255.255})"
+    "IPv4 address (:code:`0.0.0.0 - 255.255.255.255`)"
 
     _ipv6_part = Regex(r'[0-9a-fA-F]{1,4}').setName("hex_integer")
     _full_ipv6_address = (_ipv6_part + (':' + _ipv6_part)*7).setName("full IPv6 address")
@@ -5755,7 +5767,7 @@ class pyparsing_common:
         Helper to create a parse action for converting parsed date string to Python datetime.date
 
         Params -
-         - fmt - format to be passed to datetime.strptime (default=C{"%Y-%m-%d"})
+         - fmt - format to be passed to datetime.strptime (default=:code:`"%Y-%m-%d"`)
 
         Example::
             date_expr = pyparsing_common.iso8601_date.copy()
@@ -5777,7 +5789,7 @@ class pyparsing_common:
         Helper to create a parse action for converting parsed datetime string to Python datetime.datetime
 
         Params -
-         - fmt - format to be passed to datetime.strptime (default=C{"%Y-%m-%dT%H:%M:%S.%f"})
+         - fmt - format to be passed to datetime.strptime (default=:code:`"%Y-%m-%dT%H:%M:%S.%f"`)
 
         Example::
             dt_expr = pyparsing_common.iso8601_datetime.copy()
@@ -5794,13 +5806,13 @@ class pyparsing_common:
         return cvt_fn
 
     iso8601_date = Regex(r'(?P<year>\d{4})(?:-(?P<month>\d\d)(?:-(?P<day>\d\d))?)?').setName("ISO8601 date")
-    "ISO8601 date (C{yyyy-mm-dd})"
+    "ISO8601 date (:code:`yyyy-mm-dd`)"
 
     iso8601_datetime = Regex(r'(?P<year>\d{4})-(?P<month>\d\d)-(?P<day>\d\d)[T ](?P<hour>\d\d):(?P<minute>\d\d)(:(?P<second>\d\d(\.\d*)?)?)?(?P<tz>Z|[+-]\d\d:?\d\d)?').setName("ISO8601 datetime")
-    "ISO8601 datetime (C{yyyy-mm-ddThh:mm:ss.s(Z|+-00:00)}) - trailing seconds, milliseconds, and timezone optional; accepts separating C{'T'} or C{' '}"
+    "ISO8601 datetime (:code:`yyyy-mm-ddThh:mm:ss.s(Z|+-00:00)`) - trailing seconds, milliseconds, and timezone optional; accepts separating :code:`'T'` or :code:`' '`"
 
     uuid = Regex(r'[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}').setName("UUID")
-    "UUID (C{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx})"
+    "UUID (:code:`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)"
 
     _html_stripper = anyOpenTag.suppress() | anyCloseTag.suppress()
     @staticmethod
author	Matěj Cepl <mcepl@cepl.eu>	2018-11-20 09:55:47 +0100
committer	Matěj Cepl <mcepl@cepl.eu>	2018-11-20 10:01:02 +0100
commit	a0b490366a2f218f111eb4c770bab2f0b9cce19c (patch)
tree	45a7a53727dd3c219ad8c1a66336a8db23bf9628
parent	eb43d95fde4c967b0ce24b0faa082aa70e2a720b (diff)
download	pyparsing-git-a0b490366a2f218f111eb4c770bab2f0b9cce19c.tar.gz