Skip to content

Remove more duplicated chunks of text from the manual with AutoDoc entities #861

@wilfwilson

Description

@wilfwilson

In doc/io.xml, the documentation for the functions DigraphFile, ReadDigraphs, and WriteDigraphs all contain the following chunk of text, or something almost identical:

    The currently supported file formats, and associated filename extensions,
    are:
    <List>
      <Mark>graph6 (.g6)</Mark>
      <Item>
	A standard and widely-used format for undirected graphs, with no support
	for loops or multiple edges.  Only symmetric graphs are allowed -- each
	edge is combined with its converse edge to produce a single undirected
	edge.  This format is best used for "dense" graphs -- those with many
	edges per vertex.
      </Item>
      <Mark>sparse6 (.s6)</Mark>
      <Item>
	Unlike graph6, sparse6 has support for loops and multiple edges.
	However, its use is still limited to symmetric graphs.  This format is
	better-suited to "sparse" graphs -- those with few edges per vertex.
      </Item>
      <Mark>digraph6 (.d6)</Mark>
      <Item>
	This format is based on graph6, but stores direction information -
	therefore is not limited to symmetric graphs.  Loops are allowed, but
	multiple edges are not.  Best compression with "dense" graphs.
      </Item>
      <Mark>disparse6 (.ds6)</Mark>
      <Item>
	Any type of digraph can be encoded in disparse6: directions, loops, and
	multiple edges are all allowed.  Similar to sparse6, this has the best
	compression rate with "sparse" graphs.
      </Item>
      <Mark>plain text (.txt)</Mark>
      <Item>
	This is a human-readable format which stores graphs in the form
        <C>0 7  0 8  1 7  2 8  3 8  4 8  5 8  6 8</C> i.e. pairs of vertices
        describing edges in a graph. More specifically, the vertices making up
        one edge must be separated by a single space, and pairs of vertices must
        be separated by two spaces. <P/>

        See <Ref Oper="ReadPlainTextDigraph"/> for a more flexible way to store
        digraphs in a plain text file. <P/>
      </Item>

      <Mark>pickled (<F>.p</F> or <F>.pickle</F>)</Mark>
      <Item>
        Digraphs are pickled using the &IO; package. This is particularly good
        when the <Ref Attr="DigraphGroup"/> is non-trivial.
      </Item>
      <Mark>dreadnaut (.dre)</Mark>
      <Item>
        A graph format designed for directed and undirected graphs.
        The format supports loops but multiple edges are ignored.  The format consists of an
        initial section that defines the graph's structural properties, such as the number of
        vertices, the starting value for vertices, and whether the graph is directed. This is followed
        by a list of edges. For more information and examples of the format see
        <URL Text="nauty and Traces User's Guide">http://pallini.di.uniroma1.it/Guide.html</URL>.<P/>
      </Item>
      <Mark> DIMACS (.dimacs) </Mark>
      <Item>
        A graph format that can be used for symmetric digraphs. For a more detailed description, see <Ref Oper="WriteDIMACSDigraph"/>
      </Item>
    </List>

We should probably only have this source once in the repository, to make it easier to maintain, and then it can be reproduced in each location (as long as the bits of text are, indeed, meant to be the same).

Similarly, in doc/isomorph.xml, there is a lot of repetition of the form:

obtained from &BLISS; by Tommi Junttila
and Petteri Kaski. If &NAUTYTRACESINTERFACE; is available, then &NAUTY; by
Brendan Mckay and Adolfo Piperno can be used instead

This duplication probably can/should be reduced, too.

Metadata

Metadata

Assignees

No one assigned

    Labels

    difficulty: 1A label for feature requests of moderate difficultydocIssues, bugs, pull requests relating to the documentationhelp wantedA label for issues or PRs where help is wanted

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions