Improve the documentation/behaviour of the digraph encoding formats

[wilfwilson]

I don't think it is sufficiently easy to find out which of the four main digraph encoding formats apply to which kinds of digraphs. I'm talking about (di)sparse6 and (di)graph6. For instance, I naively did the following, expecting it to work:

gap> gr := Digraph([[2, 2], []]);
<multidigraph with 2 vertices, 2 edges>
gap> Digraph6String(gr);
"+AG"
gap> DigraphFromDigraph6String(last) = gr;
false

I got a string from Digraph6String(gr), so why didn't recreating the digraph from the string work? I did ?Digraph6String and got the following documentation, which covers all four of the formats:

These  four functions return a highly compressed string fully describing the
digraph digraph.

Graph6  and  Digraph6  are  formats  best  used  on  small, dense graphs, if
applicable. For larger, sparse graphs use Sparse6 and Disparse6 (this latter
also preserves multiple edges).

See WriteDigraphs (9.2-5).

[Technical note: shouldn't these things be attributes, and described as such, since they don't change?]
[Also, haven't we decided at some point that the names Graph6 and Digraph6 and Sparse6 and Disparse6 are written without capital letters, when they appear as words in the middle of a sentence?]

From reading this, I would interpret the phrase "fully describing the digraph" to mean that each format can completely represent any type of digraph; I got a string representing my digraph gr above, so I would expect it to "fully describe" gr. However the phrase "(this latter also preserves multiple edges)", which comes later, seems confusing in this context, as it implies that some of the formats don't support all digraphs.

There is the final line, which is a direction to look at WriteDigraphs, but it is not clear why this is relevant or what one would expect to find there. I wouldn't expect that that would be the place to find a more detailed description of the formats.

Similarly, doing ?DigraphFromDigraph6String gives me the following:

If  str  is  a  string  encoding  a  graph  in  Graph6, Digraph6, Sparse6 or
DiSparse6  format, then the corresponging function returns a digraph. In the
case  of  either  Graph6  or  Sparse6, formats which do not support directed
edges,  this  will  be a digraph such that for every edge, the edge going in
the opposite direction is also present.

Firstly there's the typo "corresponging", and the same comment about capitalising the formats. There's nothing factually wrong about this paragraph (except possibly the use of the word "graph" in the first sentence), but it's not very helpful, and doesn't tell me what I was doing wrong with my code above.

In both of these pieces of documentation, there's a tiny bit of description about some or all of the formats. If you're going to describe the formats, why not give a proper description, or better yet, refer to a proper, complete, central description.

---

This isn't meant to be a rant, but I think these encoding/decoding functions are one of the best bits of the package, and I think that they should be as clear and easy to use as possible.

As far as I can tell, these are the limitations of the formats:

• Graph6: can encode any symmetric digraph without loops or multiple edges
• Sparse6: can encode any symmetric digraph
• Digraph6: can encode any digraph without multiple edges
• Disparse6: can encode any digraph

The formats are described in detail at the beginning of chapter 9.2 "Reading and writing graphs to a file", and the formats are described again in the documentation for DigraphFile, ReadDigraphs, and WriteDigraphs (although in these cases, the type of detail given is somewhat different than at the start of chapter 9.2).

Here are my suggestions:

1. There should be a single central description and definition of these four formats. This should probably reside at the start of chapter 9.2, and incorporate the current detail from there, along with any additional detail which is written about the formats in DigraphFile, ReadDigraphs, and WriteDigraphs.

2. Any documentation which talks about these formats should refer the reader to this part of the documentation. This should probably be accomplished by putting it into a subsection and giving it a label, say, "Encoding formats". Then every time the topic comes up, you could say something along the lines of a detailed description of the formats: graph6, digraph6, sparse6, and disparse6, the kinds of digraphs that each format can encode, and their comparative strengths and weaknesses, is given in <Ref Subsect="Encoding formats" Style="Number" />

3. A user should not be able to create an XString from a digraph gr if the format X can not encode gr faithfully. So in my example above, Digraph6String(gr); would have caused an error. Even better, the error message would suggest a more appropriate encoding format to use.

I hope that this issue will form the start of a discussion about how we improve the documentation of these features.

[james-d-mitchell]

I agree, this is confusing. I'd be very happy for it to be improved along the lines you suggest, in particular points 1 to 3.

I think the actual code itself could also use some improvement, but that's probably another issue.