Open wilfwilson opened 7 years ago
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.
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: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:[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
andDigraph6
andSparse6
andDisparse6
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: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:
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
, andWriteDigraphs
(although in these cases, the type of detail given is somewhat different than at the start of chapter 9.2).Here are my suggestions:
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
, andWriteDigraphs
.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" />
A user should not be able to create an
XString
from a digraphgr
if the formatX
can not encodegr
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.