From 21cf74df51cea318625cf9f897fa567be264c210 Mon Sep 17 00:00:00 2001 From: erg Date: Sat, 12 Dec 2009 22:02:03 +0000 Subject: [PATCH] Clarify certain aspects about the dot language; explicitly define cluster subgraphs; remove references to mif output. --- doc/info/attrs.html | 3 --- doc/info/lang.html | 44 +++++++++++++++++++++++++++++++++++++++++--- doc/infosrc/lang.2 | 44 +++++++++++++++++++++++++++++++++++++++++--- doc/infosrc/types | 3 --- 4 files changed, 82 insertions(+), 12 deletions(-) diff --git a/doc/info/attrs.html b/doc/info/attrs.html index c3d869028..8e233eb71 100644 --- a/doc/info/attrs.html +++ b/doc/info/attrs.html @@ -1795,9 +1795,6 @@ the given types. Turquoise"#40e0d0""0.482 0.714 0.878""turquoise" Sienna"#a0522d""0.051 0.718 0.627""sienna" -

- Note that some output formats, e.g., mif, - only support a limited number of specific colors.

The string value transparent can be used to indicate no color. This is only available in the output formats diff --git a/doc/info/lang.html b/doc/info/lang.html index ae58eb3ae..efc08477f 100644 --- a/doc/info/lang.html +++ b/doc/info/lang.html @@ -119,12 +119,16 @@ An ID is one of the following:

  • Any string of alphabetic ([a-zA-Z\200-\377]) characters, underscores ('_') or digits ([0-9]), not beginning with a digit; -
  • a number [-]?(.[0-9]+ | [0-9]+(.[0-9]*)? ); +
  • a numeral [-]?(.[0-9]+ | [0-9]+(.[0-9]*)? );
  • any double-quoted string ("...") possibly containing escaped quotes (\")1;
  • an HTML string (<...>).
    • -Note that in HTML strings, angle +An ID is just a string; the lack of quote characters in the first two +forms is just for simplicity. There is no semantic difference between +abc_2 and "abc_2", or between 2.34 and +"2.34". Obviously, to use a keyword as an ID, it must be quoted. +Note that, in HTML strings, angle brackets must occur in matched pairs, and unescaped newlines are allowed. In addition, the content must be legal XML, so that the special XML escape sequences for ", &, <, and > may be necessary @@ -155,7 +159,35 @@ backslash immediately preceding a newline character. In addition, double-quoted strings can be concatenated using a '+' operator. As HTML strings can contain newline characters, they do not support the concatenation operator. -

    Semantic Notes

    +

    Subgraphs and Clusters

    +Subgraphs play three roles in Graphviz. First, a subgraph can be used to +represent graph structure, indicating that certain nodes and edges should +be grouped together. This is the usual role for subgraphs +and typically specifies semantic information about the graph components. +

    +In the second role, a subgraph can provide a context for setting attributes. +For example, a subgraph could specify that blue +is the default color for all nodes defined in it. +In the context of +graph drawing, a more interesting example is: +

    +subgraph { 
+rank = same; A; B; C; 
+} 
+
    +This (anonymous) subgraph specifies that the nodes A, B and C +should all be placed on the same rank if drawn using dot. +

    +The third role for subgraphs directly involves how the graph +will be laid out by certain layout engines. If the name of +the subgraph begins with cluster, Graphviz notes the subgraph as +a special cluster subgraph. If supported, the layout engine will +do the layout so that the nodes belonging to the cluster are drawn together, +with the entire drawing of the cluster contained within a bounding rectangle. +Note that, for good and bad, cluster subgraphs are not part of the +DOT language, but solely a syntactic convention adhered to by +certain of the layout engines. +

    Lexical and Semantic Notes

    If a default attribute is defined using a node, edge, or graph statement, or by an attribute assignment not attached to a node or edge, any object of the @@ -179,6 +211,12 @@ have been defined. If an edge belongs to a cluster, its endpoints belong to that cluster. Thus, where you put an edge can effect a layout, as clusters are sometimes laid out recursively. +

    +There are certain restrictions on subgraphs and clusters. First, at +present, the names of a graph and it subgraphs share the same namespace. +Thus, each subgraph must have a unique name. Second, although nodes +can belong to any number of subgraphs, it is assumed clusters form +a strict hierarchy when viewed as subsets of nodes and edges.

    Character encodings

    The DOT language assumes at least the ascii character set. Quoted strings, both ordinary and HTML-like, may contain non-ascii characters. diff --git a/doc/infosrc/lang.2 b/doc/infosrc/lang.2 index cb6e43767..86dbacc19 100644 --- a/doc/infosrc/lang.2 +++ b/doc/infosrc/lang.2 @@ -10,12 +10,16 @@ An ID is one of the following:
  • Any string of alphabetic ([a-zA-Z\200-\377]) characters, underscores ('_') or digits ([0-9]), not beginning with a digit; -
  • a number [-]?(.[0-9]+ | [0-9]+(.[0-9]*)? ); +
  • a numeral [-]?(.[0-9]+ | [0-9]+(.[0-9]*)? );
  • any double-quoted string ("...") possibly containing escaped quotes (\")1;
  • an HTML string (<...>).
    • -Note that in HTML strings, angle +An ID is just a string; the lack of quote characters in the first two +forms is just for simplicity. There is no semantic difference between +abc_2 and "abc_2", or between 2.34 and +"2.34". Obviously, to use a keyword as an ID, it must be quoted. +Note that, in HTML strings, angle brackets must occur in matched pairs, and unescaped newlines are allowed. In addition, the content must be legal XML, so that the special XML escape sequences for ", &, <, and > may be necessary @@ -46,7 +50,35 @@ backslash immediately preceding a newline character. In addition, double-quoted strings can be concatenated using a '+' operator. As HTML strings can contain newline characters, they do not support the concatenation operator. -

    Semantic Notes

    +

    Subgraphs and Clusters

    +Subgraphs play three roles in Graphviz. First, a subgraph can be used to +represent graph structure, indicating that certain nodes and edges should +be grouped together. This is the usual role for subgraphs +and typically specifies semantic information about the graph components. +

    +In the second role, a subgraph can provide a context for setting attributes. +For example, a subgraph could specify that blue +is the default color for all nodes defined in it. +In the context of +graph drawing, a more interesting example is: +

    +subgraph { 
+rank = same; A; B; C; 
+} 
+
    +This (anonymous) subgraph specifies that the nodes A, B and C +should all be placed on the same rank if drawn using dot. +

    +The third role for subgraphs directly involves how the graph +will be laid out by certain layout engines. If the name of +the subgraph begins with cluster, Graphviz notes the subgraph as +a special cluster subgraph. If supported, the layout engine will +do the layout so that the nodes belonging to the cluster are drawn together, +with the entire drawing of the cluster contained within a bounding rectangle. +Note that, for good and bad, cluster subgraphs are not part of the +DOT language, but solely a syntactic convention adhered to by +certain of the layout engines. +

    Lexical and Semantic Notes

    If a default attribute is defined using a node, edge, or graph statement, or by an attribute assignment not attached to a node or edge, any object of the @@ -70,6 +102,12 @@ have been defined. If an edge belongs to a cluster, its endpoints belong to that cluster. Thus, where you put an edge can effect a layout, as clusters are sometimes laid out recursively. +

    +There are certain restrictions on subgraphs and clusters. First, at +present, the names of a graph and it subgraphs share the same namespace. +Thus, each subgraph must have a unique name. Second, although nodes +can belong to any number of subgraphs, it is assumed clusters form +a strict hierarchy when viewed as subsets of nodes and edges.

    Character encodings

    The DOT language assumes at least the ascii character set. Quoted strings, both ordinary and HTML-like, may contain non-ascii characters. diff --git a/doc/infosrc/types b/doc/infosrc/types index 11fdfae90..53dd211e8 100644 --- a/doc/infosrc/types +++ b/doc/infosrc/types @@ -85,9 +85,6 @@ Examples:
    Turquoise"#40e0d0""0.482 0.714 0.878""turquoise" Sienna"#a0522d""0.051 0.718 0.627""sienna" -

    - Note that some output formats, e.g., mif, - only support a limited number of specific colors.

    The string value transparent can be used to indicate no color. This is only available in the output formats -- 2.40.0