From bb2300976ba1491a54dc2b82819fae68d59d6e53 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:49:38 -0500 Subject: [PATCH 01/11] Documentation/Makefile: make most operations "quiet" This adapts the "quiet make" implementation from the main Makefile. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/Makefile | 84 +++++++++++++++++++++++++++--------------- 1 file changed, 55 insertions(+), 29 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 144ec32f12..3e1d175ee6 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -76,6 +76,32 @@ endif # yourself - yes, all 6 characters of it! # +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifndef V + QUIET_ASCIIDOC = @echo ' ' ASCIIDOC $@; + QUIET_XMLTO = @echo ' ' XMLTO $@; + QUIET_DB2TEXI = @echo ' ' DB2TEXI $@; + QUIET_MAKEINFO = @echo ' ' MAKEINFO $@; + QUIET_DBLATEX = @echo ' ' DBLATEX $@; + QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; + QUIET_GEN = @echo ' ' GEN $@; + QUIET_STDERR = 2> /dev/null + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + all: html man html: $(DOC_HTML) @@ -119,7 +145,7 @@ install-html: html sh ./install-webdoc.sh $(DESTDIR)$(htmldir) ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE - $(MAKE) -C ../ GIT-VERSION-FILE + $(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE -include ../GIT-VERSION-FILE @@ -127,8 +153,8 @@ install-html: html # Determine "include::" file references in asciidoc files. # doc.dep : $(wildcard *.txt) build-docdep.perl - $(RM) $@+ $@ - $(PERL_PATH) ./build-docdep.perl >$@+ + $(QUIET_GEN)$(RM) $@+ $@ && \ + $(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \ mv $@+ $@ -include doc.dep @@ -146,8 +172,8 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) - $(RM) $@ - $(PERL_PATH) ./cmd-list.perl ../command-list.txt + $(QUIET_GEN)$(RM) $@ && \ + $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \ date >$@ clean: @@ -158,79 +184,79 @@ clean: $(RM) $(cmds_txt) *.made $(MAN_HTML): %.html : %.txt - $(RM) $@+ $@ + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ %.1 %.5 %.7 : %.xml - $(RM) $@ + $(QUIET_XMLTO)$(RM) $@ && \ xmlto -m $(MANPAGE_XSL) man $< %.xml : %.txt - $(RM) $@+ $@ + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \ mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf - $(ASCIIDOC) -b docbook -d book $< + $(QUIET_ASCIIDOC)$(ASCIIDOC) -b docbook -d book $< technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) - cd technical && sh ./api-index.sh + $(QUIET_GEN)cd technical && sh ./api-index.sh $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt - $(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ + $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \ $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css user-manual.html: user-manual.xml - xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< + $(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $< git.info: user-manual.texi - $(MAKEINFO) --no-split -o $@ user-manual.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi user-manual.texi: user-manual.xml - $(RM) $@+ $@ + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout | \ - $(PERL_PATH) fix-texi.perl >$@+ + $(PERL_PATH) fix-texi.perl >$@+ && \ mv $@+ $@ user-manual.pdf: user-manual.xml - $(RM) $@+ $@ - $(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< + $(QUIET_DBLATEX)$(RM) $@+ $@ && \ + $(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< && \ mv $@+ $@ gitman.texi: $(MAN_XML) cat-texi.perl - $(RM) $@+ $@ + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ - --to-stdout $(xml);)) | $(PERL_PATH) cat-texi.perl $@ >$@+ + --to-stdout $(xml) &&) true) | $(PERL_PATH) cat-texi.perl $@ >$@+ && \ mv $@+ $@ gitman.info: gitman.texi - $(MAKEINFO) --no-split --no-validate $*.texi + $(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml - $(RM) $@+ $@ - $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ + $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ + $(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \ mv $@+ $@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) - $(RM) $@+ $@ - sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ + $(QUIET_GEN)$(RM) $@+ $@ && \ + sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \ mv $@+ $@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt - $(ASCIIDOC) -b xhtml11 $*.txt + $(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 $*.txt WEBDOC_DEST = /pub/software/scm/git/docs $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt - $(RM) $@+ $@ - sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ && \ mv $@+ $@ install-webdoc : html From c6a5ad21e57ce38a0add04a2708ccf02ed17af39 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:49:39 -0500 Subject: [PATCH 02/11] Documentation/Makefile: break up texi pipeline Most shells define the exit value of a pipeline as the exit value of the last process. For each texi rule, run the DOCBOOK2X_TEXI tool and the "fixup" script in their own non-pipeline commands so that make will notice an error exit code. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/Makefile | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e1d175ee6..d145372393 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -178,7 +178,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) clean: $(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 - $(RM) *.texi *.texi+ git.info gitman.info + $(RM) *.texi *.texi+ *.texi++ git.info gitman.info $(RM) howto-index.txt howto/*.html doc.dep $(RM) technical/api-*.html technical/api-index.txt $(RM) $(cmds_txt) *.made @@ -221,8 +221,9 @@ git.info: user-manual.texi user-manual.texi: user-manual.xml $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ - $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout | \ - $(PERL_PATH) fix-texi.perl >$@+ && \ + $(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \ + $(PERL_PATH) fix-texi.perl <$@++ >$@+ && \ + rm $@++ && \ mv $@+ $@ user-manual.pdf: user-manual.xml @@ -233,7 +234,9 @@ user-manual.pdf: user-manual.xml gitman.texi: $(MAN_XML) cat-texi.perl $(QUIET_DB2TEXI)$(RM) $@+ $@ && \ ($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \ - --to-stdout $(xml) &&) true) | $(PERL_PATH) cat-texi.perl $@ >$@+ && \ + --to-stdout $(xml) &&) true) > $@++ && \ + $(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \ + rm $@++ && \ mv $@+ $@ gitman.info: gitman.texi From c30e9485238bb8e9daa4cbba5deb1f79c8da7dde Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:43:58 -0500 Subject: [PATCH 03/11] Documentation: move callouts.xsl to manpage-{base,normal}.xsl Each of manpage-base.xsl and manpage-normal.xsl gets a copy of the contents of callouts.xsl and the original is removed. The Makefile is adjusted to refer to manpage-normal.xsl instead of callouts.xsl. manpage-base.xsl will be later made into a common base for -normal and -1.72. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- .../{callouts.xsl => manpage-base.xsl} | 0 Documentation/manpage-normal.xsl | 30 +++++++++++++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) rename Documentation/{callouts.xsl => manpage-base.xsl} (100%) create mode 100644 Documentation/manpage-normal.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index 144ec32f12..e1562e351c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -41,7 +41,7 @@ man7dir=$(mandir)/man7 ASCIIDOC=asciidoc ASCIIDOC_EXTRA = -MANPAGE_XSL = callouts.xsl +MANPAGE_XSL = manpage-normal.xsl INSTALL?=install RM ?= rm -f DOC_REF = origin/man diff --git a/Documentation/callouts.xsl b/Documentation/manpage-base.xsl similarity index 100% rename from Documentation/callouts.xsl rename to Documentation/manpage-base.xsl diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl new file mode 100644 index 0000000000..6a361a2136 --- /dev/null +++ b/Documentation/manpage-normal.xsl @@ -0,0 +1,30 @@ + + + + + + + .sp + + + + + + + .br + + + + + + + + + + + + + + From ae8d09b8fa138aeb8ec3e20819360241dfb9f0b8 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:43:59 -0500 Subject: [PATCH 04/11] Documentation: use parametrized manpage-base.xsl with manpage-{1.72,normal}.xsl Parametrize the backslash and dot characters that are used to generate roff control sequences in manpage-base.xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/manpage-1.72.xsl | 29 +++++++++++------------- Documentation/manpage-base.xsl | 39 ++++++++++++++++---------------- Documentation/manpage-normal.xsl | 30 +++++++++++------------- 3 files changed, 46 insertions(+), 52 deletions(-) diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl index 4065a3a27a..e24d26cd00 100644 --- a/Documentation/manpage-1.72.xsl +++ b/Documentation/manpage-1.72.xsl @@ -1,21 +1,18 @@ - - + + + + + +▓ +⌂ + + - - - - - ⌂sp - - - - - - - ⌂br - - diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl index 6a361a2136..6d3eb1912a 100644 --- a/Documentation/manpage-base.xsl +++ b/Documentation/manpage-base.xsl @@ -1,30 +1,31 @@ - - + + + + - + - .sp + + sp - + - .br - - - - - - - - - - - + + br diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl index 6a361a2136..e36472f5ad 100644 --- a/Documentation/manpage-normal.xsl +++ b/Documentation/manpage-normal.xsl @@ -1,21 +1,17 @@ - - - - - - - .sp - - - - - - - .br - + + - + + + +\ +. + + From 8fa2b45f3a70a1622c8fc5d35af148da5cab80d1 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:44:00 -0500 Subject: [PATCH 05/11] Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff It seems that the ability to use raw roff codes in asciidoc.conf was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the 1.72.0-specific XSLT problem, this behavior was not reverted in later releases. This patch aims to make it clear that the affected asciidoc attribute (flag) can be reasonably used with docbook-xsl versions other than 1.72.0. Also, document which make variables should be set for various versions of asciidoc and docbook-xsl. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/Makefile | 29 ++++++++++++++++++++++++++++- Documentation/asciidoc.conf | 8 ++++---- 2 files changed, 32 insertions(+), 5 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index e1562e351c..d71760b807 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -59,12 +59,39 @@ endif -include ../config.mak.autogen -include ../config.mak +# +# For asciidoc ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0-1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# + ifdef ASCIIDOC8 ASCIIDOC_EXTRA += -a asciidoc7compatible endif ifdef DOCBOOK_XSL_172 -ASCIIDOC_EXTRA += -a docbook-xsl-172 +ASCIIDOC_EXTRA += -a git-asciidoc-no-roff MANPAGE_XSL = manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_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 # diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 1e735df3bb..ce1b1755ae 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -27,7 +27,7 @@ ifdef::backend-docbook[] endif::backend-docbook[] ifdef::backend-docbook[] -ifndef::docbook-xsl-172[] +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] @@ -42,9 +42,9 @@ ifdef::doctype-manpage[] endif::doctype-manpage[] {title#} -endif::docbook-xsl-172[] +endif::git-asciidoc-no-roff[] -ifdef::docbook-xsl-172[] +ifdef::git-asciidoc-no-roff[] ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] @@ -62,7 +62,7 @@ ifdef::doctype-manpage[] {title#} endif::doctype-manpage[] -endif::docbook-xsl-172[] +endif::git-asciidoc-no-roff[] endif::backend-docbook[] ifdef::doctype-manpage[] From 9d8d13a8c52c55ad4695b659cbffa61e4c3a3774 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:44:01 -0500 Subject: [PATCH 06/11] Documentation: move quieting params into manpage-base.xsl Move a couple of XSL parameters that act to silence informational/warning messages generated when running xmlto from manpage-1.72.xsl to manpage-base.xsl. Since unused parameters are silently ignored, there is no problem if some version of docbook-xsl does not know about these parameters. The only problem might be if a version of docbook-xsl uses the parameters for alternate functionality. Since both parameters have fairly specific names such a situation is unlikely. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/manpage-1.72.xsl | 4 ---- Documentation/manpage-base.xsl | 4 ++++ 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl index e24d26cd00..b4d315cb8c 100644 --- a/Documentation/manpage-1.72.xsl +++ b/Documentation/manpage-1.72.xsl @@ -11,8 +11,4 @@ ▓ ⌂ - - - - diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl index 6d3eb1912a..a264fa6160 100644 --- a/Documentation/manpage-base.xsl +++ b/Documentation/manpage-base.xsl @@ -3,6 +3,10 @@ + + + + From 34c800b8fcbd85c276cb102b3e60d170aa9e55e0 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:44:02 -0500 Subject: [PATCH 07/11] Documentation: move "spurious .sp" code into manpage-base.xsl The "spurious .sp" code should be independent of docbook-xsl versions. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/manpage-base.xsl | 13 +++++++++++++ Documentation/manpage-normal.xsl | 13 ------------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl index a264fa6160..16e2e40976 100644 --- a/Documentation/manpage-base.xsl +++ b/Documentation/manpage-base.xsl @@ -32,4 +32,17 @@ br + + + + + + + + + + + diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl index e36472f5ad..a48f5b11f3 100644 --- a/Documentation/manpage-normal.xsl +++ b/Documentation/manpage-normal.xsl @@ -10,17 +10,4 @@ \ . - - - - - - - - - - - From dad3211503e2760a0e704b3c617849ba298a76e7 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:44:03 -0500 Subject: [PATCH 08/11] Documentation: asciidoc.conf: always use for [blocktext] Make the docbook-xsl-no-raw-roff variant match the no-docbook-xsl-no-raw-roff variant in terms of which XML tag is used to wrap listing block text (delimited with lines of dashes). e920b56 (Tweak asciidoc output to work with broken docbook-xsl, 2006-03-05) says docbook-xsl 1.68 needs . This usages was in the old, 1.72-only section. But since it is now the "roff-less" section, it probably makes sense to make it symmetric with the "roff-ful" section. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/asciidoc.conf | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index ce1b1755ae..9963f2da81 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -49,9 +49,9 @@ ifdef::doctype-manpage[] # The following two small workarounds insert a simple paragraph after screen [listingblock] {title} - + | - + {title#} [verseblock] From 0c04f5273579da4b8308c125b1eb4b8f888bffab Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:44:04 -0500 Subject: [PATCH 09/11] Documentation: asciidoc.conf: fix verse block with block titles No files use the variant of block-title with verse-block, but such a case would have generated broken docbook XML ( is not allowed inside ). This fixes the potential deviation from valid docbook XML. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/asciidoc.conf | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 9963f2da81..dc76e7f073 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -59,8 +59,9 @@ ifdef::doctype-manpage[] {title%} {title#} | - + {title#} +{title%} endif::doctype-manpage[] endif::git-asciidoc-no-roff[] endif::backend-docbook[] From 5121a6d99368906292dfdf7fe0047fb89c4c1969 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Fri, 27 Mar 2009 01:44:05 -0500 Subject: [PATCH 10/11] Documentation: option to render literal text as bold for manpages This allows manpages viewed on a tty to render inline literal text in a manner that is distinct from the surrounding text. The initial implementation (pre-mailing-list) of this patch included a conditional variant of the XSLT code in manpage-base.xsl and use xmlto's --stringparam option to optionally enable the functionality. It turns out that --stringparam is broken in all versions of xmlto except for the pre-release, SVN version. Since xmlto is a shell script the patch to fix it is simple enough, but I instead opted to use xmlto's "module" functionality. Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/Makefile | 6 +++++- Documentation/manpage-bold-literal.xsl | 17 +++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 Documentation/manpage-bold-literal.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index d71760b807..1c94531874 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -42,6 +42,7 @@ man7dir=$(mandir)/man7 ASCIIDOC=asciidoc ASCIIDOC_EXTRA = MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = INSTALL?=install RM ?= rm -f DOC_REF = origin/man @@ -93,6 +94,9 @@ else ASCIIDOC_EXTRA += -a git-asciidoc-no-roff endif endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif # # Please note that there is a minor bug in asciidoc. @@ -192,7 +196,7 @@ $(MAN_HTML): %.html : %.txt %.1 %.5 %.7 : %.xml $(RM) $@ - xmlto -m $(MANPAGE_XSL) man $< + xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< %.xml : %.txt $(RM) $@+ $@ diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl new file mode 100644 index 0000000000..608eb5df62 --- /dev/null +++ b/Documentation/manpage-bold-literal.xsl @@ -0,0 +1,17 @@ + + + + + + + fB + + + fR + + + From 2346431e476ab9f095f0dd2921f63fa071039bb8 Mon Sep 17 00:00:00 2001 From: Chris Johnsen Date: Wed, 1 Apr 2009 03:50:34 -0500 Subject: [PATCH 11/11] Documentation: use "spurious .sp" XSLT if DOCBOOK_SUPPRESS_SP is set With this change, the "spurious .sp" suppression XSLT code is disabled by default. It can be enabled by defining DOCBOOK_SUPPRESS_SP. The "spurious .sp" XSLT fragment was used to work around a bug first released in docbook-xsl 1.69.1. Modern versions of docbook-xsl are negatively affected by the code (some empty lines are omitted from manpage output; see ). The key revisions in the docbook SVN repo seem to be 5144 (before docbook-xsl 1.69.1) and 6359 (before docbook-xsl 1.71.1). Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0. Signed-off-by: Chris Johnsen Signed-off-by: Junio C Hamano --- Documentation/Makefile | 7 ++++++- Documentation/RelNotes-1.6.3.txt | 5 +++++ Documentation/manpage-base.xsl | 13 ------------- Documentation/manpage-suppress-sp.xsl | 21 +++++++++++++++++++++ 4 files changed, 32 insertions(+), 14 deletions(-) create mode 100644 Documentation/manpage-suppress-sp.xsl diff --git a/Documentation/Makefile b/Documentation/Makefile index dae3174667..dba97dc21d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -69,7 +69,9 @@ endif # # For docbook-xsl ... # -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) -# 1.69.0-1.71.1, no extra settings are needed? +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? # 1.72.0, set DOCBOOK_XSL_172. # 1.73.0-, set ASCIIDOC_NO_ROFF # @@ -97,6 +99,9 @@ endif ifdef MAN_BOLD_LITERAL XMLTO_EXTRA += -m manpage-bold-literal.xsl endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif # # Please note that there is a minor bug in asciidoc. diff --git a/Documentation/RelNotes-1.6.3.txt b/Documentation/RelNotes-1.6.3.txt index 0d8260a842..95405907b8 100644 --- a/Documentation/RelNotes-1.6.3.txt +++ b/Documentation/RelNotes-1.6.3.txt @@ -102,6 +102,11 @@ Updates since v1.6.2 * Makefile learned 'coverage' option to run the test suites with coverage tracking enabled. +* Building the manpages with docbook-xsl between 1.69.1 and 1.71.1 now + requires setting DOCBOOK_SUPPRESS_SP to work around a docbook-xsl bug. + This workaround used to be enabled by default, but causes problems + with newer versions of docbook-xsl. + Fixes since v1.6.2 ------------------ diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl index 16e2e40976..a264fa6160 100644 --- a/Documentation/manpage-base.xsl +++ b/Documentation/manpage-base.xsl @@ -32,17 +32,4 @@ br - - - - - - - - - - - diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl new file mode 100644 index 0000000000..a63c7632a8 --- /dev/null +++ b/Documentation/manpage-suppress-sp.xsl @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + +