meta: extra fields (#126)

Expand the metadata properties with additional fields, intended for use in
code generation (see #94).

CITATION.bib

@@ -3,7 +3,7 @@ @misc{addchain
     author       = {Michael B. McLoughlin},
     year         = 2021,
     month        = may,
-    howpublished = {Github repository \url{https://github.com/mmcloughlin/addchain}},
+    howpublished = {Repository \url{https://github.com/mmcloughlin/addchain}},
     version      = {0.3.0},
     license      = {BSD 3-Clause License},
     doi          = {10.5281/zenodo.4758226},

README.md

@@ -363,7 +363,7 @@ release](https://github.com/mmcloughlin/addchain/releases/tag/v0.3.0).
     author       = {Michael B. McLoughlin},
     year         = 2021,
     month        = may,
-    howpublished = {Github repository \url{https://github.com/mmcloughlin/addchain}},
+    howpublished = {Repository \url{https://github.com/mmcloughlin/addchain}},
     version      = {0.3.0},
     license      = {BSD 3-Clause License},
     doi          = {10.5281/zenodo.4758226},

internal/tools/docgen/templates/cff.tmpl

@@ -1,14 +1,14 @@
 cff-version: 1.2.0
 message: "If you use addchain in your work, a citation would be appreciated using the following metadata."
-title: "addchain: Cryptographic Addition Chain Generation in Go"
+title: "{{ .Meta.Title }}"
 authors:
   - family-names: "McLoughlin"
     given-names: "Michael Ben"
     orcid: "https://orcid.org/0000-0003-2347-6258"
 version: "{{ .Meta.ReleaseVersion }}"
 date-released: "{{ .Meta.ReleaseDate }}"
 license: BSD-3-Clause
-repository-code: https://github.com/mmcloughlin/addchain
+repository-code: {{ .Meta.RepositoryURL }}
 doi: "{{ .Meta.DOI }}"
 identifiers:
   - type: doi

internal/tools/docgen/templates/readme.tmpl

@@ -7,7 +7,7 @@
   <a href="{{ .Meta.DOIURL }}"><img src="https://img.shields.io/badge/DOI-{{ urlquery .Meta.DOI }}-007ec6?style=flat-square" alt="DOI: {{ .Meta.DOI }}" /></a>
 </p>
 
-<p align="center">Cryptographic Addition Chain Generation in Go</p>
+<p align="center">{{ .Meta.Description }}</p>
 
 `addchain` generates short addition chains for exponents of cryptographic
 interest with [results](#results) rivaling the best hand-optimized chains.
@@ -98,7 +98,7 @@ produce high quality results in an automated code generation tool.
 ### Command-line Interface
 
 Install a pre-compiled [release
-binary](https://github.com/mmcloughlin/addchain/releases):
+binary]({{ .Meta.RepositoryURL }}/releases):
 
 ```
 curl -sSfL https://git.io/addchain | sh -s -- -b /usr/local/bin
@@ -107,7 +107,7 @@ curl -sSfL https://git.io/addchain | sh -s -- -b /usr/local/bin
 Alternatively build from source:
 
 ```
-go install github.com/mmcloughlin/addchain/cmd/addchain@latest
+go install {{ .Meta.Module }}/cmd/addchain@latest
 ```
 
 Search for a curve25519 field inversion addition chain with:
@@ -127,7 +127,7 @@ Output:
 Install:
 
 ```
-go get -u github.com/mmcloughlin/addchain
+go get -u {{ .Meta.Module }}
 ```
 
 Algorithms all conform to the {{ sym "alg" "ChainAlgorithm" }} or
@@ -199,7 +199,7 @@ about their precise definition and poor results from early experiments.
 Furthermore, this library does not apply weights to the heuristics as
 suggested in the paper, rather it simply uses the first that applies. However
 both of these remain [possible avenues for
-improvement](https://github.com/mmcloughlin/addchain/issues/26).
+improvement]({{ .Meta.RepositoryURL }}/issues/26).
 
 #### References
 
@@ -276,7 +276,7 @@ These micro-optimizations were vital in closing the gap between `addchain`'s
 automated approaches and hand-optimized chains. This technique is reminiscent
 of basic passes in optimizing compilers, raising the question of whether
 other [compiler optimizations could apply to addition
-chains](https://github.com/mmcloughlin/addchain/issues/24)?
+chains]({{ .Meta.RepositoryURL }}/issues/24)?
 
 > I have not seen this method discussed in the literature. Please help me find references to prior art if you know any.
 
@@ -286,14 +286,14 @@ If you use `addchain` in your research a citation would be appreciated.
 Citing a specific release is preferred, since they are [archived on
 Zenodo]({{ .Meta.ConceptDOIURL }}) and assigned a DOI. Please use the
 following BibTeX to cite the most recent [{{ .Meta.ReleaseVersion }}
-release]({{ .Meta.GithubReleaseURL }}).
+release]({{ .Meta.ReleaseURL }}).
 
 ```bib
 {{ .Meta.Citation -}}
 ```
 
 If you need to cite a currently unreleased version please consider [filing an
-issue](https://github.com/mmcloughlin/addchain/issues/new) to request a new
+issue]({{ .Meta.RepositoryURL }}/issues/new) to request a new
 release, or to discuss an appropriate format for the citation.
 
 ## Thanks
@@ -308,11 +308,11 @@ Glancy](https://twitter.com/mglancy) for review.
 
 Contributions to `addchain` are welcome:
 
-* [Submit bug reports](https://github.com/mmcloughlin/addchain/issues/new) to
+* [Submit bug reports]({{ .Meta.RepositoryURL }}/issues/new) to
   the issues page.
-* Suggest [test cases](https://github.com/mmcloughlin/addchain/blob/e6c070065205efcaa02627ab1b23e8ce6aeea1db/internal/results/results.go#L62)
+* Suggest [test cases]({{ .Meta.RepositoryURL }}/blob/e6c070065205efcaa02627ab1b23e8ce6aeea1db/internal/results/results.go#L62)
   or update best-known hand-optimized results.
-* Pull requests accepted. Please discuss in the [issues section](https://github.com/mmcloughlin/addchain/issues)
+* Pull requests accepted. Please discuss in the [issues section]({{ .Meta.RepositoryURL }}/issues)
   before starting significant work.
 
 ## License

internal/tools/docgen/templates/zenodo.tmpl

@@ -1,6 +1,6 @@
 {
-    "title": "mmcloughlin/addchain: {{ .Meta.ReleaseTag }}",
-    "description": "Cryptographic Addition Chain Generation in Go",
+    "title": "{{ .Meta.FullName }}: {{ .Meta.ReleaseTag }}",
+    "description": "{{ .Meta.Description }}",
     "version": "{{ .Meta.ReleaseVersion }}",
     "publication_date": "{{ .Meta.ReleaseDate }}",
     "upload_type": "software",

meta/cite.go

@@ -35,12 +35,12 @@ func (p *Properties) WriteCitation(w io.Writer) error {
 	field := func(key, value string) { tw.Linef("    %s\t=\t%s,", key, value) }
 	str := func(key, value string) { field(key, "{"+value+"}") }
 
-	tw.Linef("@misc{addchain,")
-	str("title", "addchain: Cryptographic Addition Chain Generation in Go")
+	tw.Linef("@misc{%s,", p.Name)
+	str("title", p.Title())
 	str("author", "Michael B. McLoughlin")
 	field("year", strconv.Itoa(date.Year()))
 	field("month", strings.ToLower(date.Month().String()[:3]))
-	str("howpublished", "Github repository \\url{https://github.com/mmcloughlin/addchain}")
+	str("howpublished", "Repository \\url{"+p.RepositoryURL()+"}")
 	str("version", p.ReleaseVersion)
 	str("license", "BSD 3-Clause License")
 	str("doi", p.DOI)

meta/meta.go

@@ -1,14 +1,27 @@
 // Package meta defines properties about this project.
 package meta
 
-import "time"
+import (
+	"fmt"
+	"path"
+	"time"
+)
 
 // VersionTagPrefix is the prefix used on Git tags corresponding to semantic
 // version releases.
 const VersionTagPrefix = "v"
 
 // Properties about this software package.
 type Properties struct {
+	// Name is the project name.
+	Name string
+
+	// FullName is the "owner/name" identifier for the project.
+	FullName string
+
+	// Description is the concise project headline.
+	Description string
+
 	// BuildVersion is the version that was built. Typically populated at build
 	// time and will typically be empty for non-release builds.
 	BuildVersion string
@@ -31,6 +44,9 @@ type Properties struct {
 
 // Meta defines specific properties for the current version of this software.
 var Meta = &Properties{
+	Name:           "addchain",
+	FullName:       "mmcloughlin/addchain",
+	Description:    "Cryptographic Addition Chain Generation in Go",
 	BuildVersion:   buildversion,
 	ReleaseVersion: releaseversion,
 	ReleaseDate:    releasedate,
@@ -39,6 +55,11 @@ var Meta = &Properties{
 	ZenodoID:       zenodoid,
 }
 
+// Title is a full project title, suitable for a citation.
+func (p *Properties) Title() string {
+	return fmt.Sprintf("%s: %s", p.Name, p.Description)
+}
+
 // IsRelease reports whether the built version is a release.
 func (p *Properties) IsRelease() bool {
 	return p.BuildVersion == p.ReleaseVersion
@@ -49,9 +70,19 @@ func (p *Properties) ReleaseTag() string {
 	return VersionTagPrefix + p.ReleaseVersion
 }
 
-// GithubReleaseURL returns the URL to the release page on Github.
-func (p *Properties) GithubReleaseURL() string {
-	return "https://github.com/mmcloughlin/addchain/releases/tag/" + p.ReleaseTag()
+// Module returns the Go module path.
+func (p *Properties) Module() string {
+	return path.Join("github.com", p.FullName)
+}
+
+// RepositoryURL returns a URL to the hosted repository.
+func (p *Properties) RepositoryURL() string {
+	return "https://" + p.Module()
+}
+
+// ReleaseURL returns the URL to the release page.
+func (p *Properties) ReleaseURL() string {
+	return fmt.Sprintf("%s/releases/tag/%s", p.RepositoryURL(), p.ReleaseTag())
 }
 
 // ReleaseTime returns the release date as a time object.