regen_doc.g

#############################################################################
##
##  This file is part of recog, a package for the GAP computer algebra system
##  which provides a collection of methods for the constructive recognition
##  of groups.
##
##  Copyright of recog belongs to its developers whose names are too numerous
##  to list here. Please refer to the COPYRIGHT file for details.
##
##  SPDX-License-Identifier: GPL-3.0-or-later
##
##
##  Regenerate parts of the recog documentation from its source code
##
#############################################################################

# We need the precise version of recog contained in the current directory; if
# recog is not yet loaded, that's no problem; otherwise, we need to work a bit
# to verify that this is the case, and otherwise exit with an error Reading
# the implementation part of the recog package.
if not IsBound(GAPInfo.PackagesLoaded.recog) then
    SetPackagePath("recog", "./");
    LoadPackage("recog");
else
    loadedPath := GAPInfo.PackagesLoaded.recog[1];
    # ask bash whether that path corresponds to the current directory
    testPath := DirectoriesSystemPrograms();
    testPath := Filename(testPath, "test");
    res := Process( DirectoryCurrent(), testPath,
                    InputTextNone(), OutputTextNone(),
                    [ GAPInfo.PackagesLoaded.recog[1], "-ef", "." ] );
    if res <> 0 then
        ErrorNoReturn("a different version of recog was already loaded or you ",
                      "started GAP in the wrong directory; try ",
                      "`gap -A regen_doc.g` or `gap -A makedoc.g`");
    fi;
fi;

GenerateMethodsTableXML := function(shortname, desc, db)
local xmlfile, meth;

    xmlfile := Concatenation("doc/_methods_", shortname, "_table.xml");
    xmlfile := OutputTextFile(xmlfile, false);
    SetPrintFormattingStatus(xmlfile, false);

    PrintTo(xmlfile, "<Table Align=\"|l|l|l|l|\">\n");
    AppendTo(xmlfile, "<Caption>", desc, " group find homomorphism methods</Caption>\n");
    AppendTo(xmlfile, "<HorLine/>\n");

    SortBy(db, x -> -x.rank);
    for meth in db do
        AppendTo(xmlfile, "<Row>\n");
        AppendTo(xmlfile, "<Item>", meth.rank, "</Item>\n");
        AppendTo(xmlfile, "<Item><C>", meth.stamp, "</C></Item>\n");
        AppendTo(xmlfile, "<Item>", meth.comment, "</Item>\n");
        AppendTo(xmlfile, "<Item><Ref Subsect=\"", meth.stamp, "\"/></Item>\n");
        AppendTo(xmlfile, "</Row>\n");
        AppendTo(xmlfile, "<HorLine/>\n");
    od;

    AppendTo(xmlfile, "</Table>\n");

    CloseStream(xmlfile);

end;

GenerateMethodsListXML := function(shortname, desc, db)
local xmlfile, meth;

    xmlfile := Concatenation("doc/_methods_", shortname, "_list.xml");
    xmlfile := OutputTextFile(xmlfile, false);
    SetPrintFormattingStatus(xmlfile, false);

    for meth in Set(RecNames(db)) do
        AppendTo(xmlfile, "<Subsection Label=\"", meth, "\">\n");
        AppendTo(xmlfile, "<Heading><C>", meth, "</C></Heading>\n");
        AppendTo(xmlfile, "<#Include Label=\"", meth, "\">\n");
        AppendTo(xmlfile, "</Subsection>\n");
   od;

    CloseStream(xmlfile);

end;

GenerateMethodsTableXML("matrix", "Matrix", FindHomDbMatrix);
GenerateMethodsTableXML("perm", "Permutation", FindHomDbPerm);
GenerateMethodsTableXML("proj", "Projective", FindHomDbProjective);

GenerateMethodsListXML("generic", "Generic", FindHomMethodsGeneric);
GenerateMethodsListXML("matrix", "Matrix", FindHomMethodsMatrix);
GenerateMethodsListXML("perm", "Permutation", FindHomMethodsPerm);
GenerateMethodsListXML("proj", "Projective", FindHomMethodsProjective);