It would be nice to have some sort of custom keyword in ASCII Doc to refer to git hashes. Specifically for the list of __FreeBSD_version values, but also in other places. This would allow centralizing the decision of how many hex digits to abbreviate in the rendered text as well as the generation of the link in the rendered website. I'm not sure if ASCII Doc keywords can except parameters (in this case which repository the hash belongs to), if not we might need separate 'srcgit', 'docgit', etc. keywords?
Yes, we can do that. I'm gonna create an extension.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/doc/commit/?id=fb36cfdfb2dd5e9ebe217d820609d96fb73d8cc8 commit fb36cfdfb2dd5e9ebe217d820609d96fb73d8cc8 Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-02-13 21:16:57 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2021-02-13 21:22:34 +0000 Add gitref macro to reference a git hash With this extension a git hash can be easily referenced. The porters handbook versions chapter uses this extension as an example in the FreeBSD 14.0 version table. An example of use gitref:hash[repository="src|doc|ports",length=hash-longitude] The repository should be src, doc or ports. And if no length it's specified the macro will use 12 characters of the specified hash. PR: 253050 Submitted by: jhb@ documentation/config/_default/config.toml | 2 +- .../books/porters-handbook/versions/chapter.adoc | 8 +++---- shared/lib/GitReferencesMacro/extension.rb (new) | 25 ++++++++++++++++++++++ shared/lib/git-macro.rb (new) | 5 +++++ website/config/_default/config.toml | 2 +- 5 files changed, 36 insertions(+), 6 deletions(-)
I just committed this extension to the repository. You can find an example of use in the versions chapter of the porters handbook.