From 86bba6a538e51a18204651cf9a9a72fceec839d4 Mon Sep 17 00:00:00 2001
From: John Baldwin <jhb@FreeBSD.org>
Date: Mon, 21 Dec 2020 10:54:42 -0800
Subject: Add infrastructure for links to Git commits.

- Add a <githash> tag which accepts a Git hash.  Leave
  <revnumber> as is for svn revisions.  In theory we
  could add a new attribute to <revnumber> to say which
  VCS to use, but this would require tagging either all
  SVN revisions or all Git hashes explicitly which would
  be invasive.  A new tag going forward seems simpler.

- Revert svnweb.link back to generating svnweb links.  This
  fixes all the explicit <revnumber>'s referring to SVN src
  commits in existing documentation.

- Add a cgit.link which links to a Git commit in cgit.
  githash generates cgit.link's when asked to generate a
  href.

Reviewed by:	gjb, ygy
Differential Revision:	https://reviews.freebsd.org/D27703
---
 share/misc/docbook.css             |  4 ++++
 share/xml/docbook50.dtd            | 16 +++++++++++++---
 share/xml/freebsd-common.xsl       | 15 ++++++++++++++-
 share/xml/freebsd-fo.xsl           | 17 +++++++++++++++++
 share/xml/freebsd-xhtml-common.xsl | 18 ++++++++++++++++++
 share/xml/freebsd50.rnc            |  1 +
 6 files changed, 67 insertions(+), 4 deletions(-)

(limited to 'share')

diff --git a/share/misc/docbook.css b/share/misc/docbook.css
index c4029cf975..38e7bf476e 100644
--- a/share/misc/docbook.css
+++ b/share/misc/docbook.css
@@ -265,6 +265,10 @@ html {
 	color: #007a00;
 }
 
+.gitref {
+	color: #007a00;
+}
+
 .guimenu, .guimenuitem, .guisubmenu,
 .guilabel, .interface,
 .shortcut, .shortcut .keycap {
diff --git a/share/xml/docbook50.dtd b/share/xml/docbook50.dtd
index 9bb6f37f10..365f54eddc 100644
--- a/share/xml/docbook50.dtd
+++ b/share/xml/docbook50.dtd
@@ -321,7 +321,7 @@
 >
 
 <!ELEMENT para (#PCDATA|info|inlinemediaobject|remark|superscript|subscript|xref|link|olink|anchor|biblioref|alt|annotation|indexterm|abbrev|acronym|date|emphasis|footnote|footnoteref|foreignphrase|phrase|quote|wordasword|firstterm|glossterm|coref|trademark|productnumber|productname|database|application|hardware|citation|citerefentry|citetitle|citebiblioid|author|person|personname|org|orgname|editor|jobtitle|replaceable|package|parameter|termdef|nonterminal|systemitem|option|optional|property|inlineequation|tag|markup|token|symbol|literal|code|constant|email|uri|guiicon|guibutton|guimenuitem|guimenu|guisubmenu|guilabel|menuchoice|mousebutton|keycombo|keycap|keycode|keysym|shortcut|accel|prompt|envar|filename|command|computeroutput|userinput|function|varname|returnvalue|type|classname|exceptionname|interfacename|methodname|modifier|initializer|ooclass|ooexception|oointerface|errorcode|errortext|errorname|errortype|itemizedlist|orderedlist|procedure|simplelist|variablelist|segmentedlist|glosslist|bibliolist|calloutlist|qandaset|example|figure|table|equation|informalexample|informalfigure|informaltable|informalequation|sidebar|blockquote|address|epigraph|mediaobject|screenshot|task|productionset|constraintdef|msgset|screen|literallayout|programlistingco|screenco|programlisting|synopsis|bridgehead|revhistory|funcsynopsis|classsynopsis|methodsynopsis|constructorsynopsis|destructorsynopsis|fieldsynopsis|cmdsynopsis|caution|important|note|tip|warning|
-	revnumber|buildtarget|xi:include)*>
+	revnumber|buildtarget|xi:include|githash)*>
 
 <!ATTLIST para
 	xmlns	CDATA	#FIXED	"http://docbook.org/ns/docbook"
@@ -1311,7 +1311,7 @@
 
 >
 
-<!ELEMENT revision ((revnumber)?, date, (authorinitials|author)*, ((revremark|revdescription))?)>
+<!ELEMENT revision ((revnumber|githash)?, date, (authorinitials|author)*, ((revremark|revdescription))?)>
 
 <!ATTLIST revision
 	xmlns	CDATA	#FIXED	"http://docbook.org/ns/docbook"
@@ -1331,6 +1331,16 @@
 
 >
 
+<!ELEMENT githash (#PCDATA|inlinemediaobject|remark|superscript|subscript|xref|link|olink|anchor|biblioref|alt|annotation|indexterm|phrase|replaceable)*>
+
+<!ATTLIST githash
+	xmlns	CDATA	#FIXED	"http://docbook.org/ns/docbook"
+	role	CDATA	#IMPLIED
+	%db.common.attributes;
+	%db.common.linking.attributes;
+
+>
+
 <!ELEMENT revremark (#PCDATA|inlinemediaobject|remark|superscript|subscript|xref|link|olink|anchor|biblioref|alt|annotation|indexterm|phrase|replaceable)*>
 
 <!ATTLIST revremark
@@ -2881,7 +2891,7 @@
 >
 
 <!ELEMENT entry (#PCDATA|inlinemediaobject|remark|superscript|subscript|xref|link|olink|anchor|biblioref|alt|annotation|indexterm|abbrev|acronym|date|emphasis|footnote|footnoteref|foreignphrase|phrase|quote|wordasword|firstterm|glossterm|coref|trademark|productnumber|productname|database|application|hardware|citation|citerefentry|citetitle|citebiblioid|author|person|personname|org|orgname|editor|jobtitle|replaceable|package|parameter|termdef|nonterminal|systemitem|option|optional|property|inlineequation|tag|markup|token|symbol|literal|code|constant|email|uri|guiicon|guibutton|guimenuitem|guimenu|guisubmenu|guilabel|menuchoice|mousebutton|keycombo|keycap|keycode|keysym|shortcut|accel|prompt|envar|filename|command|computeroutput|userinput|function|varname|returnvalue|type|classname|exceptionname|interfacename|methodname|modifier|initializer|ooclass|ooexception|oointerface|errorcode|errortext|errorname|errortype|itemizedlist|orderedlist|procedure|simplelist|variablelist|segmentedlist|glosslist|bibliolist|calloutlist|qandaset|example|figure|table|equation|informalexample|informalfigure|informaltable|informalequation|sidebar|blockquote|address|epigraph|mediaobject|screenshot|task|productionset|constraintdef|msgset|screen|literallayout|programlistingco|screenco|programlisting|synopsis|bridgehead|revhistory|funcsynopsis|classsynopsis|methodsynopsis|constructorsynopsis|destructorsynopsis|fieldsynopsis|cmdsynopsis|caution|important|note|tip|warning|para|formalpara|simpara|
-	revnumber|buildtarget)*>
+	revnumber|buildtarget|githash)*>
 
 <!ATTLIST entry
 	xmlns	CDATA	#FIXED	"http://docbook.org/ns/docbook"
diff --git a/share/xml/freebsd-common.xsl b/share/xml/freebsd-common.xsl
index 5da114730a..5499c42e47 100644
--- a/share/xml/freebsd-common.xsl
+++ b/share/xml/freebsd-common.xsl
@@ -16,6 +16,11 @@
     <xsl:call-template name="svnref.genlink"/>
   </xsl:template>
 
+  <!-- Generate link for githash -->
+  <xsl:template match="db:githash">
+    <xsl:call-template name="gitref.genlink"/>
+  </xsl:template>
+
   <!-- Redefine variables, and replace templates as necessary here -->
   <xsl:template match="db:buildtarget|db:command">
     <xsl:call-template name="inline.monoseq"/>
@@ -25,7 +30,15 @@
     <xsl:param name="repo" select="'base'"/>
     <xsl:param name="rev"/>
 
-    <xsl:value-of select="concat('https://cgit.freebsd.org/doc/commit/?id=',
+    <xsl:value-of select="concat('https://svnweb.freebsd.org/changeset/',
+      $repo, '/', $rev)"/>
+  </xsl:template>
+
+  <xsl:template name="cgit.link">
+    <xsl:param name="repo" select="'src'"/>
+    <xsl:param name="rev"/>
+
+    <xsl:value-of select="concat('https://cgit.freebsd.org/', $repo, '/commit/?id=',
       $rev)"/>
   </xsl:template>
 
diff --git a/share/xml/freebsd-fo.xsl b/share/xml/freebsd-fo.xsl
index 3d786b2de7..102e4dba31 100644
--- a/share/xml/freebsd-fo.xsl
+++ b/share/xml/freebsd-fo.xsl
@@ -581,6 +581,23 @@
     </fo:basic-link>
   </xsl:template>
 
+  <xsl:template name="gitref.genlink">
+    <xsl:param name="rev" select="."/>
+    <xsl:param name="repo" select="'src'"/>
+    <xsl:variable name="href">
+      <xsl:call-template name="cgit.link">
+	<xsl:with-param name="repo" select="$repo"/>
+	<xsl:with-param name="rev" select="$rev"/>
+      </xsl:call-template>
+    </xsl:variable>
+
+    <fo:basic-link external-destination="url({$href})">
+      <fo:inline color="blue">
+	<xsl:value-of select="$rev"/>
+      </fo:inline>
+    </fo:basic-link>
+  </xsl:template>
+
   <xsl:template name="chapter.authorgroup">
     <fo:inline font-style="italic">
       <xsl:call-template name="freebsd.authorgroup"/>
diff --git a/share/xml/freebsd-xhtml-common.xsl b/share/xml/freebsd-xhtml-common.xsl
index 3f90b34249..abc66af2d4 100644
--- a/share/xml/freebsd-xhtml-common.xsl
+++ b/share/xml/freebsd-xhtml-common.xsl
@@ -212,6 +212,24 @@
     </a>
   </xsl:template>
 
+  <xsl:template name="gitref.genlink">
+    <xsl:param name="rev" select="."/>
+    <xsl:param name="repo" select="'src'"/>
+
+    <a>
+      <xsl:attribute name="href">
+	<xsl:call-template name="cgit.link">
+	  <xsl:with-param name="repo" select="$repo"/>
+	  <xsl:with-param name="rev" select="$rev"/>
+	</xsl:call-template>
+      </xsl:attribute>
+
+      <span class="gitref">
+	<xsl:value-of select="$rev"/>
+      </span>
+    </a>
+  </xsl:template>
+
   <xsl:template name="generate.citerefentry.link">
     <xsl:text>https://www.FreeBSD.org/cgi/man.cgi?query=</xsl:text>
     <xsl:value-of select="db:refentrytitle"/>
diff --git a/share/xml/freebsd50.rnc b/share/xml/freebsd50.rnc
index a240d0317a..695542c1c6 100644
--- a/share/xml/freebsd50.rnc
+++ b/share/xml/freebsd50.rnc
@@ -39,6 +39,7 @@ include "/usr/local/share/xml/docbook/5.0/rng/docbook.rnc" inherit = db {
   # FreeBSD extension: add buildtarget element to allowed inlines
   db.extension.inlines = db.buildtarget
      | db.revnumber
+     | db.githash
 #    | db.trademark
 
 
-- 
cgit v1.2.3