kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

Merge branch 'ma/doc-discard-docbook-xsl-1.73' 

Raise the minimum required version of docbook-xsl package to 1.74,
as 1.74.0 was from late 2008, which is more than 10 years old, and
drop compatibility cruft from our documentation suite.

* ma/doc-discard-docbook-xsl-1.73:
  user-manual.conf: don't specify [listingblock]
  INSTALL: drop support for docbook-xsl before 1.74
  manpage-normal.xsl: fold in manpage-base.xsl
  manpage-bold-literal.xsl: stop using git.docbook.backslash
  Doc: drop support for docbook-xsl before 1.73.0
  Doc: drop support for docbook-xsl before 1.72.0
  Doc: drop support for docbook-xsl before 1.71.1
maint
Junio C Hamano 2020-04-28 15:50:00 -07:00
parent 27dd34b95e 3c255ad660
commit ed9aa096bb
10 changed files with 22 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
Documentation/Makefile
View File

@ -150,32 +150,9 @@ endif
-include ../config.mak.autogen
-include ../config.mak

#
# For docbook-xsl ...
# -1.68.1, no extra settings are needed?
# 1.69.0, set ASCIIDOC_ROFF?
# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP?
# 1.71.1, set ASCIIDOC_ROFF?
# 1.72.0, set DOCBOOK_XSL_172.
# 1.73.0-, no extra settings are needed
#

ifdef DOCBOOK_XSL_172
ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
MANPAGE_XSL = manpage-1.72.xsl
else
ifndef ASCIIDOC_ROFF
# docbook-xsl after 1.72 needs the regular XSL, but will not
# pass-thru raw roff codes from asciidoc.conf, so turn them off.
ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
endif
endif
ifndef NO_MAN_BOLD_LITERAL
XMLTO_EXTRA += -m manpage-bold-literal.xsl
endif
ifdef DOCBOOK_SUPPRESS_SP
XMLTO_EXTRA += -m manpage-suppress-sp.xsl
endif

# Newer DocBook stylesheet emits warning cruft in the output when
# this is not set, and if set it shows an absolute link. Older

19
Documentation/asciidoc.conf
View File

@ -31,24 +31,6 @@ ifdef::backend-docbook[]
endif::backend-docbook[]

ifdef::backend-docbook[]
ifndef::git-asciidoc-no-roff[]
# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
# v1.72 breaks with this because it replaces dots not in roff requests.
[listingblock]
<example><title>{title}</title>
<literallayout class="monospaced">
ifdef::doctype-manpage[]
&#10;.ft C&#10;
endif::doctype-manpage[]
|
ifdef::doctype-manpage[]
&#10;.ft&#10;
endif::doctype-manpage[]
</literallayout>
{title#}</example>
endif::git-asciidoc-no-roff[]

ifdef::git-asciidoc-no-roff[]
ifdef::doctype-manpage[]
# The following two small workarounds insert a simple paragraph after screen
[listingblock]
@ -67,7 +49,6 @@ ifdef::doctype-manpage[]
{title#}</para></formalpara>
{title%}<simpara></simpara>
endif::doctype-manpage[]
endif::git-asciidoc-no-roff[]
endif::backend-docbook[]

ifdef::doctype-manpage[]

14
Documentation/manpage-1.72.xsl
View File

@ -1,14 +0,0 @@
<!-- manpage-1.72.xsl:
special settings for manpages rendered from asciidoc+docbook
handles peculiarities in docbook-xsl 1.72.0 -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">

<xsl:import href="manpage-base.xsl"/>

<!-- these are the special values for the roff control characters
needed for docbook-xsl 1.72.0 -->
<xsl:param name="git.docbook.backslash">&#x2593;</xsl:param>
<xsl:param name="git.docbook.dot" >&#x2302;</xsl:param>

</xsl:stylesheet>

35
Documentation/manpage-base.xsl
View File

@ -1,35 +0,0 @@
<!-- manpage-base.xsl:
special formatting for manpages rendered from asciidoc+docbook -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">

<!-- these params silence some output from xmlto -->
<xsl:param name="man.output.quietly" select="1"/>
<xsl:param name="refentry.meta.get.quietly" select="1"/>

<!-- convert asciidoc callouts to man page format;
git.docbook.backslash and git.docbook.dot params
must be supplied by another XSL file or other means -->
<xsl:template match="co">
<xsl:value-of select="concat(
$git.docbook.backslash,'fB(',
substring-after(@id,'-'),')',
$git.docbook.backslash,'fR')"/>
</xsl:template>
<xsl:template match="calloutlist">
<xsl:value-of select="$git.docbook.dot"/>
<xsl:text>sp&#10;</xsl:text>
<xsl:apply-templates/>
<xsl:text>&#10;</xsl:text>
</xsl:template>
<xsl:template match="callout">
<xsl:value-of select="concat(
$git.docbook.backslash,'fB',
substring-after(@arearefs,'-'),
'. ',$git.docbook.backslash,'fR')"/>
<xsl:apply-templates/>
<xsl:value-of select="$git.docbook.dot"/>
<xsl:text>br&#10;</xsl:text>
</xsl:template>

</xsl:stylesheet>

6
Documentation/manpage-bold-literal.xsl
View File

@ -8,11 +8,9 @@
this makes literal text easier to distinguish in manpages
viewed on a tty -->
<xsl:template match="literal|d:literal">
<xsl:value-of select="$git.docbook.backslash"/>
<xsl:text>fB</xsl:text>
<xsl:text>\fB</xsl:text>
<xsl:apply-templates/>
<xsl:value-of select="$git.docbook.backslash"/>
<xsl:text>fR</xsl:text>
<xsl:text>\fR</xsl:text>
</xsl:template>

</xsl:stylesheet>

25
Documentation/manpage-normal.xsl
View File

@ -1,13 +1,26 @@
<!-- manpage-normal.xsl:
special settings for manpages rendered from asciidoc+docbook
handles anything we want to keep away from docbook-xsl 1.72.0 -->
special settings for manpages rendered from asciidoc+docbook -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">

<xsl:import href="manpage-base.xsl"/>

<!-- these are the normal values for the roff control characters -->
<xsl:param name="git.docbook.backslash">\</xsl:param>
<xsl:param name="git.docbook.dot" >.</xsl:param>
<!-- these params silence some output from xmlto -->
<xsl:param name="man.output.quietly" select="1"/>
<xsl:param name="refentry.meta.get.quietly" select="1"/>

<!-- convert asciidoc callouts to man page format -->
<xsl:template match="co">
<xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
</xsl:template>
<xsl:template match="calloutlist">
<xsl:text>.sp&#10;</xsl:text>
<xsl:apply-templates/>
<xsl:text>&#10;</xsl:text>
</xsl:template>
<xsl:template match="callout">
<xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/>
<xsl:apply-templates/>
<xsl:text>.br&#10;</xsl:text>
</xsl:template>

</xsl:stylesheet>

21
Documentation/manpage-suppress-sp.xsl
View File

@ -1,21 +0,0 @@
<!-- manpage-suppress-sp.xsl:
special settings for manpages rendered from asciidoc+docbook
handles erroneous, inline .sp in manpage output of some
versions of docbook-xsl -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">

<!-- attempt to work around spurious .sp at the tail of the line
that some versions of docbook stylesheets seem to add -->
<xsl:template match="simpara">
<xsl:variable name="content">
<xsl:apply-templates/>
</xsl:variable>
<xsl:value-of select="normalize-space($content)"/>
<xsl:if test="not(ancestor::authorblurb) and
not(ancestor::personblurb)">
<xsl:text>&#10;&#10;</xsl:text>
</xsl:if>
</xsl:template>

</xsl:stylesheet>

10
Documentation/user-manual.conf
View File

@ -9,13 +9,3 @@ tilde=&#126;

[linkgit-inlinemacro]
<ulink url="{target}.html">{target}{0?({0})}</ulink>

ifdef::backend-docbook[]
# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
[listingblock]
<example><title>{title}</title>
<literallayout class="monospaced">
|
</literallayout>
{title#}</example>
endif::backend-docbook[]

4
INSTALL
View File

@ -206,9 +206,7 @@ Issues of note:
clone two separate git-htmldocs and git-manpages repositories next
to the clone of git itself.

It has been reported that docbook-xsl version 1.72 and 1.73 are
buggy; 1.72 misformats manual pages for callouts, and 1.73 needs
the patch in contrib/patches/docbook-xsl-manpages-charmap.patch
The minimum supported version of docbook-xsl is 1.74.

Users attempting to build the documentation on Cygwin may need to ensure
that the /etc/xml/catalog file looks something like this:

6
Makefile
View File

@ -282,12 +282,6 @@ all::
# Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks
# field that counts the on-disk footprint in 512-byte blocks.
#
# Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72
# (not v1.73 or v1.71).
#
# Define ASCIIDOC_ROFF if your DocBook XSL does not escape raw roff directives
# (versions 1.68.1 through v1.72).
#
# Define GNU_ROFF if your target system uses GNU groff. This forces
# apostrophes to be ASCII so that cut&pasting examples to the shell
# will work.