Problems with cross references between manuals

[frankluebeck]

I open this issue to link to this issue for the repository of the GAP website.

The exactly same problem exists for the GAP distribution. In the GAP 4.11.1 distribution the HTML versions of all manuals contain about 275 links to other manuals that do not work.

The mentioned other issue contains a script that add symbolic links in the pkg/ directory that makes almost all of these links work - but for the cost of introducing confusing directory names.

[frankluebeck]

Here is a proposal for one solution.

All packages which have version information in their directory name seem to use the format MainName-VersionPart.

Assuming that the MainName part remains stable, we could add symbolic links MainName pointing to the longer directory name. (Does this work in Windows?)

Then GAP will load all packages using the shorter name (check GAPInfo.PackagesLoaded).(*) As a consequence, manuals which are built in this setup will introduce HTML links using the shorter names.

So, one could use the "hack" script mentioned above temporarily and after a few releases it will no longer be needed.

(*) This statement can be checked in the code of InitializePackagesInfoRecords, see Set( DirectoryContents( Filename( pkgdir, "" ) ) ) and StableSortParallel( ....

[frankluebeck]

If symbolic links are not sufficiently supported by Windows, we could also return to the former setup where packages were put in directories with normalized names. No information is lost, because the package version is in its PackageInfo.g file.

[fingolfin]

The problematic links (i.e., to directories with names of the form PackageName-1.2.3 instead of packagename) persists in the following packages in GAP 4.12.1:

• [x] atlasrep
• [x] ctbllib (this one has such links against itself, to its doc2 manual)
• [ ] gapdoc (version 1.6.6 has links to io-4.7.0)
• [x] openmath
• [ ] permut (version 2.0.4 has links to format-1.4.3)
• [x] scscp
• [x] unitlib
• [x] utils

To fix this, I recommend building the package manuals for the release against a pristine copy of GAP 4.12.0 (or 4.12.1 once it is out tomorrow). For anyone using ReleaseTools, this can be done like this:

GAP=/path/to/gap-4.12.0/gap release-gap-package

Ping @ThomasBreuer @alex-konovalov @cdwensley @RamonEstebanRomero

[cdwensley]

Sorry, but I do not understand this at all: (a) I can see no problematic link in the Utils manual; (b) my development version is not at the moment in a state to be released.

[ThomasBreuer]

Concerning AtlasRep, the situation is tricky: There is (logically) one bad link in the AtlasRep manual, which points to the utils manual. More precisely, AtlasRep needs a link to a function that is not yet available in the version of utils that belongs to GAP 4.12.0. Thus I had installed the current version 0.77 of utils in the pkg directory of the GAP 4.12.0 installation w.r.t. which I have created the AtlasRep documentation. From the viewpoint of the offending links, I should have renamed the directory utils-0.77 to utils (but this is wrong from the viewpoint of GAP 4.12.0).

How can this be made foolproof? On the one hand, the package archives have to be created before a new GAP release, but on the other hand, computing the cross-references in the documentation requires an installation of the system as it will look like after the release. (Is it necessary to create a new AtlasRep release because of the bad link?)

[ThomasBreuer]

I am going to use the following piece of code in the script that builds the package documentation (makedocrel.g) of AtlasRep and CTblLib.

With this modification, the links from the package in question to other packages and to other books of the same package are adjusted to the normalized names of the subdirectories of pkg in the distributed version of GAP. Then the links are correct under the assumptions that they shall point to the packages as they are contained in the package distribution; if there are dependencies on newer versions of some packages then the links created by the function are wrong.

GAPDoc2HTMLProcs.AdjustExtURL_Orig:= GAPDoc2HTMLProcs.AdjustExtURL;

GAPDoc2HTMLProcs.AdjustExtURL := function( r, url )
  local res, pkgpath, self, pos, pos2, prefix, pkgname, suffix;

  res:= GAPDoc2HTMLProcs.AdjustExtURL_Orig( r, url );
  if IsBound( GAPDoc2HTMLProcs.RelPath ) then
    # We want to replace absolute paths in links to other package manuals
    # by relative links.
    pkgpath:= Concatenation( GAPInfo.MainRootPath, "pkg/" );
    if not StartsWith( res, pkgpath ) then
      # Perhaps the link points to a package outside the main root path.
      # Probably this indicates an error.
      if ForAny( RecNames( GAPInfo.PackagesLoaded ),
                 x -> StartsWith( res, GAPInfo.PackagesLoaded.( x )[1] ) ) then
        Error( "<url> points to a package outside the main GAP root path" );
      fi;
      # Otherwise the link is just kept.
      # Typical examples are links to the GAP Manuals,
      # they will get replaced via the GAPDoc function.
    else
      # The link points to a file in the main GAP root path.
      self:= GAPInfo.PackagesLoaded.( GAPInfo.CurrentPackageName );
      if StartsWith( res, self[1] ) then
        # The link points to a file inside the same package
        # but in a different book.
        # In this case, we want to create a link relative to the package
        # not only relative to the GAP root directory.
        res:= Concatenation( "..",
                  res{ [ Length( self[1] ) + 1 .. Length( res ) ] } );
      else
        # The link points to a file inside another package.
        # Use 'GAPInfo.PackagesLoaded' for deriving the normalized name of
        # this package from the directory name that occurs in the link.
        pos:= Length( pkgpath );
        pos2:= Position( res, '/', pos );
        prefix:= res{ [ 1 .. pos2-1 ] };
        pkgname:= First( RecNames( GAPInfo.PackagesLoaded ),
                         x -> GAPInfo.PackagesLoaded.( x )[1] = prefix );
        suffix:= res{ [ pos2 .. Length( res ) ] };
        res:= Concatenation( prefix{ [ 1 .. pos ] }, pkgname, suffix );
      fi;
    fi;
  fi;

  return res;
end;

[fingolfin]

Good news: this issue has been resolved in all packages but one: GAPDoc 1.6.6 has links containing io-4.7.0 and GAPDoc-1.6.6.

Seeing as there are a bunch of minor fixes and tweaks in the GAPDoc repository, I hope this can be resolved by simply having a new GAPDoc release -- ping @frankluebeck