anchor.diff:  limitations under the License.
   ////
   [[intro]]
  -= Introduction to Graph Computing
  += Introduction
  +
  +Welcome to the Reference Documentation for Apache TinkerPop™ - the backbone for all details on how to work with
  +TinkerPop and the Gremlin graph traversal language. This documentation is not meant to be a "book", but a source
  +from which to spawn more detailed accounts of specific topics and a target to which all other resources point.
  +The Reference Documentation makes some general assumptions about the reader:
  +
  +1. They have a sense of what a graph is - not sure? see link:http://kelvinlawrence.net/book/Gremlin-Graph-Guide.html#whygraph[Practical Gremlin - Why Graph?]
  +1. They know what it means for a graph system to be TinkerPop-enabled - not sure? see link:link:http://tinkerpop.apache.org/providers.html[TinkerPop-enabled Providers]
  +1. They know what the role of Gremlin is - not sure? see link:link:http://tinkerpop.apache.org/gremlin.html[Introduction to Gremlin]
  +
  +Given those assumptions, it's possible to dive more quickly into the details without spending a lot of time repeating
  +what is written elsewhere.
  +
  +It is fairly certain that readers of the Reference Documentation are coming from the most diverse software development
  +backgrounds that TinkerPop has ever engaged in over the decade or so of its existence. While TinkerPop holds some roots
  +in Java, and thus, languages bound to the Java Virtual Machine (JVM), it long ago branched out into other languages
  +such as Python, Javascript, .NET, and others. To compound upon that diversity, it is also seeing extensive support
  +from different graph systems which have chosen TinkerPop as their standard method for allowing users to interface
  +with their graph. Moreover, the graph systems themselves are not only separated by OLTP and OLAP style workloads, but
  +also by their implementation patterns, which range everywhere from being an embedded graph system to a cloud-only
  +graph. One might even find diversity parallel to Gremlin if considering other graph query languages.
  +
  +Despite all this diversity and disparity, Gremlin remains the unifying interface for all these different elements of
  +the graph community. As a user, choosing a TinkerPop-enabled graph and using Gremlin in the correct way when building
  +applications shields them from change and disparity in the space. As a graph provider, choosing to become
  +TinkerPop-enabled not only expands the reach their system can get into different development ecosystems, but also
  +provides access to other query languages through bytecode compilation as seen in <<sparql-gremlin,sparql-gremlin>>.
  +
  +Irrespective of the programming language being used, graph system chosen or other development background that might
  +be driving a user to this documentation, the critical point to remember is that "Gremlin is Gremlin is Gremlin". The
  +same Gremlin that is written for an OLTP query over an in-memory TinkerGraph is the same Gremlin that is written to
  +execute over a multi-billion edge graph using OLAP through Spark. That same Gremlin for either of those cases is
  +written in the same way whether using Java or Python or Javascript. The Gremlin is always fundamentally the same
  +aside from syntactical differences that might be language specific - e.g. the construction of a lambda in Groovy is
  +different than the construction of a lambda in Python or a reserved word in Javascript forces a Gremlin step to have
  +slightly different naming than Java.
  +
  +While learning the Gremlin language and its patterns is largely agnostic to all the diversity in the space, it is not
  +really possible to ignore the impact of the diversity from an application development perspective and the Reference
  +Documentation makes an effort to try to point out where differences and inconsistencies might lie without diving too
  +deeply into specific graph provider implementations. Users are strongly encouraged to consult the documentation of
  +their chosen graph provider to understand all of the capabilities and limitations that may restrict or inhibit usage
  +of certain aspects of TinkerPop APIs which are defined here in this Reference Documentation.
  +
  +The following introductory sections and separately referenced content will be of varying interest to different readers.
  +The summaries below will hopefully be helpful in directing individuals to the appropriate place to start their
  +learning process.
  +
  +* <<graph-computing,Graph Computing>> is an introduction to what "graph computing" means to TinkerPop and describes
  +many of the provider and user-facing TinkerPop APIs and concepts that enable Gremlin.
  +* <<connecting-gremlin,Connecting Gremlin>> provides descriptions for the different modes by which users will connect to graphs
  +depending on their environment.
  +* <<basic-gremlin, Basic Gremlin>> describes how to use a connection to start writing Gremlin.
  +* <<staying-agnostic, Staying Agnostic>> explains the extent to which working with Gremlin protects agnosticism.
  +
  +New users should not ignore TinkerPop's link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/getting-started/[Getting Started]
  +tutorial or link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/[The Gremlin Console] tutorial.
  +Both contain a large number of basic information and tips that can help readers avoid some basic pitfalls early on.
  +Both also focus on Gremlin usage in the Gremlin Console, which tends to be a critical tool for Gremlin developers of
  +any development background.
  +
  +More advanced and experience users will appreciate link:http://tinkerpop.apache.org/docs/x.y.z/recipes/[Gremlin Recipes]
  +which provide examples of common Gremlin traversal patterns.
  +
  +Finally, all Gremlin developers should become familiar with
  +link:http://kelvinlawrence.net/book/Gremlin-Graph-Guide.html["Practical Gremlin"] by Kelvin Lawrence. This book is
  +freely available and published online. It contains great examples and details that are applicable to anyone building
  +applications with Gremlin.
  +
  +[[graph-computing]]
  +== Graph Computing
   
   image::graph-computing.png[width=350]
  -
  -[source,xml]
  -<dependency>
  -  <groupId>org.apache.tinkerpop</groupId>
  -  <artifactId>gremlin-core</artifactId>
  -  <version>x.y.z</version>
  -</dependency>
   
   A link:http://en.wikipedia.org/wiki/Graph_(data_structure)[graph] is a data structure composed of vertices (nodes,
   dots) and edges (arcs, lines). When modeling a graph in a computer and applying it to modern data sets and practices,
   the generic mathematically-oriented, binary graph is extended to support both labels and key/value properties. This
   structure is known as a property graph. More formally, it is a directed, binary, attributed multi-graph. An example
  -property graph is diagrammed below. This graph example will be used extensively throughout the documentation and is
  -called "TinkerPop Modern" as it is a modern variation of the original demo graph distributed with TinkerPop0 back
  -in 2009 (i.e. the good ol' days -- it was the best of times and it was the worst of times).
  -
  -TIP: The TinkerPop graph is available with <<tinkergraph-gremlin,TinkerGraph>> via `TinkerFactory.createModern()`.
  -TinkerGraph is the reference implementation of TinkerPop and is used in nearly all the examples in this documentation.
  -
  -TIP: All of the toy graphs available in TinkerPop are described in
  -link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/#toy-graphs[The Gremlin Console] tutorial.
  +property graph is diagrammed below.
   
   [[tinkerpop-modern]]
   .TinkerPop Modern
   image::tinkerpop-modern.png[width=500]
   
  -TinkerPop 3.x is the third incarnation of the Apache TinkerPop™ graph computing framework. Similar to computing in
  -general, graph computing makes a distinction between *structure* (graph) and *process* (traversal). The structure of
  -the graph is the data model defined by a vertex/edge/property link:http://en.wikipedia.org/wiki/Network_topology[topology].
  -The process of the graph is the means by which the structure is analyzed. The typical form of graph processing is
  -called a link:http://en.wikipedia.org/wiki/Graph_traversal[traversal].
  +TIP: Get to know this graph structure as it is used extensively throughout the documentation and in wider circles as
  +well. It is referred to as "TinkerPop Modern" as it is a modern variation of the original demo graph distributed with
  +TinkerPop0 back in 2009 (i.e. the good ol' days -- it was the best of times and it was the worst of times).
  +
  +TIP: All of the toy graphs available in TinkerPop are described in
  +link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/#toy-graphs[The Gremlin Console] tutorial.
  +
  +Similar to computing in general, graph computing makes a distinction between *structure* (graph) and *process*
  +(traversal). The structure of the graph is the data model defined by a vertex/edge/property
  +link:http://en.wikipedia.org/wiki/Network_topology[topology]. The process of the graph is the means by which the
  +structure is analyzed. The typical form of graph processing is called a
  +link:http://en.wikipedia.org/wiki/Graph_traversal[traversal].
  +
  +image:tinkerpop-enabled.png[width=135,float=left] TinkerPop's role in graph computing is to provide the appropriate
  +interfaces for link:http://tinkerpop.apache.org/providers.html[graph providers] and users to interact with graphs over
  +their structure and process.  When a graph system implements the TinkerPop structure and process
  +link:http://en.wikipedia.org/wiki/Application_programming_interface[APIs], their technology is considered
  +_TinkerPop-enabled_ and becomes nearly indistinguishable from any other TinkerPop-enabled graph system save for their
  +respective time and space complexity. The purpose of this documentation is to describe the structure/process dichotomy
  +at length and in doing so, explain how to leverage TinkerPop for the sole purpose of graph system-agnostic graph
  +computing.
  +
  +IMPORTANT: TinkerPop is licensed under the popular link:http://www.apache.org/licenses/LICENSE-2.0.html[Apache2]
  +free software license. However, note that the underlying graph engine used with TinkerPop may have a different
  +license. Thus, be sure to respect the license caveats of the graph system product.
   
   Generally speaking, the structure or "graph" API is meant for link:http://tinkerpop.apache.org/providers.html[graph providers]
   who are implementing the TinkerPop interfaces and the process or "traversal" API (i.e. Gremlin) is meant for end-users
  
positive.code: <2> Get the vertices that are outgoing adjacent to the marko-vertex via knows-edges.
  <3> Get the names of the marko-vertex's friends.
  
  === The Traverser
  
  When a traversal is executed, the source of the traversal is on the left of the expression (e.g. vertex 1), the steps
  are the middle of the traversal (e.g. `out('knows')` and `values('name')`), and the results are "traversal.next()'d"
  
negative.code:  ** `VertexProgram`: code executed at all vertices in a logically parallel manner with intercommunication via message passing.
   ** `MapReduce`: a computation that analyzes all vertices in the graph in parallel and yields a single reduced result.
  
  NOTE: The TinkerPop API rides a fine line between providing concise "query language" method names and respecting
  Java method naming standards. The general convention used throughout TinkerPop is that if a method is "user exposed,"
  then a concise name is provided (e.g. `out()`, `path()`, `repeat()`). If the method is primarily for graph systems
  providers, then the standard Java naming convention is followed (e.g. `getNextStep()`, `getSteps()`,
  `getElementComputeKeys()`).
  
  === The Graph Structure
  
  image:gremlin-standing.png[width=125,float=left] A graph's structure is the topology formed by the explicit references
  between its vertices, edges, and properties. A vertex has incident edges. A vertex is adjacent to another vertex if
  