pgf (5jan19)

git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 166 insertions, 173 deletions

diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
index d5848375067..46b1d5db041 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
@@ -15,159 +15,155 @@
 
 
 \section{The Display Layer}
+\label{section-gd-display-layer}
 
 {\noindent {\itshape{by Till Tantau}}}
 
-\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi
+\ifluatex
+\else
+    This section of the manual can only be typeset using Lua\TeX.
+    \expandafter\endinput
+\fi
 
-\label{section-gd-display-layer}
 
 \begin{quote}
-  \itshape You do not need to read this section in order to write new
-  graph drawing algorithms. It is of interest only to those wishing to
-  write programs that wish to ``use'' the graph drawing system in a
-  similar way that \tikzname\ does for laying out graphs that are
-  generated and then passed down from the program to the graph drawing
-  system.
+    \itshape You do not need to read this section in order to write new graph
+    drawing algorithms. It is of interest only to those wishing to write
+    programs that wish to ``use'' the graph drawing system in a similar way
+    that \tikzname\ does for laying out graphs that are generated and then
+    passed down from the program to the graph drawing system.
 \end{quote}
 
 
 \subsection{Introduction: The Interplay of the Different Layers}
 
-The job of the graph drawing system is to run graph drawing algorithms
-on graphs. Since graph drawing is useful in many different contexts,
-not only in the context of \tikzname\ for which the present system was
-originally developed, the graph drawing system was designed in such a
-way that it can be used independently of \tikzname. To achieve this,
-the \emph{display layer} provides an interface via which an arbitrary
-program (\tikzname, a graph editor, a command line interface, etc.)
-``talk'' to the graph drawing system.
-
-To better understand how this works, let us consider the following
-setup: 
+The job of the graph drawing system is to run graph drawing algorithms on
+graphs. Since graph drawing is useful in many different contexts, not only in
+the context of \tikzname\ for which the present system was originally
+developed, the graph drawing system was designed in such a way that it can be
+used independently of \tikzname. To achieve this, the \emph{display layer}
+provides an interface via which an arbitrary program (\tikzname, a graph
+editor, a command line interface, etc.) ``talk'' to the graph drawing system.
 
+To better understand how this works, let us consider the following setup:
+%
 \begin{itemize}
-\item A program would like to communicate with the graph
-  drawing system. It is written in Java and its job is to analyse social
-  networks. This software would like to use graph drawing to produce
-  drawings of some ``social graphs'' arising from its analyses. This
-  software will be called ``the display system'' in the following.
-\item There are two algorithms that the display system would like to apply to
-  the graphs its produces. Let us call these algorithms ``A'' and
-  ``B''. However, the display system would also, ideally, wish to make it
-  possible that its user chooses other algorithms ``C'' that are not
-  necessarily part of its binary.
-\item The display system has internally generated a ``social graph'' that it
-  would now like to draw.
+    \item A program would like to communicate with the graph drawing system. It
+        is written in Java and its job is to analyse social networks. This
+        software would like to use graph drawing to produce drawings of some
+        ``social graphs'' arising from its analyses. This software will be
+        called ``the display system'' in the following.
+    \item There are two algorithms that the display system would like to apply
+        to the graphs its produces. Let us call these algorithms ``A'' and
+        ``B''. However, the display system would also, ideally, wish to make it
+        possible that its user chooses other algorithms ``C'' that are not
+        necessarily part of its binary.
+    \item The display system has internally generated a ``social graph'' that
+        it would now like to draw.
 \end{itemize}
 
-For this setup, the communication between the different layers of the
-graph drawing system is as follows:
-
+For this setup, the communication between the different layers of the graph
+drawing system is as follows:
+%
 \begin{enumerate}
-\item The display system, being written in Java, must embed Lua to use the
-  graph drawing system.
-\item The display system must initialize the graph drawing system. For this,
-  it must use |require| on the file |InterfaceToDisplay|, which, as
-  the name suggests, contains the interface between the display
-  system and the graph drawing system.
-  
-  It must also create a so-called ``binding'' between the
-  graph drawing system and the display layer. See
-  Section~\ref{section-gd-binding-layer} for more information on
-  bindings.
-\item The display system now needs to load the declarations of the
-  algorithms A and B. For this, it just needs to apply |require| to
-  the files in which the algorithms reside. This will cause the
-  |declare| function to be called. This function is declared by
-  |InterfaceToAlgorithms| and allows files to declare that certain
-  algorithms and options are now available.
-
-  Once this is done, the graph drawing system is fully initialized and
-  can be used.
-\item Later on, the display system wishes to lay out a social graph. Note
-  that this is known as ``drawing the graph'' in the graph drawing
-  community, even though this only means the coordinates are computed
-  for the nodes of the graph. The actual ``rendering'' of the graph on
-  the display is the job of the display system (hence the name ``display
-  layer'').
-\item To start the layout process, the display system calls the function
-  |beginGraphDrawingScope| of the class |InterfaceToDisplay|.
-\item Next, for each vertex the function |createVertex| of the
-  interface class must be called and similarly for each edge. These
-  calls will cause an internal model of the graph to be created on the
-  algorithm layer. Options that are attached to nodes and edges are
-  also communicated to the graph drawing system through function calls
-  like |pushOption|.
-\item When the graph is fully specified, the method
-  |runGraphDrawingAlgorithm| must be called, which is once more a
-  method of the interface class. This function will internally discern
-  which algorithms have been chosen (via options) and invoke the code
-  of the appropriate algorithms.
-\item Next, the function |renderGraph| must be called. Its job is to
-  ``communicate back'' which coordinates have been computed. It will
-  use the binding for this communication, see
-  Section~\ref{section-gd-binding-layer}.
-\item Finally, by calling |endGraphDrawingScope|, the resources needed
-  for the layout process for the social graph are freed once more.
+    \item The display system, being written in Java, must embed Lua to use the
+        graph drawing system.
+    \item The display system must initialize the graph drawing system. For
+        this, it must use |require| on the file |InterfaceToDisplay|, which, as
+        the name suggests, contains the interface between the display system
+        and the graph drawing system.
+
+        It must also create a so-called ``binding'' between the graph drawing
+        system and the display layer. See
+        Section~\ref{section-gd-binding-layer} for more information on
+        bindings.
+    \item The display system now needs to load the declarations of the
+        algorithms A and B. For this, it just needs to apply |require| to the
+        files in which the algorithms reside. This will cause the |declare|
+        function to be called. This function is declared by
+        |InterfaceToAlgorithms| and allows files to declare that certain
+        algorithms and options are now available.
+
+        Once this is done, the graph drawing system is fully initialized and
+        can be used.
+    \item Later on, the display system wishes to lay out a social graph. Note
+        that this is known as ``drawing the graph'' in the graph drawing
+        community, even though this only means the coordinates are computed for
+        the nodes of the graph. The actual ``rendering'' of the graph on the
+        display is the job of the display system (hence the name ``display
+        layer'').
+    \item To start the layout process, the display system calls the function
+        |beginGraphDrawingScope| of the class |InterfaceToDisplay|.
+    \item Next, for each vertex the function |createVertex| of the interface
+        class must be called and similarly for each edge. These calls will
+        cause an internal model of the graph to be created on the algorithm
+        layer. Options that are attached to nodes and edges are also
+        communicated to the graph drawing system through function calls like
+        |pushOption|.
+    \item When the graph is fully specified, the method
+        |runGraphDrawingAlgorithm| must be called, which is once more a method
+        of the interface class. This function will internally discern which
+        algorithms have been chosen (via options) and invoke the code of the
+        appropriate algorithms.
+    \item Next, the function |renderGraph| must be called. Its job is to
+        ``communicate back'' which coordinates have been computed. It will use
+        the binding for this communication, see
+        Section~\ref{section-gd-binding-layer}.
+    \item Finally, by calling |endGraphDrawingScope|, the resources needed for
+        the layout process for the social graph are freed once more.
 \end{enumerate}
 
 A few points may be noteworthy:
+%
 \begin{itemize}
-\item The whole communication between the display system and the graph
-  drawing system goes through the interface class via function
-  calls. This makes it easy to communicate with display system whose
-  internal model of graphs is quite different from the one used in Lua
-  (as is certainly the case for \TeX, but also the ``social graph''
-  mentioned above need not even exist as a separate entity inside the
-  display system).
-  
-  \emph{The display system should only rely on the interface
-    class. All communication has to go through this class, the
-    display system may not access the internals of the internally
-    constructed graphs directly.}
-\item New algorithms can be loaded at runtime, as long as the
-  |require| method is supported.
-\item The display system can also use the interface class to query which
-  algorithms and which options are available in principle (and display
-  this information to the user). The display system can even get access the
-  documentation of the options at runtime since the documentation is
-  stored in fields of the declared options.
+    \item The whole communication between the display system and the graph
+        drawing system goes through the interface class via function calls.
+        This makes it easy to communicate with display system whose internal
+        model of graphs is quite different from the one used in Lua (as is
+        certainly the case for \TeX, but also the ``social graph'' mentioned
+        above need not even exist as a separate entity inside the display
+        system).
+
+        \emph{The display system should only rely on the interface class. All
+        communication has to go through this class, the display system may not
+        access the internals of the internally constructed graphs directly.}
+    \item New algorithms can be loaded at runtime, as long as the |require|
+        method is supported.
+    \item The display system can also use the interface class to query which
+        algorithms and which options are available in principle (and display
+        this information to the user). The display system can even get access
+        the documentation of the options at runtime since the documentation is
+        stored in fields of the declared options.
 \end{itemize}
 
-
 In the following, we first present a simple display system other than
-\tikzname. The remainder of the section then encompasses a
-documentation of the different functions of the class
-|InterfaceToDisplay|. 
-
+\tikzname. The remainder of the section then encompasses a documentation of the
+different functions of the class |InterfaceToDisplay|.
 
 
 \subsection{An Example Display System}
 
-In the following, we present the code of a very simple display system
-written in Lua (another such display system is \tikzname\ itself, but
-the minimal system will allow us to focus on what is really
-needed). You will also find it in |pgf.gd.examples.ASCIIDisplayer|. 
-
-The job of this display system is to parse a string that encodes a graph
-and to call the appropriate functions of |InterfaceToDisplay| to lay
-out the graph. The actual calls for rendering the graph are part of
-the binding, which is documented in
-Section~\ref{section-gd-binding-layer-example}.
-
-The syntax of the to-be-laid-out graph is a reduced version of
-\tikzname's |graph| syntax: The string must start with
-|graph[|\meta{algorithm's name}|]{| and end with |}|. Between the
-braces, all lines must either be of the form \meta{node name}|;| or
-\meta{name 1}|->|\meta{name 2}|;| with optional spaces around the node
-names.
-
-Let us now have a look at what we must do to use the graph drawing
-system. First, we load some libraries and initialize the binding (see
-Section~\ref{section-gd-binding-layer-example} for details on the
-binding; we can ignore it for now).
-
+In the following, we present the code of a very simple display system written
+in Lua (another such display system is \tikzname\ itself, but the minimal
+system will allow us to focus on what is really needed). You will also find it
+in |pgf.gd.examples.ASCIIDisplayer|.
+
+The job of this display system is to parse a string that encodes a graph and to
+call the appropriate functions of |InterfaceToDisplay| to lay out the graph.
+The actual calls for rendering the graph are part of the binding, which is
+documented in Section~\ref{section-gd-binding-layer-example}.
+
+The syntax of the to-be-laid-out graph is a reduced version of \tikzname's
+|graph| syntax: The string must start with |graph[|\meta{algorithm's name}|]{|
+and end with |}|. Between the braces, all lines must either be of the form
+\meta{node name}|;| or \meta{name 1}|->|\meta{name 2}|;| with optional spaces
+around the node names.
+
+Let us now have a look at what we must do to use the graph drawing system.
+First, we load some libraries and initialize the binding (see
+Section~\ref{section-gd-binding-layer-example} for details on the binding; we
+can ignore it for now).
+%
 \begin{codeexample}[code only]
 local InterfaceToDisplay = require "pgf.gd.interface.InterfaceToDisplay"
 InterfaceToDisplay.bind(require "pgf.gd.examples.BindingToASCII")
@@ -178,13 +174,14 @@ require "pgf.gd.layered.library"
 require "pgf.gd.force.library"
 \end{codeexample}
 
-Now comes some preparation code that starts a graph drawing scope and
-sets up the algorithm to the string provided between the square
-brackets:
+Now comes some preparation code that starts a graph drawing scope and sets up
+the algorithm to the string provided between the square \todosp{should
+\texttt{.pushPhase} be \texttt{.pushOption}? (bug \#396)} brackets:
 
+%
 \begin{codeexample}[code only]
 local algorithm = io.read():match("%s*graph%s*%[(.-)%]")
-  
+
 InterfaceToDisplay.pushPhase(algorithm, "main", 1)
 InterfaceToDisplay.pushOption("level distance", 6, 2)
 InterfaceToDisplay.pushOption("sibling distance", 8, 3)
@@ -192,13 +189,11 @@ InterfaceToDisplay.beginGraphDrawingScope(3)
 InterfaceToDisplay.pushLayout(4)
 \end{codeexample}
 
-The numbers |1| to |4| are the positions on the options stack at which
-the options should be placed. See the description of |pushOption| for
-more details.
-
-We are now ready to create the vertices and edges via a very simple
-parser:
+The numbers |1| to |4| are the positions on the options stack at which the
+options should be placed. See the description of |pushOption| for more details.
 
+We are now ready to create the vertices and edges via a very simple parser:
+%
 \begin{codeexample}[code only]
 for line in io.lines() do
   if line:match("}") then
@@ -213,24 +208,23 @@ for line in io.lines() do
 end
 \end{codeexample}
 
-The graph is now completely constructed inside the graph drawing
-system. We can now invoke the algorithms:
-
+The graph is now completely constructed inside the graph drawing system. We can
+now invoke the algorithms:
+%
 \begin{codeexample}[code only]
 InterfaceToDisplay.runGraphDrawingAlgorithm()
 InterfaceToDisplay.renderGraph()
 InterfaceToDisplay.endGraphDrawingScope()
 \end{codeexample}
 
-We can now run the resulting file using the Lua interpreter. If we
-provide the input shown on the left, we get the output shown on the
-right:
+We can now run the resulting file using the Lua interpreter. If we provide the
+input shown on the left, we get the output shown on the right:
 
 \bigskip
 \noindent
 \begin{minipage}[t]{.5\textwidth}
-\emph{Input given to ASCIIDisplayer:}  
-  
+\emph{Input given to ASCIIDisplayer:}
+
 \begin{verbatim}
 graph [layered layout] {
   Alice;
@@ -250,38 +244,38 @@ graph [layered layout] {
   George -> Eve;
   George -> Fritz;
   Alice -> George;
-}  
+}
 \end{verbatim}
 \end{minipage}%
 \begin{minipage}[t]{.49\textwidth}
-\emph{Output produced by ASCIIDisplayer:}  
-  
+\emph{Output produced by ASCIIDisplayer:}
+
 \begin{verbatim}
-                   Alice                            
-                 .......                            
-               .. .  .  .                           
-            ...  .   .   .                          
-         ...   ..    .    ..                        
-       ..     .      .      .                       
-  Charly    Bob      .       .                      
-      ..     .       .       .                      
-        .    .       .       .                      
-         .   .       .       .                      
-          .. .       .       .                      
-            ..       .       .                      
-           Dave   George     .                      
-              ..     . ...   .                      
-                .    .    .. .                      
-                 .   .      ...                     
-                  .. .       . ...                  
-                    ..       .    ..                
-                    Eve      .      ..              
-                      ..     .     ..               
-                        .    .    .                 
-                         .   .   .                  
-                          .. . ..                   
-                            ...                     
-                           Fritz                    
+                   Alice
+                 .......
+               .. .  .  .
+            ...  .   .   .
+         ...   ..    .    ..
+       ..     .      .      .
+  Charly    Bob      .       .
+      ..     .       .       .
+        .    .       .       .
+         .   .       .       .
+          .. .       .       .
+            ..       .       .
+           Dave   George     .
+              ..     . ...   .
+                .    .    .. .
+                 .   .      ...
+                  .. .       . ...
+                    ..       .    ..
+                    Eve      .      ..
+                      ..     .     ..
+                        .    .    .
+                         .   .   .
+                          .. . ..
+                            ...
+                           Fritz
 \end{verbatim}
 \end{minipage}
 
@@ -289,4 +283,3 @@ graph [layered layout] {
 \subsection{The Interface to Display Systems}
 
 \includeluadocumentationof{pgf.gd.interface.InterfaceToDisplay}
-