Bug 253050

Summary:	Add a keyword for Git hashes (and perhaps SVN revisions for older things)
Product:	Documentation	Reporter:	John Baldwin <jhb>
Component:	Website	Assignee:	Sergio Carlavilla Delgado <carlavilla>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	---
Version:	Latest
Hardware:	Any
OS:	Any

Description John Baldwin freebsd_committer

2021-01-27 20:02:17 UTC

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?

Comment 1 Sergio Carlavilla Delgado freebsd_committer

2021-02-13 19:09:40 UTC

Yes, we can do that. I'm gonna create an extension.

Comment 2 commit-hook freebsd_committer

2021-02-13 21:23:40 UTC

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(-)

Comment 3 Sergio Carlavilla Delgado freebsd_committer

2021-02-13 21:24:52 UTC

I just committed this extension to the repository. You can find an example of use in the versions chapter of the porters handbook.