RE: [Yaml-core] Re: formalism in YAML

[Peter W. <pwo...@qu...>]

> > Normally it is not considered necessary to define elementary
> > theoretical words before using them, but in this case we could
> > perhaps make an exception because of the potential confusion
> > with "that other kind of graph".
>
> That's why I think YAML shouldn't use "graph."  If you have to
> have a whole thing where you explain why you're using a certain
> term and what it means exactly, it's the wrong term in the first
> place.  The meaning of the term should become apparent immediately
> in a brief explanation.  Look at these two  examples:
>
>   To provide interoperability between various languages, platforms,
>   and applications, this specification defines an abstraction called
>   a YAML graph.   A YAML graph models native data structures of=20
>   modern programming languages, including strings, arrays, hashes,
>   and user-defined types.
>
> This means virtually nothing unless you've spent a lot of time in
> the  yaml-core mailing list or you have someone willing to stop
> and spend a couple (of) minutes explaining to you what a graph is.

I think a good way to satisfy both the hardcode CS/math geeks while
informing a broader audience would be to insert a sentence (after
"called a YAML graph") which says (succinctly) what the "nodes" are
*and* what the "edges" are. People who already know what a "graph"
is will now understand the abstraction, and people who forgot what
a graph is will remember (or maybe even learn) when you describe
the nodes and edges.

For example, a "call graph" can be described like so: it has nodes
(representing routines) and directed edges, and an edge from node
A to node B means that routine A calls routine B. You don't need
a Ph.D. to understand that!

>   A YAML "node" models native data structures common to modern
>   programming languages, such as strings, arrays, associative
>   hashes, and user-defined data types.  YAML nodes are grouped into
>   "sets" which may arrange nodes according to a particular
>   specification or arbitrarily.

Here you've explained what a node is, but I still won't understand
what you're talking about until you tell me what it means for a
"set" to "arrange" its nodes. What's missing is a succinct (and
*accurate*, though not necessarily *precise*) description of the
relationship between the nodes.

Cheers, and good luck with the spec!

    Peter Wolfenden