git: 86bba6a538 - Add infrastructure for links to Git commits.
John Baldwin
jhb at FreeBSD.org
Tue Dec 22 21:59:10 UTC 2020
The branch main has been updated by jhb:
URL: https://cgit.FreeBSD.org/doc/commit/?id=86bba6a538e51a18204651cf9a9a72fceec839d4
commit 86bba6a538e51a18204651cf9a9a72fceec839d4
Author: John Baldwin <jhb at FreeBSD.org>
AuthorDate: 2020-12-21 18:54:42 +0000
Commit: John Baldwin <jhb at FreeBSD.org>
CommitDate: 2020-12-22 21:48:38 +0000
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(-)
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|segmentedli
st|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|g
losslist|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
More information about the dev-commits-doc-all
mailing list