Generate entities from PackageInfo.g metadata?

[fingolfin]

As you know, some packages have stuff like this in their PackageInfo.g:

Version        := "1.2.3",
Date           := "20/01/2015",
##  <#GAPDoc Label="PKGVERSIONDATA">
##  <!ENTITY VERSION "1.2.3">
##  <!ENTITY RELEASEDATE "20 January 2015">
##  <!ENTITY RELEASEYEAR "2015">
##  <#/GAPDoc>

Of course we generate title pages to take of that; but if one wants to reference the version in some other place in the manual, that doesn't help. Now, in general I am tempted to say that you just shouldn't use the version in other places ;-). At least I can think of any real justification for doing that...

But perhaps there are reasons why one might want to do that?

Well, we could of course insert the equivalent of the above entity definition, too. Also for other keys, e.g. the IssueTrackerURL, etc..

It would be easy to do -- but I am not quite convinced we should... I'll wait if anybody shows up he really wants this ... :)

[olexandr-konovalov]

Sounds familiar - I am using this approach in my packages. This way, I need to increment version and update dates twice, but at least all lines that should be changed are in a single block in the same file, and nowhere else.

[fingolfin]

A fw more notes on this:

• this is not so convenient for the authors lists, but for these, we could offer generating an authors.xml, which contains just that.
• A benefit of all this is that users are free to adjust their title pages, and e.g. don't need to add an AutoDoc record with copyright and acknowledgements to their PackageInfo.g. Plus, if they want, they can make changes, e.g. change the version string from just 1.2.3 to Version 1.2.3 in the manual.
• For maximal flexibility, we'd want multiple representations of the release date (day/month/year split; all in iso format; all in the way it appears in PackageInfo.g; a human readable format, as in the example above.
• a lot of this was easier if we'd support more flexible templating, including things like loops and conditionals (just like e.g. jekyll has with liquid, or provided by jinja, etc. etc.)

[fingolfin]

Note that to really make use of this, people would still have to let AutoDoc at least generate the "main" XML file, as that declares the entities. But usually that's no issue, I think...

[fingolfin]

Having thought some more about this, I think the best solution is this: in the package info record in PackageInfo.g, we already allow for an AutoDoc field, in which we already allow a TitlePage record entry; this AutoDoc.TitlePage then works analogous to scaffold.TitlePage in the arguments for the AutoDoc() function.

I propose that we add a TitlePage.Entities field (or perhaps TitlePage.entities to match scaffold.entities? But then everything else in PackageInfo.g uses CamelCase conventions... perhaps we should instead change scaffold.entities to scaffold.Entities, allowing the old spelling for backwards compatibility? Or just allow both?!?).

This gives us maximal flexibility, and should still be rather easy to implement.

[fingolfin]

I just realized that we already merge the pkginfo.AutoDoc record into scaffold -- thus, it is actually already possible to specify entities in PackageInfo.g, by adding to pkginfo.AutoDoc.entities, it just isn't documented (and I wasn't aware about it). While I'd prefer the spelling Entities, being able to use this with old AutoDoc versions kind of is a nice bonus.

I am not sure I feel too good about merging pkginfo.AutoDoc into scaffold in general, though -- so I might still nerf that feature to limit it to TitlePage and perhaps entities/Entities.

[wilfwilson]

I want to give a big +1 to this feature request.

I can offer you a use case, because I currently try to hack together such a system in Vole. You can see in the Vole makedoc.g file that I attempt to add various information about Vole itself as entities, and also about some of its dependencies.

The principal reason for doing this is that I want the manual to have detailed installation instructions, which are up to date in terms of versions and URLs.

That way, a user can easily learn about and navigate through this information, just from the manual.

[fingolfin]

Note that I have been doing something like this for quite some time in a bunch of packages, by adding this to PackageInfo.g:

AutoDoc := rec(
        VERSION := ~.Version,
        RELEASEYEAR := ~.Date{[7..10]},
        RELEASEDATE := function(date)
          local day, month, year, allMonths;
          day := Int(date{[1,2]});
          month := Int(date{[4,5]});
          year := Int(date{[7..10]});
          allMonths := [ "January", "February", "March", "April", "May", "June", "July",
                         "August", "September", "October", "November", "December"];
          return Concatenation(String(day)," ", allMonths[month], " ", String(year));
        end(~.Date),
   ),

But these days I tend to agree that we should add an option for the Autodoc command which automatically defines these entities. A PR would be welcome.

[fingolfin]

So I think this is really done, except that handling RELEASEDATE and RELEASEYEAR is annoying. Hence I made PR #295.

But e.g. transfering the issue tracker of package website URLs is already very easy to do.