Make `FirstNames` optional in `Persons` records in package metadata

ThomasBreuer commented 1 month ago

resolves #5768

fingolfin commented 1 month ago

Just to double-check, did you verify the resulting citations look reasonable?

ThomasBreuer commented 1 month ago

@fingolfin I get the following.

gap> Cite( "alnuth" );
Please use one of the following samples
to cite Alnuth version from this installation

Text:

[ADET22]  Assmann,  B.,  Distler,  A.,  Eick,  B.  and The GAP Team, Alnuth,
ALgebraic  NUmber  THeory  and  an  interface  to  PARI/GP, Version 3.2.1dev
(2022), GAP package, https://gap-packages.github.io/alnuth.

HTML:

<p class='BibEntry'>
[<span class='BibKey'>ADET22</span>]   <b class='BibAuthor'>Assmann, B., Distl\
er, A., Eick, B. and The GAP Team</b>,
 <i class='BibTitle'>Alnuth, ALgebraic NUmber THeory and an interface to PARI/\
GP,
         Version 3.2.1dev</i>
 (<span class='BibYear'>2022</span>)<br />
(<span class='BibNote'>GAP package</span>),
<span class='BibHowpublished'><a href="https://gap-packages.github.io/alnuth">\
https://gap-packages.github.io/alnuth</a></span>.
</p>

BibXML:

<entry id="Alnuth"><misc>
  <author>
    <name><first>Björn</first><last>Assmann</last></name>
    <name><first>Andreas</first><last>Distler</last></name>
    <name><first>Bettina</first><last>Eick</last></name>
    <name><last>The GAP Team</last></name>
  </author>
  <title><C>Alnuth</C>, ALgebraic NUmber THeory and an interface to PARI/GP,
         <C>V</C>ersion 3.2.1dev</title>
  <howpublished><URL>https://gap-packages.github.io/alnuth</URL></howpublished\
>
  <month>Apr</month>
  <year>2022</year>
  <note>GAP package</note>
  <keywords>algebraic number theory; number field; maximal order; interface to\
 PARI/GP; unit group; elements of given norm</keywords>
</misc></entry>

BibTeX:

@misc{ Alnuth,
  author =           {Assmann,  B.  and Distler, A. and Eick, B. and The GAP
                      Team},
  title =            {{Alnuth},  ALgebraic NUmber THeory and an interface to
                      PARI/GP, {V}ersion 3.2.1dev},
  month =            {Apr},
  year =             {2022},
  note =             {GAP package},
  howpublished =     {\href          {https://gap-packages.github.io/alnuth}
                      {\texttt{https://gap\texttt{\symbol{45}}packages.github.\
io/}\discretionary
                      {}{}{}\texttt{alnuth}}},
  keywords =         {algebraic  number theory; number field; maximal order;
                      interface  to  PARI/GP;  unit group; elements of given
                      norm},
  printedkey =       {ADET22}
}

Compared the result shown in #5768, this looks reasonable.

frankluebeck commented 1 month ago

In my opinion this does not fix the problem in #5768.

This in not a problem with the code in GAP or GAPDoc but with the input. In the PackageInfo.g of the alnuth package we find:

Persons := [
  ...
 rec(
      LastName      := "GAP Team",
      FirstNames    := "The",
      IsAuthor      := false,
      IsMaintainer  := true,
      Email         := "support@gap-system.org",
 ),
],

and therefore it is correct that the The part is treated like a first name.

The PackageInfo.g should be changed to:

Persons := [
  ...
 rec(
      LastName      := "The GAP Team",
      IsAuthor      := false,
      IsMaintainer  := true,
      Email         := "support@gap-system.org",
 ),
],

But then there is a problem in BibEntry in file lib/package.gi which assumes that the component .FirstNames is bound. That function should probably treat .FirstNames as optional.

So, let's try:

Persons := [
  ...
 rec(
      LastName      := "The GAP Team",
      FirstNames    := "",
      IsAuthor      := false,
      IsMaintainer  := true,
      Email         := "support@gap-system.org",
 ),
],

Then we get:

Please use one of the following samples
to cite Alnuth version from this installation

Text:

[ADET22]  Assmann, B., Distler, A., Eick, B. and The GAP Team, , Alnuth, Algebraic number theory and an interface to PARI/GP, Version
3.2.1 (2022), GAP package, https://gap-packages.github.io/alnuth.

HTML:

<p class='BibEntry'>
[<span class='BibKey'>ADET22</span>]   <b class='BibAuthor'>Assmann, B., Distler, A., Eick, B. and The GAP Team,</b>,
 <i class='BibTitle'>Alnuth, Algebraic number theory and an interface to PARI/GP,
         Version 3.2.1</i>
 (<span class='BibYear'>2022</span>)<br />
(<span class='BibNote'>GAP package</span>),
<span class='BibHowpublished'><a href="https://gap-packages.github.io/alnuth">https://gap-packages.github.io/alnuth</a></span>.
</p>

BibXML:

<entry id="Alnuth"><misc>
  <author>
    <name><first>Björn</first><last>Assmann</last></name>
    <name><first>Andreas</first><last>Distler</last></name>
    <name><first>Bettina</first><last>Eick</last></name>
    <name><first></first><last>The GAP Team</last></name>
  </author>
  <title><C>Alnuth</C>, Algebraic number theory and an interface to PARI/GP,
         <C>V</C>ersion 3.2.1</title>
  <howpublished><URL>https://gap-packages.github.io/alnuth</URL></howpublished>
  <month>Apr</month>
  <year>2022</year>
  <note>GAP package</note>
  <keywords>algebraic number theory; number field; maximal order; interface to PARI/GP; unit group; elements of given norm</keywords>
</misc></entry>

BibTeX:

@misc{ Alnuth,
  author =           {Assmann, B. and Distler, A. and Eick, B. and The GAP Team,},
  title =            {{Alnuth}, Algebraic number theory and an interface to PARI/GP, {V}ersion 3.2.1},
  month =            {Apr},
  year =             {2022},
  note =             {GAP package},
  howpublished =     {\href                                                                   {https://gap-packages.github.io/alnuth}
                      {\texttt{https://gap\texttt{\symbol{45}}packages.github.io/}\discretionary {}{}{}\texttt{alnuth}}},
  keywords =         {algebraic number theory; number field; maximal order; interface to PARI/GP; unit group; elements of given norm},
  printedkey =       {ADET22}
}

This looks almost good, except that the BibTeX version should be further improved. This is done in a new commit in GAPDoc: https://github.com/frankluebeck/GAPDoc/commit/b3544aa862702d86dc879ddb1e44ba365f71a0bb

One further comment: In BibEntry it would be better to enclose the pkginfo.Subtitle with <C> tags. Then we would get in the BibTeX version of the example above {}'s around Algebraic ... PARI/GP and this would avoid that many bib styles translate the PARI/GP to lower case.

fingolfin commented 1 month ago

With FirstNames := "" not only the BibTeX output has issues, but also the plain text and HTML versions, which include The GAP Team, , Alnuth respectively The GAP Team,</b>,

ThomasBreuer commented 1 month ago

Thanks for the comments. Yes, the source of the problem is not "a bad guess" in interpreting unstructured data but a bad choice for structured data. (And the latter was caused by bad validations.)

How shall we proceed?

I think it is uncontroversial that the FirstNames components in Person records in PackageInfo.g should become optional. For that, the functions BibEntry and ValidatePackageInfo must be changed, and the changes must be documented.
BibEntry can be changed such that additional <C> tags get added.
The 34 (?) packages which currently have a "The GAP Team" person in their PackageInfo.g files can be changed such that this string goes to LastName, and FirstNames is omitted. (Shall we keep the wrong output until this has happened, or should we add the currently proposed change as a workaound until then?)

fingolfin commented 1 month ago

I agree with @ThomasBreuer's assessment. So we should first get his PR merged (so that FirstNames becomes optional), ideally in time for GAP 4.14.0. Once that is out, I can let a script run to update all affected packages to use the new author format for "The GAP Team". That's a matter of maybe 10 minutes for work.

Then over time as those packages get new releases this will be fixed.

Of course would also immediately make releases just for that. Thing is, while making the actual release (creating & uploading tarballs etc.) is quick thanks to ReleaseTools, there is still manual work needed to update the version & release date in PackageInfo.g and in CHANGES files (if there is one). This is hard to automate right now as every package handles CHANGES files & versioning schemes differently. For 35 packages I think 2-3 packages per package is a low estimate, but already adds up to 1-2 hours of work. I don't think it's worth this bother.

gap-system / gap

Make `FirstNames` optional in `Persons` records in package metadata #5822