diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml index e9c0b91d9..3ba7c2b88 100644 --- a/.github/workflows/ubuntu.yml +++ b/.github/workflows/ubuntu.yml @@ -36,10 +36,10 @@ jobs: include: - only-needed: true pkgs-to-clone: digraphs/graphviz - pkgs-to-build: io orb datastructures + pkgs-to-build: io orb datastructures autodoc - only-needed: false pkgs-to-clone: NautyTracesInterface digraphs/graphviz - pkgs-to-build: io orb datastructures grape NautyTracesInterface + pkgs-to-build: io orb datastructures grape NautyTracesInterface autodoc steps: - uses: actions/checkout@v4 diff --git a/.gitignore b/.gitignore index 654b88ca8..80add9427 100644 --- a/.gitignore +++ b/.gitignore @@ -58,3 +58,4 @@ missing src/pkgconfig.h.in tags tst/out/ +_*.xml diff --git a/PackageInfo.g b/PackageInfo.g index b93125a12..bc51de9cb 100644 --- a/PackageInfo.g +++ b/PackageInfo.g @@ -8,17 +8,23 @@ ############################################################################# ## -## <#GAPDoc Label="PKGVERSIONDATA"> -## -## -## -## -## -## -## -## -## -## <#/GAPDoc> +BindGlobal("_RecogsFunnyNameFormatterFunction", +function(st) + if IsEmpty(st) then + return st; + else + return Concatenation(" (", st, ")"); + fi; +end); + +BindGlobal("_RecogsFunnyWWWURLFunction", +function(re) + if IsBound(re.WWWHome) then + return re.WWWHome; + else + return ""; + fi; +end); _STANDREWSMATHS := Concatenation(["Mathematical Institute, North Haugh, ", "St Andrews, Fife, KY16 9SS, Scotland"]); @@ -41,16 +47,7 @@ SourceRepository := rec( Persons := [ - rec( - LastName := "Anagnostopoulou-Merkouri", - FirstNames := "Marina", - IsAuthor := false, - IsMaintainer := false, - Email := "mam49@st-andrews.ac.uk", - PostalAddress := _STANDREWSMATHS, - Place := "St Andrews", - Institution := "University of St Andrews"), - + # The 4 main authors come first rec( LastName := "De Beule", FirstNames := "Jan", @@ -67,10 +64,60 @@ Persons := [ Place := "Brussels", Institution := "Vrije Universiteit Brussel"), + rec( + LastName := "Jonusas", + FirstNames := "Julius", + IsAuthor := true, + IsMaintainer := false, + Email := "j.jonusas@gmail.com", + WWWHome := "http://julius.jonusas.work", + Place := "Brussels, Belgium"), + + rec( + LastName := "Mitchell", + FirstNames := "James", + IsAuthor := true, + IsMaintainer := true, + Email := "jdm3@st-andrews.ac.uk", + WWWHome := "https://jdbm.me", + PostalAddress := _STANDREWSMATHS, + Place := "St Andrews", + Institution := "University of St Andrews"), + + rec( + LastName := "Wilson", + FirstNames := "Wilf A.", + IsAuthor := true, + IsMaintainer := true, + Email := "gap@wilf-wilson.net", + WWWHome := "https://wilf.me"), + + rec( + LastName := "Young", + FirstNames := "Michael", + IsAuthor := true, + IsMaintainer := true, + Email := "mct25@st-andrews.ac.uk", + WWWHome := "https://mct25.host.cs.st-andrews.ac.uk", + PostalAddress := _STANDREWSCS, + Place := "St Andrews", + Institution := "University of St Andrews"), + + # All other contributors from here on... + rec( + LastName := "Anagnostopoulou-Merkouri", + FirstNames := "Marina", + IsAuthor := true, + IsMaintainer := false, + Email := "mam49@st-andrews.ac.uk", + PostalAddress := _STANDREWSMATHS, + Place := "St Andrews", + Institution := "University of St Andrews"), + rec( LastName := "Buck", FirstNames := "Finn", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "finneganlbuck@gmail.com", PostalAddress := _STANDREWSMATHS, @@ -80,7 +127,7 @@ Persons := [ rec( LastName := "Burrell", FirstNames := "Stuart", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "stuartburrell1994@gmail.com", WWWHome := "https://stuartburrell.github.io"), @@ -88,19 +135,19 @@ Persons := [ rec( LastName := "Campbell", FirstNames := "Graham", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false), rec( LastName := "Chowdhury", FirstNames := "Raiyan", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false), rec( LastName := "Cirpons", FirstNames := "Reinis", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "rc234@st-andrews.ac.uk", PostalAddress := _STANDREWSMATHS, @@ -110,7 +157,7 @@ Persons := [ rec( LastName := "Clayton", FirstNames := "Ashley", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "ac323@st-andrews.ac.uk", PostalAddress := _STANDREWSMATHS, @@ -120,7 +167,7 @@ Persons := [ rec( LastName := "Conti-Leslie", FirstNames := "Tom", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "tom.contileslie@gmail.com", WWWHome := "https://tomcontileslie.com"), @@ -128,7 +175,7 @@ Persons := [ rec( LastName := "Edwards", FirstNames := "Joseph", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "jde1@st-andrews.ac.uk", PostalAddress := _STANDREWSMATHS, @@ -138,10 +185,10 @@ Persons := [ rec( LastName := "Elliott", - FirstNames := "Luke", - IsAuthor := false, + FirstNames := "Luna", + IsAuthor := true, IsMaintainer := false, - Email := "le27@st-andrews.ac.uk", + Email := "TODO", PostalAddress := _STANDREWSMATHS, # TODO update Place := "St Andrews", Institution := "University of St Andrews"), @@ -149,35 +196,35 @@ Persons := [ rec( LastName := "Fernando", FirstNames := "Isuru", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "isuruf@gmail.com"), rec( LastName := "Gilligan", FirstNames := "Ewan", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "eg207@st-andrews.ac.uk"), rec( LastName := "Gutsche", FirstNames := "Sebastian", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "gutsche@momo.math.rwth-aachen.de"), rec( LastName := "Harper", FirstNames := "Samantha", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "seh25@st-andrews.ac.uk"), rec( LastName := "Horn", FirstNames := "Max", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "horn@mathematik.uni-kl.de", WWWHome := "https://www.quendi.de/math", @@ -191,7 +238,7 @@ Persons := [ rec( LastName := "Jefferson", FirstNames := "Christopher", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "caj21@st-andrews.ac.uk", WWWHome := "https://caj.host.cs.st-andrews.ac.uk", @@ -199,19 +246,10 @@ Persons := [ Place := "St Andrews", Institution := "University of St Andrews"), - rec( - LastName := "Jonusas", - FirstNames := "Julius", - IsAuthor := true, - IsMaintainer := false, - Email := "j.jonusas@gmail.com", - WWWHome := "http://julius.jonusas.work", - Place := "Brussels, Belgium"), - rec( LastName := "Konovalov", FirstNames := "Olexandr", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, PostalAddress := _STANDREWSCS, Email := "obk1@st-andrews.ac.uk", @@ -221,14 +259,14 @@ Persons := [ rec(LastName := "Kwon", FirstNames := "Hyeokjun", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "hk78@st-andrews.ac.uk"), rec( LastName := "Lee", FirstNames := "Andrea", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, PostalAddress := _STANDREWSMATHS, Email := "ahwl1@st-andrews.ac.uk", @@ -238,25 +276,14 @@ Persons := [ rec( LastName := "McIver", FirstNames := "Saffron", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "sm544@st-andrews.ac.uk"), - rec( - LastName := "Mitchell", - FirstNames := "James", - IsAuthor := true, - IsMaintainer := true, - Email := "jdm3@st-andrews.ac.uk", - WWWHome := "https://jdbm.me", - PostalAddress := _STANDREWSMATHS, - Place := "St Andrews", - Institution := "University of St Andrews"), - rec( LastName := "Orlitzky", FirstNames := "Michael", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "michael@orlitzky.com", WWWHome := "https://michael.orlitzky.com/"), @@ -264,14 +291,14 @@ Persons := [ rec( LastName := "Pancer", FirstNames := "Matthew", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "mp322@st-andrews.ac.uk"), rec( LastName := "Pfeiffer", FirstNames := "Markus", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "markus.pfeiffer@morphism.de", WWWHome := "https://markusp.morphism.de/"), @@ -279,14 +306,14 @@ Persons := [ rec( LastName := "Pointon", FirstNames := "Daniel", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "dp211@st-andrews.ac.uk"), rec( LastName := "Racine", FirstNames := "Lea", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "lr217@st-andrews.ac.uk", PostalAddress := _STANDREWSCS, @@ -296,20 +323,20 @@ Persons := [ rec( LastName := "Russell", FirstNames := "Christopher", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false), rec( LastName := "Schaefer", FirstNames := "Artur", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "as305@st-and.ac.uk"), rec( LastName := "Scott", FirstNames := "Isabella", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "iscott@uchicago.edu", Place := "Chicago", @@ -318,7 +345,7 @@ Persons := [ rec( LastName := "Sharma", FirstNames := "Kamran", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "kks4@st-andrews.ac.uk", PostalAddress := _STANDREWSCS, @@ -328,7 +355,7 @@ Persons := [ rec( LastName := "Smith", FirstNames := "Finn", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "fls3@st-andrews.ac.uk", PostalAddress := _STANDREWSMATHS, @@ -338,14 +365,14 @@ Persons := [ rec( LastName := "Spiers", FirstNames := "Ben", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "bspiers972@outlook.com"), rec( LastName := "Tsalakou", FirstNames := "Maria", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "mt200@st-andrews.ac.uk", WWWHome := "https://mariatsalakou.github.io/", @@ -356,36 +383,17 @@ Persons := [ rec( LastName := "Whyte", FirstNames := "Murray", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "mw231@st-andrews.ac.uk", PostalAddress := _STANDREWSMATHS, Place := "St Andrews", Institution := "University of St Andrews"), - rec( - LastName := "Wilson", - FirstNames := "Wilf A.", - IsAuthor := true, - IsMaintainer := true, - Email := "gap@wilf-wilson.net", - WWWHome := "https://wilf.me"), - - rec( - LastName := "Young", - FirstNames := "Michael", - IsAuthor := true, - IsMaintainer := false, - Email := "mct25@st-andrews.ac.uk", - WWWHome := "https://mct25.host.cs.st-andrews.ac.uk", - PostalAddress := _STANDREWSCS, - Place := "St Andrews", - Institution := "University of St Andrews"), - rec( LastName := "Zickgraf", FirstNames := "Fabian", - IsAuthor := false, + IsAuthor := true, IsMaintainer := false, Email := "f.zickgraf@dashdos.com")], @@ -400,9 +408,6 @@ ArchiveURL := Concatenation(~.SourceRepository.URL, "/releases/download/v", ~.Version, "/", "digraphs-", ~.Version), -AbstractHTML := Concatenation("The Digraphs package is a GAP ", - "package for digraphs and multidigraphs."), - PackageDoc := rec( BookName := "Digraphs", ArchiveURLSubset := ["doc"], @@ -420,10 +425,38 @@ Dependencies := rec( ["datastructures", ">=0.2.5"]], SuggestedOtherPackages := [["GAPDoc", ">=1.6.3"], ["grape", ">=4.8.1"], - ["nautytracesinterface", ">=0.2"]], + ["nautytracesinterface", ">=0.2"], + ["AutoDoc", ">=2020.08.11"]], ExternalConditions := [], ), +BannerString := Concatenation( + "----------------------------------------------------------------------", + "-------\n", + "Loading Digraphs ", ~.Version, "\n", + "by:\n", + " ", ~.Persons[1].FirstNames, " ", ~.Persons[1].LastName, + " (", ~.Persons[1].WWWHome, "),\n", + " ", ~.Persons[2].FirstNames, " ", ~.Persons[2].LastName, + " (", ~.Persons[2].WWWHome, "),\n", + " ", ~.Persons[3].FirstNames, " ", ~.Persons[3].LastName, + " (", ~.Persons[3].WWWHome, "),\n", + " ", ~.Persons[4].FirstNames, " ", ~.Persons[4].LastName, + " (", ~.Persons[4].WWWHome, "),\n", + " ", ~.Persons[5].FirstNames, " ", ~.Persons[5].LastName, + " (", ~.Persons[5].WWWHome, ")\n", + "with contributions by:\n", + Concatenation(Concatenation(List(~.Persons{[6 .. Length(~.Persons) - 1]}, + p -> [" ", p.FirstNames, " ", p.LastName, + _RecogsFunnyNameFormatterFunction( + _RecogsFunnyWWWURLFunction(p)), ",\n"]))), + " and ", ~.Persons[Length(~.Persons)].FirstNames, " ", + ~.Persons[Length(~.Persons)].LastName, + _RecogsFunnyNameFormatterFunction( + _RecogsFunnyWWWURLFunction(~.Persons[Length(~.Persons)])), ".\n", + "-----------------------------------------------------------------------", + "------\n"), + AvailabilityTest := function() local digraphs_so; @@ -450,5 +483,33 @@ end, Autoload := false, TestFile := "tst/teststandard.g", -Keywords := [] -)); +Keywords := [], + +AutoDoc := rec( + TitlePage := rec( + Copyright := """Jan De Beule, Julius Jonušas, James D. Mitchell, + Wilf A. Wilson, Michael Young et al.

+ + &Digraphs; is free software; you can redistribute it and/or modify + it under the terms of the + https://www.fsf.org/licenses/gpl.html as published by the + Free Software Foundation; either version 3 of the License, or (at + your option) any later version.""", + Abstract := """The &Digraphs; package is a &GAP; package containing + methods for graphs, digraphs, and multidigraphs.""", + Acknowledgements := """ + We would like to thank Christopher Jefferson for his help in including + &BLISS; in &Digraphs;. + + This package's methods for computing digraph homomorphisms are based + on work by Max Neunhöffer, and independently Artur Schäfer. + """)), + + AbstractHTML := ~.AutoDoc.TitlePage.Abstract)); + +MakeReadWriteGlobal("_RecogsFunnyWWWURLFunction"); +MakeReadWriteGlobal("_RecogsFunnyNameFormatterFunction"); +Unbind(_RecogsFunnyWWWURLFunction); +Unbind(_RecogsFunnyNameFormatterFunction); +Unbind(_STANDREWSMATHS); +Unbind(_STANDREWSCS); diff --git a/doc/attr.xml b/doc/attr.xml index edd393066..09df176dd 100644 --- a/doc/attr.xml +++ b/doc/attr.xml @@ -1675,7 +1675,7 @@ gap> NrSpanningTrees(D); <#GAPDoc Label="AsGraph"> - A &Grape; package graph. + A &GRAPE; package graph. If digraph is a digraph, then this method returns the same as , except that if digraph is immutable, then the diff --git a/doc/digraph.xml b/doc/digraph.xml index d992fbe3e..05e578e11 100644 --- a/doc/digraph.xml +++ b/doc/digraph.xml @@ -192,7 +192,7 @@ for a Grape package graph - if obj is a &Grape; package graph (i.e. a record for which the + if obj is a &GRAPE; package graph (i.e. a record for which the function IsGraph returns true), then this function returns a digraph isomorphic to obj. diff --git a/doc/grape.xml b/doc/grape.xml index 012033761..7cc5e6df3 100644 --- a/doc/grape.xml +++ b/doc/grape.xml @@ -11,12 +11,12 @@ <#GAPDoc Label="Graph"> - A &Grape; package graph. + A &GRAPE; package graph. If digraph is a mutable or immutable digraph without multiple edges, then this operation - returns a &Grape; package graph that is isomorphic to digraph.

+ returns a &GRAPE; package graph that is isomorphic to digraph.

- If digraph is a multidigraph, then since &Grape; does not support + If digraph is a multidigraph, then since &GRAPE; does not support multiple edges, the multiple edges will be reduced to a single edge in the result. In order words, for a multidigraph this operation will return the same as Graph(DigraphRemoveAllMultipleEdges(digraph)). diff --git a/doc/isomorph.xml b/doc/isomorph.xml index 5e4d993a0..3cfe34bb8 100644 --- a/doc/isomorph.xml +++ b/doc/isomorph.xml @@ -14,11 +14,11 @@ Nothing. - These functions can be used to specify whether &nauty; or &bliss; should be + These functions can be used to specify whether &NAUTY; or &BLISS; should be used by default by &Digraphs;. If &NautyTracesInterface; is not available, then these functions do nothing. Otherwise, by calling DigraphsUseNauty subsequent computations will default to using - &nauty; rather than &bliss;, where possible. + &NAUTY; rather than &BLISS;, where possible.

You can call these functions at any point in a &GAP; session, as many @@ -33,7 +33,7 @@ Label="for digraphs and homogeneous lists"/> are also valid.

It is also possible to compute the automorphism group of a specific digraph - using both &nauty; and &bliss; using + using both &NAUTY; and &BLISS; using and , respectively. @@ -49,7 +49,7 @@ A permutation group. If digraph is a digraph, then this attribute contains the group of - automorphisms of digraph as calculated using &bliss; by Tommi Junttila + automorphisms of digraph as calculated using &BLISS; by Tommi Junttila and Petteri Kaski.

The attribute and @@ -60,7 +60,7 @@ their generating sets may differ.

The attribute returns the value of - BlissAutomorphismGroup as it is not implemented for &nauty; The + BlissAutomorphismGroup as it is not implemented for &NAUTY; The requirements for the optional arguments vertex_colours and edge_colours are documented in . @@ -86,7 +86,7 @@ gap> Size(G); A permutation group. If digraph is a digraph, then this attribute contains the group of - automorphisms of digraph as calculated using &nauty; by + automorphisms of digraph as calculated using &NAUTY; by Brendan Mckay and Adolfo Piperno via &NautyTracesInterface;. @@ -133,8 +133,8 @@ Group([ (3,4)(6,7)(8,9), (2,3)(5,6)(9,10), (2,5)(3,6)(4,7), Label="for a domain and a positive integer" BookName="ref"/> on the returned group.

- By default, the automorphism group is found using &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + By default, the automorphism group is found using &BLISS; by Tommi Junttila + and Petteri Kaski. If &NautyTracesInterface; is available, then &NAUTY; by Brendan Mckay and Adolfo Piperno can be used instead; see , , , @@ -206,8 +206,8 @@ true]]> Label="for a domain and a positive integer" BookName="ref"/> on the returned group.

- By default, the automorphism group is found using &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + By default, the automorphism group is found using &BLISS; by Tommi Junttila + and Petteri Kaski. If &NautyTracesInterface; is available, then &NAUTY; by Brendan Mckay and Adolfo Piperno can be used instead; see , @@ -294,8 +294,8 @@ true]]> Label="for a domain and a positive integer" BookName="ref"/> on the returned group.

- By default, the automorphism group is found using &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + By default, the automorphism group is found using &BLISS; by Tommi Junttila + and Petteri Kaski. If &NautyTracesInterface; is available, then &NAUTY; by Brendan Mckay and Adolfo Piperno can be used instead; see , @@ -349,10 +349,10 @@ true for more information about isomorphisms of digraphs.

BlissCanonicalLabelling returns a canonical labelling of the digraph - digraph found using &bliss; by Tommi Junttila and Petteri Kaski. + digraph found using &BLISS; by Tommi Junttila and Petteri Kaski. NautyCanonicalLabelling returns a canonical labelling of the digraph - digraph found using &nauty; by Brendan McKay and Adolfo Piperno. - Note that the canonical labellings returned by &bliss; and &nauty; are not + digraph found using &NAUTY; by Brendan McKay and Adolfo Piperno. + Note that the canonical labellings returned by &BLISS; and &NAUTY; are not usually the same (and may depend of the version used).

BlissCanonicalLabelling can only be computed if digraph has @@ -424,11 +424,11 @@ true]]> If digraph and colours together form a coloured digraph, BlissCanonicalLabelling returns a canonical labelling of the digraph - digraph found using &bliss; by Tommi Junttila and Petteri Kaski. + digraph found using &BLISS; by Tommi Junttila and Petteri Kaski. Similarly, NautyCanonicalLabelling returns a canonical labelling of - the digraph digraph found using &nauty; by Brendan McKay and Adolfo - Piperno. Note that the canonical labellings returned by &bliss; and - &nauty; are not usually the same (and may depend of the version used).

+ the digraph digraph found using &NAUTY; by Brendan McKay and Adolfo + Piperno. Note that the canonical labellings returned by &BLISS; and + &NAUTY; are not usually the same (and may depend of the version used).

BlissCanonicalLabelling can only be computed if digraph has no multiple edges; see . The canonical @@ -487,8 +487,8 @@ gap> List(DigraphVertices(digraph), i -> colours[i / p]); about isomorphisms of digraphs.

By default, an isomorphism is found using the canonical labellings of the - digraphs obtained from &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + digraphs 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; see , and . @@ -547,8 +547,8 @@ true]]> /> for more information about isomorphisms of coloured digraphs.

By default, an isomorphism is found using the canonical labellings of the - digraphs obtained from &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + digraphs 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; see , and . @@ -598,8 +598,8 @@ false]]> OnDigraphs(digraph1, p) = digraph2. By default, an isomorphism is found using the canonical labellings of the - digraphs obtained from &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + digraphs 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; see , and . @@ -666,8 +666,8 @@ true fail.

By default, an isomorphism is found using the canonical labellings of the - digraphs obtained from &bliss; by Tommi Junttila - and Petteri Kaski. If &NautyTracesInterface; is available, then &nauty; by + digraphs 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; see , and . diff --git a/doc/main.xml b/doc/main.xml index 95ee02d6b..61d5d1686 100644 --- a/doc/main.xml +++ b/doc/main.xml @@ -1,57 +1,27 @@ -Digraphs"> - https://gap-packages.github.io/grapeGrape"> - http://www.tcs.tkk.fi/Software/bliss/bliss"> - https://github.com/graph-algorithms/edge-addition-planarity-suiteedge-addition-planarity-suite"> - https://pallini.di.uniroma1.it/nauty"> - https://github.com/gap-packages/NautyTracesInterfaceNautyTracesInterface"> - - https://gap-packages.github.io/io/ -IO"> - - https://gap-packages.github.io/orb/ - Orb"> - https://github.com/gap-packages/datastructuresdatastructures"> - filt is present, then this should specify the category or representation the digraph being created will belong to. For example, if filt is , then the digraph being created will be mutable, if filt is , then the digraph will be immutable. If the optional first argument filt is not present, then is used by default.

"> - digraph is mutable, then the return value of this property is recomputed every time it is called.

"> - digraph is mutable, then the return value of this attribute is recomputed every time it is called.

"> - . In more detail, the vertices of the digraph are labelled by elements of the Cartesian product [1..m] x [1..n], where the first entry indexes the column (file) of the square in the chessboard, and the second entry indexes the row (rank) of the square. (Note that the files are traditionally indexed by the lowercase letters of the alphabet). The vertices are sorted in ascending order, first by row (second component) and then column (first component).

"> - m by n chessboard is a grid of m columns (‘files’) and n rows (‘ranks’) that intersect in squares. Orthogonally adjacent squares are alternately colored light and dark, with the square in the first rank and file being dark.

"> - <#Include Label="PKGVERSIONDATA"> - ]> - - -<#Include SYSTEM="z-title.xml"> + + + +] +> + +<#Include SYSTEM "title.xml"> - - <#Include SYSTEM="z-chap0.xml"> - <#Include SYSTEM="z-chap1.xml"> - <#Include SYSTEM="z-chap2.xml"> - <#Include SYSTEM="z-chap3.xml"> - <#Include SYSTEM="z-chap4.xml"> - <#Include SYSTEM="z-chap5.xml"> - <#Include SYSTEM="z-chap6.xml"> - <#Include SYSTEM="z-chap8.xml"> - <#Include SYSTEM="z-chap9.xml"> +<#Include SYSTEM "z-chap0.xml"> +<#Include SYSTEM "z-chap1.xml"> +<#Include SYSTEM "z-chap2.xml"> +<#Include SYSTEM "z-chap3.xml"> +<#Include SYSTEM "z-chap4.xml"> +<#Include SYSTEM "z-chap5.xml"> +<#Include SYSTEM "z-chap6.xml"> +<#Include SYSTEM "z-chap8.xml"> +<#Include SYSTEM "z-chap9.xml"> +<#Include SYSTEM "_AutoDocMainFile.xml"> - -<#Include SYSTEM="z-appA.xml"> - - +<#Include SYSTEM "z-appA.xml"> + - diff --git a/doc/planar.xml b/doc/planar.xml index 7fa9b559e..77e3bde4f 100644 --- a/doc/planar.xml +++ b/doc/planar.xml @@ -29,7 +29,7 @@

This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . . This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . KuratowskiPlanarSubdigraph(D);

This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . KuratowskiOuterPlanarSubdigraph(D);

This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . OuterPlanarEmbedding(CompleteBipartiteDigraph(2, 2)); Prop="IsOuterPlanarDigraph"/> for more details.

This method uses the reference implementation in - &edge-addition-planarity-suite; by John Boyer of the algorithms described + &EDGE_PLANARITY_SUITE; by John Boyer of the algorithms described in . Grape to Digraphs Command Map - Below is a table of &Grape; commands with the &Digraphs; counterparts. - The sections in this chapter correspond to the chapters in the &Grape; + Below is a table of &GRAPE; commands with the &Digraphs; counterparts. + The sections in this chapter correspond to the chapters in the &GRAPE; manual.

@@ -21,7 +21,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -43,7 +43,7 @@ - Used with the arguments of Graph in &Grape;, Graph in &GRAPE;, will return an equivalent digraph.

@@ -60,7 +60,7 @@ The operation behaves the same as - EdgeOrbitsDigraph in &Grape;. + EdgeOrbitsDigraph in &GRAPE;. @@ -79,11 +79,11 @@ - Note that, unlike in &Grape;, the arguments of and are just non-negative integers. Since digraphs in &Digraphs; are immutable, there is no reason (although it is possible) to create a null digraph - and then add edges, as you might be used to doing in &Grape;. + and then add edges, as you might be used to doing in &GRAPE;. @@ -98,7 +98,7 @@ - Note that, unlike in &Grape;, the argument to is simply a non-negative integer indicating the number of vertices. By default a complete digraph in &Digraphs; does not have any loops. If you want a complete digraph @@ -118,7 +118,7 @@ - The &Grape; function JohnsonGraph is equivalent to + The &GRAPE; function JohnsonGraph is equivalent to . @@ -135,7 +135,7 @@ The operation behaves the same as - CayleyGraph in &Grape;. + CayleyGraph in &GRAPE;. @@ -150,7 +150,7 @@ - Note that, unlike in &Grape;, digraphs in &Digraphs; are immutable, + Note that, unlike in &GRAPE;, digraphs in &Digraphs; are immutable, and this operation returns a new digraph, i.e. it does not modify the digraph given as an argument. @@ -167,7 +167,7 @@ - Note that, unlike in &Grape;, digraphs in &Digraphs; are immutable, + Note that, unlike in &GRAPE;, digraphs in &Digraphs; are immutable, and this operation returns a new digraph, i.e. it does not modify the digraph given as an argument. @@ -214,7 +214,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -253,7 +253,7 @@ The operation behaves the same as - OrderGraph in &Grape;. + OrderGraph in &GRAPE;. @@ -286,7 +286,7 @@ - Unlike VertexName in &Grape;, the return value of + Unlike VertexName in &GRAPE;, the return value of is mutable. @@ -302,7 +302,7 @@ - Unlike VertexNames in &Grape;, the return value of + Unlike VertexNames in &GRAPE;, the return value of is mutable. @@ -321,7 +321,7 @@ The vertices of a digraph in &Digraphs; is always the range [1 .. n] where n is the number of vertices of the digraph. The operation behaves the - same as Vertices in &Grape;. + same as Vertices in &GRAPE;. @@ -340,7 +340,7 @@ The operation behaves the same as - VertexDegree in &Grape;. + VertexDegree in &GRAPE;. @@ -364,7 +364,7 @@ The operation behaves the same as - VertexDegrees in &Grape;. + VertexDegrees in &GRAPE;. @@ -380,7 +380,7 @@ The operation behaves the same as - IsLoopy in &Grape;. + IsLoopy in &GRAPE;. @@ -401,7 +401,7 @@ - The &Grape; function IsSimpleGraph is equivalent to + The &GRAPE; function IsSimpleGraph is equivalent to and not . @@ -422,7 +422,7 @@ The operation behaves the same - as Adjacency in &Grape;. + as Adjacency in &GRAPE;. @@ -442,7 +442,7 @@ can be a digraph and an edge, or a digraph and two vertices. In the first form the operation - behaves the same as IsEdge in &Grape;. + behaves the same as IsEdge in &GRAPE;. @@ -458,7 +458,7 @@ The attribute behaves the same - as DirectedEdges in &Grape;. + as DirectedEdges in &GRAPE;. @@ -492,7 +492,7 @@ The operation behaves the same as - Distance in &Grape;. + Distance in &GRAPE;. @@ -508,7 +508,7 @@ The attribute behaves the same - as Diameter in &Grape;. + as Diameter in &GRAPE;. @@ -524,9 +524,9 @@ The attribute behaves the same - as Girth in &Grape; except that in the case that the + as Girth in &GRAPE; except that in the case that the argument is a forest, infinity is returned by &Digraphs; - whereas -1 is returned by &Grape;. + whereas -1 is returned by &GRAPE;. @@ -542,7 +542,7 @@ The attribute behaves the - same as IsConnectedGraph in &Grape;. + same as IsConnectedGraph in &GRAPE;. @@ -560,7 +560,7 @@ - The &Grape; function IsBipartite is equivalent to + The &GRAPE; function IsBipartite is equivalent to and . @@ -580,7 +580,7 @@ - The &Grape; function IsNullGraph is equivalent to + The &GRAPE; function IsNullGraph is equivalent to and its synonym . @@ -597,7 +597,7 @@ - The &Grape; function IsCompleteGraph is roughly + The &GRAPE; function IsCompleteGraph is roughly equivalent to except that in &Digraphs; a complete digraph has no loops. @@ -626,7 +626,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -654,7 +654,7 @@ - The &Grape; function IsRegularGraph is + The &GRAPE; function IsRegularGraph is equivalent to . @@ -670,7 +670,7 @@ - The &Grape; function LocalParameters has no equivalent + The &GRAPE; function LocalParameters has no equivalent function in &Digraphs;, although this might change in the future. @@ -686,7 +686,7 @@ - The &Grape; function GlobalParameters has no equivalent + The &GRAPE; function GlobalParameters has no equivalent function in &Digraphs;, although this might change in the future. @@ -702,7 +702,7 @@ - The &Grape; function IsDistanceRegular is + The &GRAPE; function IsDistanceRegular is equivalent to . @@ -718,7 +718,7 @@ - The &Grape; function CollapsedAdjacencyMat has no equivalent + The &GRAPE; function CollapsedAdjacencyMat has no equivalent function in &Digraphs;, although this might change in the future. @@ -734,7 +734,7 @@ - The &Grape; function OrbitalGraphColadjMats has no equivalent + The &GRAPE; function OrbitalGraphColadjMats has no equivalent function in &Digraphs;, although this might change in the future. @@ -750,7 +750,7 @@ - The &Grape; function VertexTransitiveDRGs has no equivalent + The &GRAPE; function VertexTransitiveDRGs has no equivalent function in &Digraphs;, although this might change in the future. @@ -777,7 +777,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -800,10 +800,10 @@ When applied to a simple di/graph and a vertex, - ConnectedComponent in &Grape; is equivalent to + ConnectedComponent in &GRAPE; is equivalent to . can also be applied to - non-simple graphs (in the language of &Grape;). + non-simple graphs (in the language of &GRAPE;). @@ -819,10 +819,10 @@ When applied to a simple di/graph, - ConnectedComponents in &Grape; is equivalent to + ConnectedComponents in &GRAPE; is equivalent to . can also be applied to - non-simple graphs (in the language of &Grape;). + non-simple graphs (in the language of &GRAPE;). @@ -838,11 +838,11 @@ When applied to a simple bipartite di/graph, - Bicomponents in &Grape; is equivalent to + Bicomponents in &GRAPE; is equivalent to . The definition of does not require - its argument to be simple (in the language of &Grape;), i.e. the - bipartite graphs in &Grape; are a proper subset of the bipartite + its argument to be simple (in the language of &GRAPE;), i.e. the + bipartite graphs in &GRAPE; are a proper subset of the bipartite digraphs in &Digraphs;. @@ -859,7 +859,7 @@ - DistanceSet in &Grape; is equivalent to + DistanceSet in &GRAPE; is equivalent to in &Digraphs;. @@ -876,7 +876,7 @@ - Layers in &Grape; is equivalent to + Layers in &GRAPE; is equivalent to in &Digraphs;. @@ -892,7 +892,7 @@ - IndependentSet in &Grape; is equivalent to + IndependentSet in &GRAPE; is equivalent to in &Digraphs;. @@ -919,7 +919,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -974,7 +974,7 @@ - DistanceGraph in &Grape; is equivalent to + DistanceGraph in &GRAPE; is equivalent to in &Digraphs;. @@ -992,7 +992,7 @@ in &Digraphs; is equivalent to - ComplementGraph in &Grape; with the optional argument + ComplementGraph in &GRAPE; with the optional argument comploops set to true (loops/nonloops are complemented). @@ -1025,7 +1025,7 @@ - EdgeGraph in &Grape; is equivalent to + EdgeGraph in &GRAPE; is equivalent to in &Digraphs;. @@ -1057,7 +1057,7 @@ - UnderlyingGraph in &Grape; is equivalent to + UnderlyingGraph in &GRAPE; is equivalent to in &Digraphs;. @@ -1077,7 +1077,7 @@ p of the vertices of the digraph, rather than a set of generating pairs. Hence, the equivalence might not be group-invariant. Also note that in &Digraphs; multiple edges may be - created, whereas in &Grape; they are effectively combined into a + created, whereas in &GRAPE; they are effectively combined into a single edge. @@ -1093,7 +1093,7 @@ - BipartiteDouble in &Grape; is equivalent to + BipartiteDouble in &GRAPE; is equivalent to in &Digraphs;. @@ -1186,7 +1186,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -1208,7 +1208,7 @@ - VertexColouring in &Grape; is equivalent to VertexColouring in &GRAPE; is equivalent to in &Digraphs;, except it returns a transformation rather than a list of vertex colors. @@ -1226,7 +1226,7 @@ - The functionality of CompleteSubgraphs in &Grape; is provided + The functionality of CompleteSubgraphs in &GRAPE; is provided by and in &Digraphs;. @@ -1244,7 +1244,7 @@ Much of the functionality of CompleteSubgraphsOfGivenSize in - &Grape; is provided by and and in &Digraphs;, except that the functionality relating to vertex weights and partial colourings is not implemented. @@ -1272,7 +1272,7 @@ - &Grape; command + &GRAPE; command &Digraphs; command @@ -1294,7 +1294,7 @@ - AutGroupGraph in &Grape; is equivalent to + AutGroupGraph in &GRAPE; is equivalent to in &Digraphs;. @@ -1310,7 +1310,7 @@ - GraphIsomorphism in &Grape; is equivalent to GraphIsomorphism in &GRAPE; is equivalent to in &Digraphs;. Note however that GraphIsomorphism's optional argument firstunbindcanon is not applicable, since the canonical @@ -1329,7 +1329,7 @@ - IsIsomorphicGraph in &Grape; is equivalent to IsIsomorphicGraph in &GRAPE; is equivalent to in &Digraphs;. Note however that IsIsomorphicGraph's optional argument firstunbindcanon is not applicable, since the canonical diff --git a/doc/z-chap0.xml b/doc/z-chap0.xml index 3c859b3b5..aab56004a 100644 --- a/doc/z-chap0.xml +++ b/doc/z-chap0.xml @@ -40,25 +40,25 @@ them. Full explanations of all the functions contained in the package are provided below.

- If the &Grape; package is available, it will be loaded automatically. - Digraphs created with the &Digraphs; package can be converted to &Grape; - graphs with , and conversely &Grape; graphs can be - converted to &Digraphs; objects with . &Grape; is not + If the &GRAPE; package is available, it will be loaded automatically. + Digraphs created with the &Digraphs; package can be converted to &GRAPE; + graphs with , and conversely &GRAPE; graphs can be + converted to &Digraphs; objects with . &GRAPE; is not required for &Digraphs; to run.

- The &bliss; tool is included in this package. It + The &BLISS; tool is included in this package. It is an open-source tool for computing automorphism groups and canonical forms of graphs, written by Tommi Junttila and Petteri Kaski. Several of the methods - in the &Digraphs; package rely on &bliss;. If the &NautyTracesInterface; - package for GAP is available then it is also possible to use &nauty; for computing automorphism groups and canonical forms in &Digraphs;. See Section for more details.

- The &edge-addition-planarity-suite; is also included in &Digraphs;; see + The &EDGE_PLANARITY_SUITE; is also included in &Digraphs;; see , , , and . The &edge-addition-planarity-suite; is an open-source + Key="B12"/> . The &EDGE_PLANARITY_SUITE; is an open-source implementation of the edge addition planar graph embedding algorithm and related algorithms by John M. Boyer. See Section for more details. diff --git a/doc/z-chap1.xml b/doc/z-chap1.xml index 9a2e09320..371ffb3d3 100644 --- a/doc/z-chap1.xml +++ b/doc/z-chap1.xml @@ -22,23 +22,23 @@ - ensure that the &Orb; package version &ORBVERS; or higher is available. - &Orb; has better performance when compiled, but although compilation is + ensure that the &ORB; package version &ORBVERS; or higher is available. + &ORB; has better performance when compiled, but although compilation is recommended, it is not required to be compiled for &Digraphs; to be loaded. - ensure that the &datastructures; package version + ensure that the &DATASTRUCTURES; package version &DATASTRUCTURESVERS; or higher is available. This step is optional: certain functions in &Digraphs; require - the &Grape; package to be available; see Section + the &GRAPE; package to be available; see Section for full details. To use these functions make sure - that the &Grape; package version &GRAPEVERS; or higher is available. - If &Grape; is not available, then &Digraphs; can be used as normal with + that the &GRAPE; package version &GRAPEVERS; or higher is available. + If &GRAPE; is not available, then &Digraphs; can be used as normal with the exception that the functions listed in Subsection will not work. @@ -118,10 +118,10 @@ flags are provided. --enable-debug enable debug mode - --with-external-bliss use external &bliss; + --with-external-bliss use external &BLISS; - --with-external-planarity use external &edge-addition-planarity-suite; + --with-external-planarity use external &EDGE_PLANARITY_SUITE; --with-gaproot specify root of GAP installation @@ -151,16 +151,16 @@ flags are provided. The Grape package - The &Grape; package must be available for the following operations to be + The &GRAPE; package must be available for the following operations to be available: with a digraph argument with a digraph argument - with a &Grape; graph argument + with a &GRAPE; graph argument - If &Grape; is not available, then &Digraphs; can be used as normal with + If &GRAPE; is not available, then &Digraphs; can be used as normal with the exception that the functions above will not work.

diff --git a/doc/z-chap6.xml b/doc/z-chap6.xml index 71714bd61..b298ae953 100644 --- a/doc/z-chap6.xml +++ b/doc/z-chap6.xml @@ -16,10 +16,10 @@ from} $E_a$ \emph{to} $E_b$. In this case we say that $E_a$ and $E_b$ are
Isomorphisms and canonical labellings - From version 0.11.0 of &Digraphs; it is possible to use either &bliss; or - &nauty; (via &NautyTracesInterface;) to calculate canonical labellings and + From version 0.11.0 of &Digraphs; it is possible to use either &BLISS; or + &NAUTY; (via &NautyTracesInterface;) to calculate canonical labellings and automorphism groups of digraphs; see and for more details about &bliss; and &nauty;, + Key="MP14"/> for more details about &BLISS; and &NAUTY;, respectively. <#Include Label="DigraphsUseNauty"> diff --git a/doc/z-title.xml b/doc/z-title.xml deleted file mode 100644 index 474194316..000000000 --- a/doc/z-title.xml +++ /dev/null @@ -1,89 +0,0 @@ - - &Digraphs; - Version &VERSION; - - Jan De Beule - jdebeule@cage.ugent.be - http://homepages.vub.ac.be/~jdbeule - - - Julius Jonušas - julius.jonusas@tuwien.ac.at - http://julius.jonusas.work - - - James D. Mitchell - jdm3@st-and.ac.uk - https://jdbm.me - - - Maria Tsalakou - mt200@st-andrews.ac.uk - https://mariatsalakou.github.io - - - Wilf A. Wilson - gap@wilf-wilson.net - https://wilf.me - - - Michael C. Young - mct25@st-andrews.ac.uk - https://mct25.host.cs.st-andrews.ac.uk - - - Marina Anagnostopoulou-Merkouri - - Finn Buck - - Stuart Burrell - - Reinis Cirpons - - Tom Conti-Leslie - - Luke Elliott - - Ewan Gilligan - - Max Horn - - Christopher Jefferson - - Markus Pfeiffer - - Lea Racine - - Christopher Russell - - Finn Smith - - Ben Spiers - - Murray White - - ©right; ©RIGHTYEARS; by - Jan De Beule, Julius Jonušas, James D. Mitchell, Wilf A. Wilson, - Michael Young et al.

- - &Digraphs; is free software; you can redistribute it and/or modify it - under the terms of the - https://www.fsf.org/licenses/gpl.html as published by the Free Software - Foundation; either version 3 of the License, or (at your option) any later - version. - - - - The &Digraphs; package is a &GAP; package containing methods for graphs, - digraphs, and multidigraphs. - - - - We would like to thank Christopher Jefferson for his help in including - &bliss; in &Digraphs;. - - This package's methods for computing digraph homomorphisms are based on work - by Max Neunhöffer, and independently Artur Schäfer. - - - diff --git a/gap/doc.g b/gap/doc.g deleted file mode 100644 index cea1b5acd..000000000 --- a/gap/doc.g +++ /dev/null @@ -1,74 +0,0 @@ -############################################################################# -## -## doc.g -## Copyright (C) 2021 James D. Mitchell -## Wilf A. Wilson -## -## Licensing information can be found in the README file of this package. -## -############################################################################# -## -## This file contains the information required to build the Digraphs package -## documentation, it is used by makedoc.g. - -BindGlobal("DIGRAPHS_DocXMLFiles", - ["../PackageInfo.g", - "attr.xml", - "cliques.xml", - "constructors.xml", - "digraph.xml", - "display.xml", - "examples.xml", - "grahom.xml", - "grape.xml", - "io.xml", - "isomorph.xml", - "labels.xml", - "oper.xml", - "orbits.xml", - "planar.xml", - "prop.xml", - "utils.xml", - "weights.xml"]); - -BindGlobal("DIGRAPHS_CustomCSSFile", "doc/digraphs.css"); - -BindGlobal("DIGRAPHS_MakeDoc", -function(pkgdir) - local PKG, temp, version, args, docdir, main_css, custom_css; - - PKG := "Digraphs"; - - # Get the GAP version from PackageInfo.g and write it to .VERSION - temp := SplitString(StringFile(Filename(pkgdir, "PackageInfo.g")), "\n"); - version := SplitString(First(temp, x -> StartsWith(x, "Version")), "\"")[2]; - PrintTo(Filename(pkgdir, ".VERSION"), version, "\n"); - - args := [Filename(pkgdir, "doc"), - "main.xml", - DIGRAPHS_DocXMLFiles, - PKG, - "MathJax", - "../../.."]; - # If pdflatex is not available, but we call MakeGAPDocDoc implicitly asking - # for GAPDoc to compile a PDF version of the manual, then GAPDoc fails to - # create the doc/manual.six file, which we need later. This file however is - # still created if we explicitly say that we don't want a PDF - if Filename(DirectoriesSystemPrograms(), "pdflatex") = fail then - Add(args, "nopdf"); - fi; - LoadPackage("GAPDoc"); - SetGapDocLaTeXOptions("utf8"); - CallFuncList(MakeGAPDocDoc, args); - - # HTML styling - docdir := Filename(pkgdir, "doc"); - CopyHTMLStyleFiles(docdir); - main_css := Filename(Directory(docdir), "manual.css"); - custom_css := Filename(pkgdir, DIGRAPHS_CustomCSSFile); - if IsReadableFile(custom_css) and IsWritableFile(main_css) then - AppendTo(main_css, StringFile(custom_css)); - fi; - - GAPDocManualLabFromSixFile(PKG, Filename(pkgdir, "doc/manual.six")); -end); diff --git a/gap/utils.gi b/gap/utils.gi index eba57674b..27b8801a0 100644 --- a/gap/utils.gi +++ b/gap/utils.gi @@ -102,6 +102,11 @@ end); InstallGlobalFunction(DIGRAPHS_ManualExamples, function() + if Filename(DirectoriesPackageLibrary("digraphs", "doc"), + "main.xml") = fail then + # The file main.xml only exists if AutoDoc has been run. + DigraphsMakeDoc(); + fi; return ExtractExamples(DirectoriesPackageLibrary("digraphs", "doc"), "main.xml", DIGRAPHS_DocXMLFiles, "Single"); end); @@ -207,8 +212,9 @@ end); InstallGlobalFunction(DigraphsMakeDoc, function() - # Compile the documentation of the currently-loaded version of Digraphs - DIGRAPHS_MakeDoc(DirectoriesPackageLibrary("Digraphs", "")); + local fname; + fname := Filename(DirectoriesPackageLibrary("digraphs", ""), "makedoc.g"); + Read(fname); end); InstallGlobalFunction(DigraphsTestManualExamples, diff --git a/makedoc.g b/makedoc.g index 0c4fa603d..68298e3ff 100644 --- a/makedoc.g +++ b/makedoc.g @@ -1,28 +1,158 @@ -## this creates the documentation, needs: GAPDoc package, latex, pdflatex, -## mkindex, dvips +############################################################################# ## -## Call this with GAP in the package directory: +## makedoc.g +## Copyright (C) 2024 James D. Mitchell ## -## gap makedoc.g +## Licensing information can be found in the README file of this package. +## +############################################################################# ## -if not IsDirectoryPath("gap") - or not "doc.g" in DirectoryContents("gap") then - Print("Error: GAP must be run from the package directory ", - "when reading makedoc.g\n"); - FORCE_QUIT_GAP(1); -fi; +LoadPackage("AutoDoc"); -for global in ["DIGRAPHS_DocXMLFiles", - "DIGRAPHS_MakeDoc", - "DIGRAPHS_CustomCSSFile"] do - if IsBoundGlobal(global) then - MakeReadWriteGlobal(global); - UnbindGlobal(global); +# Helper functions + +RemovePrefixVersion := function(string) + if StartsWith(string, ">=") then + return string{[3 .. Length(string)]}; fi; + return string; +end; + +UrlEntity := function(name, url) + return StringFormatted("""{2} + {1}""", name, url); +end; + +PackageEntity := function(name) + if TestPackageAvailability(name) <> fail then + return UrlEntity(PackageInfo(name)[1].PackageName, + PackageInfo(name)[1].PackageWWWHome); + fi; + return StringFormatted("{1}", name); +end; + +MathOrCode := function(string) + return StringFormatted("""{1} + {1}""", string); +end; + +XMLEntities := rec(); + +# Programmatically determined entities + +PkgInfo := PackageInfo("digraphs")[1]; + +XMLEntities.VERSION := PkgInfo.Version; +XMLEntities.GAPVERS := RemovePrefixVersion(PkgInfo.Dependencies.GAP); + +for Pkg in Concatenation(PkgInfo.Dependencies.NeededOtherPackages, + PkgInfo.Dependencies.SuggestedOtherPackages) do + entity_name := Concatenation(UppercaseString(Pkg[1]), "VERS"); + XMLEntities.(entity_name) := RemovePrefixVersion(Pkg[2]); +od; + +ARCHIVENAME := SplitString(PkgInfo.ArchiveURL, "/"); +ARCHIVENAME := Concatenation(Last(ARCHIVENAME), PkgInfo.ArchiveFormats); +XMLEntities.ARCHIVENAME := ARCHIVENAME; + +XMLEntities.DIGRAPHS := PackageEntity("Digraphs"); + +for Pkg in Concatenation(PkgInfo.Dependencies.NeededOtherPackages, + PkgInfo.Dependencies.SuggestedOtherPackages) do + entity_name := UppercaseString(Pkg[1]); + XMLEntities.(entity_name) := PackageEntity(Pkg[1]); od; -Unbind(global); -Read("gap/doc.g"); -DIGRAPHS_MakeDoc(DirectoryCurrent()); -FORCE_QUIT_GAP(); +# The files containing the xml of the doc + +DocDir := DirectoriesPackageLibrary("digraphs", "doc")[1]; +Files := Filtered(DirectoryContents(DocDir), + x -> (not StartsWith(x, ".")) + and (not StartsWith(x, "z-")) + and EndsWith(x, ".xml")); +Apply(Files, x -> Concatenation("doc/", x)); +Add(Files, "PackageInfo.g"); +Sort(Files); + +# The scaffold files (chapters) + +Includes := Filtered(DirectoryContents(DocDir), + x -> StartsWith(x, "z-") and EndsWith(x, ".xml") and not + StartsWith(x, "z-app")); +Sort(Includes); + +# Hard coded entities + +XMLEntities.BLISS := UrlEntity("bliss", + "http://www.tcs.tkk.fi/Software/bliss/"); +XMLEntities.NAUTY := UrlEntity("nauty", + "https://pallini.di.uniroma1.it"); +XMLEntities.NautyTracesInterface := UrlEntity("NautyTracesInterface", + "https://github.com/gap-packages/NautyTracesInterface"); +XMLEntities.EDGE_PLANARITY_SUITE := UrlEntity("edge-addition-planarity-suite", +"https://github.com/graph-algorithms/edge-addition-planarity-suite"); + +XMLEntities.MUTABLE_RECOMPUTED_ATTR := """If the argument digraph is +mutable, then the return value of this attribute is recomputed every time it is +called.

"""; +XMLEntities.MUTABLE_RECOMPUTED_PROP := """If the argument digraph is +mutable, then the return value of this property is recomputed every time it is +called.

"""; +XMLEntities.STANDARD_FILT_TEXT := """If the optional first argument filt +is present, then this should specify the category or representation the digraph +being created will belong to. For example, if filt is , then the digraph being created will be mutable, if +filt is , then the digraph will be +immutable. If the optional first argument filt is not present, then + is used by default.

"""; +XMLEntities.CHESSBOARD_LABELS := """The chosen correspondence between vertices +and chess squares is given by . In more +detail, the vertices of the digraph are labelled by elements of the Cartesian +product [1..m] x [1..n], where the first entry indexes the +column (file) of the square in the chessboard, and the second entry indexes the +row (rank) of the square. (Note that the files are traditionally indexed by +the lowercase letters of the alphabet). The vertices are sorted in ascending +order, first by row (second component) and then column (first component)."""; +XMLEntities.CHESSBOARD_DEFN := """An m by n chessboard is a grid +of m columns ("files") and n rows ("ranks") that intersect in +squares. Orthogonally adjacent squares are alternately colored light and dark, +with the square in the first rank and file being dark.

"""; + +# The actual call to AutoDoc + +AutoDoc("digraphs", rec( + autodoc := rec(scan_dirs := []), + gapdoc := rec( + LaTeXOptions := rec(EarlyExtraPreamble := """ + \usepackage{a4wide} + \newcommand{\bbZ}{\mathbb{Z}} + """), + main := "main", + files := Files), + + scaffold := rec( + includes := Includes, + appendix := ["z-appA.xml"], + bib := "digraphs.bib", + entities := XMLEntities))); + +# HTML styling +main_css := "doc/manual.css"; +custom_css := "doc/digraphs.css"; +if IsReadableFile(custom_css) and IsWritableFile(main_css) then + AppendTo(main_css, StringFile(custom_css)); +fi; + +Unbind(RemovePrefixVersion); +Unbind(UrlEntity); +Unbind(PackageEntity); +Unbind(Greens); +Unbind(MathOrCode); +Unbind(XMLEntities); +Unbind(PkgInfo); +Unbind(Pkg); +Unbind(ARCHIVENAME); +Unbind(DocDir); +Unbind(Files); +Unbind(Includes);