Makefiles: add "shared.mak", move ".DELETE_ON_ERROR" to it
We have various behavior that's shared across our Makefiles, or that
really should be (e.g. via defined templates). Let's create a
top-level "shared.mak" to house those sorts of things, and start by
adding the ".DELETE_ON_ERROR" flag to it.
See my own 7b76d6bf221 (Makefile: add and use the ".DELETE_ON_ERROR"
flag, 2021-06-29) and db10fc6c09f (doc: simplify Makefile using
.DELETE_ON_ERROR, 2021-05-21) for the addition and use of the
".DELETE_ON_ERROR" flag.
I.e. this changes the behavior of existing rules in the altered
Makefiles (except "Makefile" & "Documentation/Makefile"). I'm
confident that this is safe having read the relevant rules in those
Makfiles, and as the GNU make manual notes that it isn't the default
behavior is out of an abundance of backwards compatibility
caution. From edition 0.75 of its manual, covering GNU make 4.3:
[Enabling '.DELETE_ON_ERROR' is] almost always what you want
'make' to do, but it is not historical practice; so for
compatibility, you must explicitly request it.
This doesn't introduce a bug by e.g. having this
".DELETE_ON_ERROR" flag only apply to this new shared.mak, Makefiles
have no such scoping semantics.
It does increase the danger that any Makefile without an explicit "The
default target of this Makefile is..." snippet to define the default
target as "all" could have its default rule changed if our new
shared.mak ever defines a "real" rule. In subsequent commits we'll be
careful not to do that, and such breakage would be obvious e.g. in the
case of "make -C t".
We might want to make that less fragile still (e.g. by using
".DEFAULT_GOAL" as noted in the preceding commit), but for now let's
simply include "shared.mak" without adding that boilerplate to all the
Makefiles that don't have it already. Most of those are already
exposed to that potential caveat e.g. due to including "config.mak*".
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-03 17:04:13 +01:00
|
|
|
# Import tree-wide shared Makefile behavior and libraries
|
|
|
|
|
include ../shared.mak
|
|
|
|
|
|
2013-02-01 20:41:14 +01:00
|
|
|
# Guard against environment variables
|
|
|
|
|
MAN1_TXT =
|
|
|
|
|
MAN5_TXT =
|
|
|
|
|
MAN7_TXT =
|
2021-04-09 17:02:44 +02:00
|
|
|
HOWTO_TXT =
|
2021-04-09 17:02:45 +02:00
|
|
|
DOC_DEP_TXT =
|
2014-01-27 18:04:32 +01:00
|
|
|
TECH_DOCS =
|
|
|
|
|
ARTICLES =
|
|
|
|
|
SP_ARTICLES =
|
2014-10-10 23:25:36 +02:00
|
|
|
OBSOLETE_HTML =
|
2013-02-01 20:41:14 +01:00
|
|
|
|
2019-04-18 15:16:44 +02:00
|
|
|
-include GIT-EXCLUDED-PROGRAMS
|
|
|
|
|
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN1_TXT += $(filter-out \
|
2019-04-18 15:16:44 +02:00
|
|
|
$(patsubst %,%.txt,$(EXCLUDED_PROGRAMS)) \
|
2013-02-01 20:41:14 +01:00
|
|
|
$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
|
|
|
|
|
$(wildcard git-*.txt))
|
|
|
|
|
MAN1_TXT += git.txt
|
|
|
|
|
MAN1_TXT += gitk.txt
|
|
|
|
|
MAN1_TXT += gitweb.txt
|
scalar: include in standard Git build & installation
Move 'scalar' out of 'contrib/' and into the root of the Git tree. The goal
of this change is to build 'scalar' as part of the standard Git build &
install processes.
This patch includes both the physical move of Scalar's files out of
'contrib/' ('scalar.c', 'scalar.txt', and 't9xxx-scalar.sh'), and the
changes to the build definitions in 'Makefile' and 'CMakelists.txt' to
accommodate the new program.
At a high level, Scalar is built so that:
- there is a 'scalar-objs' target (similar to those created in 029bac01a8
(Makefile: add {program,xdiff,test,git,fuzz}-objs & objects targets,
2021-02-23)) for debugging purposes.
- it appears in the root of the install directory (rather than the
gitexecdir).
- it is included in the 'bin-wrappers/' directory for use in tests.
- it receives a platform-specific executable suffix (e.g., '.exe'), if
applicable.
- 'scalar.txt' is installed as 'man1' documentation.
- the 'clean' target removes the 'scalar' executable.
Additionally, update the root level '.gitignore' file to ignore the Scalar
executable.
Signed-off-by: Victoria Dye <vdye@github.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-09-02 17:56:43 +02:00
|
|
|
MAN1_TXT += scalar.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
|
2020-08-05 03:19:04 +02:00
|
|
|
# man5 / man7 guides (note: new guides should also be added to command-list.txt)
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN5_TXT += gitattributes.txt
|
2022-08-04 18:28:34 +02:00
|
|
|
MAN5_TXT += gitformat-bundle.txt
|
2022-08-04 18:28:39 +02:00
|
|
|
MAN5_TXT += gitformat-chunk.txt
|
2022-08-04 18:28:35 +02:00
|
|
|
MAN5_TXT += gitformat-commit-graph.txt
|
2022-08-04 18:28:37 +02:00
|
|
|
MAN5_TXT += gitformat-index.txt
|
2022-08-04 18:28:39 +02:00
|
|
|
MAN5_TXT += gitformat-pack.txt
|
2022-08-04 18:28:38 +02:00
|
|
|
MAN5_TXT += gitformat-signature.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN5_TXT += githooks.txt
|
|
|
|
|
MAN5_TXT += gitignore.txt
|
2021-01-12 21:17:45 +01:00
|
|
|
MAN5_TXT += gitmailmap.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN5_TXT += gitmodules.txt
|
2022-08-04 18:28:36 +02:00
|
|
|
MAN5_TXT += gitprotocol-capabilities.txt
|
|
|
|
|
MAN5_TXT += gitprotocol-common.txt
|
2022-08-04 18:28:41 +02:00
|
|
|
MAN5_TXT += gitprotocol-http.txt
|
2022-08-04 18:28:36 +02:00
|
|
|
MAN5_TXT += gitprotocol-pack.txt
|
|
|
|
|
MAN5_TXT += gitprotocol-v2.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN5_TXT += gitrepository-layout.txt
|
|
|
|
|
MAN5_TXT += gitweb.conf.txt
|
|
|
|
|
|
|
|
|
|
MAN7_TXT += gitcli.txt
|
|
|
|
|
MAN7_TXT += gitcore-tutorial.txt
|
2011-12-10 11:31:38 +01:00
|
|
|
MAN7_TXT += gitcredentials.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN7_TXT += gitcvs-migration.txt
|
|
|
|
|
MAN7_TXT += gitdiffcore.txt
|
2014-10-10 23:25:37 +02:00
|
|
|
MAN7_TXT += giteveryday.txt
|
2020-03-30 13:55:18 +02:00
|
|
|
MAN7_TXT += gitfaq.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN7_TXT += gitglossary.txt
|
|
|
|
|
MAN7_TXT += gitnamespaces.txt
|
2019-03-25 22:41:36 +01:00
|
|
|
MAN7_TXT += gitremote-helpers.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN7_TXT += gitrevisions.txt
|
2017-06-22 23:01:49 +02:00
|
|
|
MAN7_TXT += gitsubmodules.txt
|
2013-02-01 20:41:14 +01:00
|
|
|
MAN7_TXT += gittutorial-2.txt
|
|
|
|
|
MAN7_TXT += gittutorial.txt
|
|
|
|
|
MAN7_TXT += gitworkflows.txt
|
2005-05-10 23:32:39 +02:00
|
|
|
|
2021-04-09 17:02:44 +02:00
|
|
|
HOWTO_TXT += $(wildcard howto/*.txt)
|
|
|
|
|
|
2021-04-09 17:02:45 +02:00
|
|
|
DOC_DEP_TXT += $(wildcard *.txt)
|
|
|
|
|
DOC_DEP_TXT += $(wildcard config/*.txt)
|
2022-09-07 10:26:57 +02:00
|
|
|
DOC_DEP_TXT += $(wildcard includes/*.txt)
|
2021-04-09 17:02:45 +02:00
|
|
|
|
2019-01-07 20:21:12 +01:00
|
|
|
ifdef MAN_FILTER
|
|
|
|
|
MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
|
|
|
|
|
else
|
2007-12-10 10:15:57 +01:00
|
|
|
MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
|
2019-01-07 20:21:12 +01:00
|
|
|
MAN_FILTER = $(MAN_TXT)
|
|
|
|
|
endif
|
|
|
|
|
|
2013-06-16 19:13:00 +02:00
|
|
|
MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
|
|
|
|
|
MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
|
2017-12-09 23:07:57 +01:00
|
|
|
GIT_MAN_REF = master
|
2007-12-10 10:15:57 +01:00
|
|
|
|
2014-10-10 23:25:37 +02:00
|
|
|
OBSOLETE_HTML += everyday.html
|
2014-10-10 23:25:36 +02:00
|
|
|
OBSOLETE_HTML += git-remote-helpers.html
|
2005-08-30 22:51:01 +02:00
|
|
|
|
2014-01-27 18:04:32 +01:00
|
|
|
ARTICLES += howto-index
|
2006-03-05 10:36:33 +01:00
|
|
|
ARTICLES += git-tools
|
2009-11-08 16:09:47 +01:00
|
|
|
ARTICLES += git-bisect-lk2009
|
2005-08-30 22:51:01 +02:00
|
|
|
# with their own formatting rules.
|
2014-01-27 18:04:32 +01:00
|
|
|
SP_ARTICLES += user-manual
|
2012-12-21 19:05:28 +01:00
|
|
|
SP_ARTICLES += howto/new-command
|
2012-01-17 23:52:24 +01:00
|
|
|
SP_ARTICLES += howto/revert-branch-rebase
|
|
|
|
|
SP_ARTICLES += howto/using-merge-subtree
|
|
|
|
|
SP_ARTICLES += howto/using-signed-tag-in-pull-request
|
2012-10-23 19:58:04 +02:00
|
|
|
SP_ARTICLES += howto/use-git-daemon
|
|
|
|
|
SP_ARTICLES += howto/update-hook-example
|
|
|
|
|
SP_ARTICLES += howto/setup-git-server-over-http
|
|
|
|
|
SP_ARTICLES += howto/separating-topic-branches
|
|
|
|
|
SP_ARTICLES += howto/revert-a-faulty-merge
|
|
|
|
|
SP_ARTICLES += howto/recover-corrupted-blob-object
|
2013-10-25 09:55:02 +02:00
|
|
|
SP_ARTICLES += howto/recover-corrupted-object-harder
|
2012-10-23 19:58:04 +02:00
|
|
|
SP_ARTICLES += howto/rebuild-from-update-hook
|
|
|
|
|
SP_ARTICLES += howto/rebase-from-internal-branch
|
2014-05-09 08:08:41 +02:00
|
|
|
SP_ARTICLES += howto/keep-canonical-history-correct
|
2012-10-23 19:58:04 +02:00
|
|
|
SP_ARTICLES += howto/maintain-git
|
2021-03-26 23:12:46 +01:00
|
|
|
SP_ARTICLES += howto/coordinate-embargoed-releases
|
2007-11-25 08:48:04 +01:00
|
|
|
API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
|
|
|
|
|
SP_ARTICLES += $(API_DOCS)
|
2012-10-23 19:58:04 +02:00
|
|
|
|
2022-09-19 21:12:46 +02:00
|
|
|
TECH_DOCS += ReviewingGuidelines
|
2019-05-17 21:07:02 +02:00
|
|
|
TECH_DOCS += MyFirstContribution
|
2019-10-12 01:55:54 +02:00
|
|
|
TECH_DOCS += MyFirstObjectWalk
|
2017-11-12 23:07:18 +01:00
|
|
|
TECH_DOCS += SubmittingPatches
|
2022-04-21 10:45:15 +02:00
|
|
|
TECH_DOCS += ToolsForGit
|
2022-06-16 07:03:52 +02:00
|
|
|
TECH_DOCS += technical/bitmap-format
|
2022-08-09 15:12:40 +02:00
|
|
|
TECH_DOCS += technical/bundle-uri
|
2017-09-28 06:43:21 +02:00
|
|
|
TECH_DOCS += technical/hash-function-transition
|
2018-01-25 19:53:24 +01:00
|
|
|
TECH_DOCS += technical/long-running-process-protocol
|
2018-11-20 19:04:54 +01:00
|
|
|
TECH_DOCS += technical/multi-pack-index
|
2012-10-23 19:58:04 +02:00
|
|
|
TECH_DOCS += technical/pack-heuristics
|
2021-04-19 21:53:35 +02:00
|
|
|
TECH_DOCS += technical/parallel-checkout
|
2018-08-15 00:28:46 +02:00
|
|
|
TECH_DOCS += technical/partial-clone
|
2012-10-23 19:58:04 +02:00
|
|
|
TECH_DOCS += technical/racy-git
|
2020-05-20 19:36:10 +02:00
|
|
|
TECH_DOCS += technical/reftable
|
2022-09-02 17:56:50 +02:00
|
|
|
TECH_DOCS += technical/scalar
|
2012-10-23 19:58:04 +02:00
|
|
|
TECH_DOCS += technical/send-pack-pipeline
|
|
|
|
|
TECH_DOCS += technical/shallow
|
|
|
|
|
TECH_DOCS += technical/trivial-merge
|
|
|
|
|
SP_ARTICLES += $(TECH_DOCS)
|
2007-11-25 08:48:04 +01:00
|
|
|
SP_ARTICLES += technical/api-index
|
2005-08-30 22:51:01 +02:00
|
|
|
|
2019-01-07 20:21:12 +01:00
|
|
|
ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
|
|
|
|
|
HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
|
|
|
|
|
DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML))
|
2005-08-30 08:09:22 +02:00
|
|
|
|
2019-01-07 20:21:12 +01:00
|
|
|
DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
|
|
|
|
|
DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
|
|
|
|
|
DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
|
2005-05-22 19:44:15 +02:00
|
|
|
|
2013-06-16 19:13:00 +02:00
|
|
|
prefix ?= $(HOME)
|
|
|
|
|
bindir ?= $(prefix)/bin
|
|
|
|
|
htmldir ?= $(prefix)/share/doc/git-doc
|
2013-06-16 19:13:01 +02:00
|
|
|
infodir ?= $(prefix)/share/info
|
2013-06-16 19:13:00 +02:00
|
|
|
pdfdir ?= $(prefix)/share/doc/git-doc
|
|
|
|
|
mandir ?= $(prefix)/share/man
|
|
|
|
|
man1dir = $(mandir)/man1
|
|
|
|
|
man5dir = $(mandir)/man5
|
|
|
|
|
man7dir = $(mandir)/man7
|
|
|
|
|
# DESTDIR =
|
2005-07-15 03:21:57 +02:00
|
|
|
|
2023-04-13 09:47:22 +02:00
|
|
|
GIT_DATE := $(shell git show --quiet --pretty='%as')
|
|
|
|
|
|
2012-09-19 19:06:37 +02:00
|
|
|
ASCIIDOC = asciidoc
|
2007-02-14 00:15:05 +01:00
|
|
|
ASCIIDOC_EXTRA =
|
2014-10-12 01:37:35 +02:00
|
|
|
ASCIIDOC_HTML = xhtml11
|
|
|
|
|
ASCIIDOC_DOCBOOK = docbook
|
|
|
|
|
ASCIIDOC_CONF = -f asciidoc.conf
|
2014-10-27 01:13:42 +01:00
|
|
|
ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
|
2023-04-13 09:47:22 +02:00
|
|
|
-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)' \
|
|
|
|
|
-arevdate='$(GIT_DATE)'
|
2021-05-22 00:29:38 +02:00
|
|
|
ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
|
2014-10-27 01:13:42 +01:00
|
|
|
TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
|
|
|
|
|
TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
|
2009-03-27 07:43:58 +01:00
|
|
|
MANPAGE_XSL = manpage-normal.xsl
|
2012-09-19 19:06:37 +02:00
|
|
|
XMLTO = xmlto
|
2009-03-27 07:44:05 +01:00
|
|
|
XMLTO_EXTRA =
|
2013-06-16 19:13:00 +02:00
|
|
|
INSTALL ?= install
|
2007-07-14 19:51:44 +02:00
|
|
|
RM ?= rm -f
|
2011-11-08 19:17:40 +01:00
|
|
|
MAN_REPO = ../../git-manpages
|
|
|
|
|
HTML_REPO = ../../git-htmldocs
|
2005-07-15 03:21:57 +02:00
|
|
|
|
2013-06-16 19:13:00 +02:00
|
|
|
MAKEINFO = makeinfo
|
|
|
|
|
INSTALL_INFO = install-info
|
|
|
|
|
DOCBOOK2X_TEXI = docbook2x-texi
|
|
|
|
|
DBLATEX = dblatex
|
2013-10-03 21:17:32 +02:00
|
|
|
ASCIIDOC_DBLATEX_DIR = /etc/asciidoc/dblatex
|
2017-01-22 03:41:55 +01:00
|
|
|
DBLATEX_COMMON = -p $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.xsl -s $(ASCIIDOC_DBLATEX_DIR)/asciidoc-dblatex.sty
|
2007-12-01 03:36:34 +01:00
|
|
|
ifndef PERL_PATH
|
|
|
|
|
PERL_PATH = /usr/bin/perl
|
|
|
|
|
endif
|
2007-08-06 12:22:57 +02:00
|
|
|
|
2006-09-01 00:31:08 +02:00
|
|
|
-include ../config.mak.autogen
|
2007-02-28 21:57:42 +01:00
|
|
|
-include ../config.mak
|
2006-09-01 00:31:08 +02:00
|
|
|
|
2016-05-31 18:20:33 +02:00
|
|
|
ifndef NO_MAN_BOLD_LITERAL
|
2009-03-27 07:44:05 +01:00
|
|
|
XMLTO_EXTRA += -m manpage-bold-literal.xsl
|
|
|
|
|
endif
|
2007-11-14 10:38:46 +01:00
|
|
|
|
2009-12-03 09:06:52 +01:00
|
|
|
# Newer DocBook stylesheet emits warning cruft in the output when
|
2009-12-04 18:53:21 +01:00
|
|
|
# this is not set, and if set it shows an absolute link. Older
|
|
|
|
|
# stylesheets simply ignore this parameter.
|
2009-12-03 20:12:32 +01:00
|
|
|
#
|
2009-12-04 18:53:21 +01:00
|
|
|
# Distros may want to use MAN_BASE_URL=file:///path/to/git/docs/
|
|
|
|
|
# or similar.
|
|
|
|
|
ifndef MAN_BASE_URL
|
|
|
|
|
MAN_BASE_URL = file://$(htmldir)/
|
2009-12-03 20:12:32 +01:00
|
|
|
endif
|
2023-03-22 01:08:15 +01:00
|
|
|
XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)'
|
2009-12-03 03:45:09 +01:00
|
|
|
|
2017-01-22 03:41:56 +01:00
|
|
|
ifdef USE_ASCIIDOCTOR
|
|
|
|
|
ASCIIDOC = asciidoctor
|
|
|
|
|
ASCIIDOC_CONF =
|
|
|
|
|
ASCIIDOC_HTML = xhtml5
|
Documentation: fix build with Asciidoctor 2
Our documentation toolchain has traditionally been built around DocBook
4.5. This version of DocBook is the last DTD-based version of DocBook.
In 2009, DocBook 5 was introduced using namespaces and its syntax is
expressed in RELAX NG, which is more expressive and allows a wider
variety of syntax forms.
Asciidoctor, one of the alternatives for building our documentation,
moved support for DocBook 4.5 out of core in its recent 2.0 release and
now only supports DocBook 5 in the main release. The DocBoook 4.5
converter is still available as a separate component, but this is not
available in most distro packages. This would not be a problem but for
the fact that we use xmlto, which is still stuck in the DocBook 4.5 era.
xmlto performs DTD validation as part of the build process. This is not
problematic for DocBook 4.5, which has a valid DTD, but it clearly
cannot work for DocBook 5, since no DTD can adequately express its full
syntax. In addition, even if xmlto did support RELAX NG validation,
that wouldn't be sufficient because it uses the libxml2-based xmllint to
do so, which has known problems with validating interleaves in RELAX NG.
Fortunately, there's an easy way forward: ask Asciidoctor to use its
DocBook 5 backend and tell xmlto to skip validation. Asciidoctor has
supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported
skipping validation for probably longer than that.
We also need to teach xmlto how to use the namespaced DocBook XSLT
stylesheets instead of the non-namespaced ones it usually uses.
Normally these stylesheets are interchangeable, but the non-namespaced
ones have a bug that causes them not to strip whitespace automatically
from certain elements when namespaces are in use. This results in
additional whitespace at the beginning of list elements, which is
jarring and unsightly.
We can do this by passing a custom stylesheet with the -x option that
simply imports the namespaced stylesheets via a URL. Any system with
support for XML catalogs will automatically look this URL up and
reference a local copy instead without us having to know where this
local copy is located. We know that anyone using xmlto will already
have catalogs set up properly since the DocBook 4.5 DTD used during
validation is also looked up via catalogs. All major Linux
distributions distribute the necessary stylesheets and have built-in
catalog support, and Homebrew does as well, albeit with a requirement to
set an environment variable to enable catalog support.
On the off chance that someone lacks support for catalogs, it is
possible for xmlto (via xmllint) to download the stylesheets from the
URLs in question, although this will likely perform poorly enough to
attract attention. People still have the option of using the prebuilt
documentation that we ship, so happily this should not be an impediment.
Finally, we need to filter out some messages from other stylesheets that
occur when invoking dblatex in the CI job. This tool strips namespaces
much like the unnamespaced DocBook stylesheets and prints similar
messages. If we permit these messages to be printed to standard error,
our documentation CI job will fail because we check standard error for
unexpected output. Due to dblatex's reliance on Python 2, we may need
to revisit its use in the future, in which case this problem may go
away, but this can be delayed until a future patch.
The final message we filter is due to libxslt on modern Debian and
Ubuntu. The patch which they use to implement reproducible ID
generation also prints messages about the ID generation. While this
doesn't affect our current CI images since they use Ubuntu 16.04 which
lacks this patch, if we upgrade to Ubuntu 18.04 or a modern Debian,
these messages will appear and, like the above messages, cause a CI
failure.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-16 00:43:32 +02:00
|
|
|
ASCIIDOC_DOCBOOK = docbook5
|
2018-05-06 22:42:25 +02:00
|
|
|
ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
|
2017-01-26 01:13:44 +01:00
|
|
|
ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
|
2017-01-22 03:41:56 +01:00
|
|
|
ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
|
2021-05-22 00:29:38 +02:00
|
|
|
ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
|
2017-01-22 03:41:56 +01:00
|
|
|
DBLATEX_COMMON =
|
Documentation: fix build with Asciidoctor 2
Our documentation toolchain has traditionally been built around DocBook
4.5. This version of DocBook is the last DTD-based version of DocBook.
In 2009, DocBook 5 was introduced using namespaces and its syntax is
expressed in RELAX NG, which is more expressive and allows a wider
variety of syntax forms.
Asciidoctor, one of the alternatives for building our documentation,
moved support for DocBook 4.5 out of core in its recent 2.0 release and
now only supports DocBook 5 in the main release. The DocBoook 4.5
converter is still available as a separate component, but this is not
available in most distro packages. This would not be a problem but for
the fact that we use xmlto, which is still stuck in the DocBook 4.5 era.
xmlto performs DTD validation as part of the build process. This is not
problematic for DocBook 4.5, which has a valid DTD, but it clearly
cannot work for DocBook 5, since no DTD can adequately express its full
syntax. In addition, even if xmlto did support RELAX NG validation,
that wouldn't be sufficient because it uses the libxml2-based xmllint to
do so, which has known problems with validating interleaves in RELAX NG.
Fortunately, there's an easy way forward: ask Asciidoctor to use its
DocBook 5 backend and tell xmlto to skip validation. Asciidoctor has
supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported
skipping validation for probably longer than that.
We also need to teach xmlto how to use the namespaced DocBook XSLT
stylesheets instead of the non-namespaced ones it usually uses.
Normally these stylesheets are interchangeable, but the non-namespaced
ones have a bug that causes them not to strip whitespace automatically
from certain elements when namespaces are in use. This results in
additional whitespace at the beginning of list elements, which is
jarring and unsightly.
We can do this by passing a custom stylesheet with the -x option that
simply imports the namespaced stylesheets via a URL. Any system with
support for XML catalogs will automatically look this URL up and
reference a local copy instead without us having to know where this
local copy is located. We know that anyone using xmlto will already
have catalogs set up properly since the DocBook 4.5 DTD used during
validation is also looked up via catalogs. All major Linux
distributions distribute the necessary stylesheets and have built-in
catalog support, and Homebrew does as well, albeit with a requirement to
set an environment variable to enable catalog support.
On the off chance that someone lacks support for catalogs, it is
possible for xmlto (via xmllint) to download the stylesheets from the
URLs in question, although this will likely perform poorly enough to
attract attention. People still have the option of using the prebuilt
documentation that we ship, so happily this should not be an impediment.
Finally, we need to filter out some messages from other stylesheets that
occur when invoking dblatex in the CI job. This tool strips namespaces
much like the unnamespaced DocBook stylesheets and prints similar
messages. If we permit these messages to be printed to standard error,
our documentation CI job will fail because we check standard error for
unexpected output. Due to dblatex's reliance on Python 2, we may need
to revisit its use in the future, in which case this problem may go
away, but this can be delayed until a future patch.
The final message we filter is due to libxslt on modern Debian and
Ubuntu. The patch which they use to implement reproducible ID
generation also prints messages about the ID generation. While this
doesn't affect our current CI images since they use Ubuntu 16.04 which
lacks this patch, if we upgrade to Ubuntu 18.04 or a modern Debian,
these messages will appear and, like the above messages, cause a CI
failure.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-16 00:43:32 +02:00
|
|
|
XMLTO_EXTRA += --skip-validation
|
|
|
|
|
XMLTO_EXTRA += -x manpage.xsl
|
2017-01-22 03:41:56 +01:00
|
|
|
endif
|
|
|
|
|
|
2009-03-22 14:20:44 +01:00
|
|
|
SHELL_PATH ?= $(SHELL)
|
|
|
|
|
# Shell quote;
|
|
|
|
|
SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH))
|
|
|
|
|
|
2012-03-31 10:44:53 +02:00
|
|
|
ifdef DEFAULT_PAGER
|
|
|
|
|
DEFAULT_PAGER_SQ = $(subst ','\'',$(DEFAULT_PAGER))
|
|
|
|
|
ASCIIDOC_EXTRA += -a 'git-default-pager=$(DEFAULT_PAGER_SQ)'
|
|
|
|
|
endif
|
|
|
|
|
|
|
|
|
|
ifdef DEFAULT_EDITOR
|
|
|
|
|
DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR))
|
|
|
|
|
ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'
|
|
|
|
|
endif
|
|
|
|
|
|
2005-05-22 19:44:15 +02:00
|
|
|
all: html man
|
2005-05-10 23:32:39 +02:00
|
|
|
|
|
|
|
|
html: $(DOC_HTML)
|
|
|
|
|
|
2007-04-20 05:47:04 +02:00
|
|
|
man: man1 man5 man7
|
2005-05-22 19:44:15 +02:00
|
|
|
man1: $(DOC_MAN1)
|
2007-04-20 05:47:04 +02:00
|
|
|
man5: $(DOC_MAN5)
|
2005-05-22 19:44:15 +02:00
|
|
|
man7: $(DOC_MAN7)
|
2005-05-10 23:32:39 +02:00
|
|
|
|
2007-12-10 10:15:57 +01:00
|
|
|
info: git.info gitman.info
|
2007-08-06 12:22:57 +02:00
|
|
|
|
2008-12-10 23:44:50 +01:00
|
|
|
pdf: user-manual.pdf
|
|
|
|
|
|
2008-11-02 18:53:03 +01:00
|
|
|
install: install-man
|
|
|
|
|
|
|
|
|
|
install-man: man
|
2007-12-01 18:05:40 +01:00
|
|
|
$(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
|
|
|
|
|
$(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
|
|
|
|
|
$(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
|
|
|
|
|
$(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(man1dir)
|
|
|
|
|
$(INSTALL) -m 644 $(DOC_MAN5) $(DESTDIR)$(man5dir)
|
|
|
|
|
$(INSTALL) -m 644 $(DOC_MAN7) $(DESTDIR)$(man7dir)
|
2005-07-15 03:21:57 +02:00
|
|
|
|
2007-08-06 12:22:57 +02:00
|
|
|
install-info: info
|
2007-12-01 18:05:40 +01:00
|
|
|
$(INSTALL) -d -m 755 $(DESTDIR)$(infodir)
|
2007-12-10 10:15:57 +01:00
|
|
|
$(INSTALL) -m 644 git.info gitman.info $(DESTDIR)$(infodir)
|
2007-08-06 12:22:57 +02:00
|
|
|
if test -r $(DESTDIR)$(infodir)/dir; then \
|
|
|
|
|
$(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) git.info ;\
|
2007-12-10 10:15:57 +01:00
|
|
|
$(INSTALL_INFO) --info-dir=$(DESTDIR)$(infodir) gitman.info ;\
|
2007-08-06 12:22:57 +02:00
|
|
|
else \
|
|
|
|
|
echo "No directory found in $(DESTDIR)$(infodir)" >&2 ; \
|
|
|
|
|
fi
|
2005-11-04 09:06:20 +01:00
|
|
|
|
2008-12-10 23:44:50 +01:00
|
|
|
install-pdf: pdf
|
|
|
|
|
$(INSTALL) -d -m 755 $(DESTDIR)$(pdfdir)
|
|
|
|
|
$(INSTALL) -m 644 user-manual.pdf $(DESTDIR)$(pdfdir)
|
|
|
|
|
|
2007-12-02 06:07:55 +01:00
|
|
|
install-html: html
|
2009-03-22 14:20:44 +01:00
|
|
|
'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(DESTDIR)$(htmldir)
|
2007-12-02 06:07:55 +01:00
|
|
|
|
2010-01-06 09:06:58 +01:00
|
|
|
../GIT-VERSION-FILE: FORCE
|
2009-03-27 07:49:38 +01:00
|
|
|
$(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE
|
2007-03-25 13:56:49 +02:00
|
|
|
|
2021-10-15 14:39:13 +02:00
|
|
|
ifneq ($(filter-out lint-docs clean,$(MAKECMDGOALS)),)
|
2007-03-25 13:56:49 +02:00
|
|
|
-include ../GIT-VERSION-FILE
|
Documentation/Makefile: conditionally include ../GIT-VERSION-FILE
The 'clean' target is still noticeably slow on cygwin, despite the
substantial improvement made by the previous patch. For example, the
second invocation of 'make clean' below:
$ make clean >/dev/null 2>&1
$ make clean
...
make[1]: Entering directory '/home/ramsay/git/Documentation'
make[2]: Entering directory '/home/ramsay/git'
make[2]: 'GIT-VERSION-FILE' is up to date.
make[2]: Leaving directory '/home/ramsay/git'
...
$
has been timed at 12.364s on my laptop (an old core i5-4200M @ 2.50GHz,
8GB RAM, 1TB HDD).
Notice that the 'clean' target is making a nested call to the parent
Makefile to ensure that the GIT-VERSION-FILE is up-to-date (prior to
the previous patch, there would have been _two_ such invocations).
This is to ensure that the $(GIT_VERSION) make variable is set, once
that file had been included. However, the 'clean' target does not use
the $(GIT_VERSION) variable, directly or indirectly, so it does not
have any affect on what the target removes. Therefore, the time spent
on ensuring an up to date GIT-VERSION-FILE is wasted effort.
In order to eliminate such wasted effort, use the value of the internal
$(MAKECMDGOALS) variable to only '-include ../GIT-VERSION-FILE' when the
target is not 'clean'. (This drops the time down to 10.361s, on my laptop,
giving an improvement of 16.20%).
Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-08 23:33:05 +01:00
|
|
|
endif
|
2007-03-25 13:56:49 +02:00
|
|
|
|
2005-11-07 06:30:56 +01:00
|
|
|
#
|
|
|
|
|
# Determine "include::" file references in asciidoc files.
|
|
|
|
|
#
|
2013-01-28 01:52:26 +01:00
|
|
|
docdep_prereqs = \
|
|
|
|
|
mergetools-list.made $(mergetools_txt) \
|
|
|
|
|
cmd-list.made $(cmds_txt)
|
|
|
|
|
|
2021-04-09 17:02:45 +02:00
|
|
|
doc.dep : $(docdep_prereqs) $(DOC_DEP_TXT) build-docdep.perl
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_GEN)$(PERL_PATH) ./build-docdep.perl >$@ $(QUIET_STDERR)
|
2005-11-07 06:30:56 +01:00
|
|
|
|
Documentation/Makefile: conditionally include doc.dep
The 'clean' target is noticeably slow on cygwin, even for a 'do-nothing'
invocation of 'make clean'. For example, the second 'make clean' below:
$ make clean >/dev/null 2>&1
$ make clean
GIT_VERSION = 2.29.0
...
make[1]: Entering directory '/home/ramsay/git/Documentation'
GEN mergetools-list.made
GEN cmd-list.made
GEN doc.dep
...
$
has been timed at 23.339s, using git v2.29.0, on my laptop (an old core
i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD).
Notice that, since the 'doc.dep' file does not exist, make takes the
time (about 8s) to generate several files in order to create the doc.dep
include file. (If an 'include' file is missing, but a target for the
said file is present in the Makefile, make will execute that target
and, if that file now exists, throw away all its internal data and
re-read and re-parse the Makefile). Having spent the time to include
the 'doc.dep' file, the 'clean' target immediately deletes those files.
The document dependencies specified in the 'doc.dep' include file,
expressed as make targets and prerequisites, do not affect what the
'clean' target removes. Therefore, the time spent in generating the
dependencies is completely wasted effort.
In order to eliminate such wasted effort, use the value of the internal
$(MAKECMDGOALS) variable to only '-include doc.dep' when the target is
not 'clean'. (This drops the time down to 12.364s, on my laptop, giving
an improvement of 47.02%).
Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-08 23:31:44 +01:00
|
|
|
ifneq ($(MAKECMDGOALS),clean)
|
2005-11-08 03:21:51 +01:00
|
|
|
-include doc.dep
|
Documentation/Makefile: conditionally include doc.dep
The 'clean' target is noticeably slow on cygwin, even for a 'do-nothing'
invocation of 'make clean'. For example, the second 'make clean' below:
$ make clean >/dev/null 2>&1
$ make clean
GIT_VERSION = 2.29.0
...
make[1]: Entering directory '/home/ramsay/git/Documentation'
GEN mergetools-list.made
GEN cmd-list.made
GEN doc.dep
...
$
has been timed at 23.339s, using git v2.29.0, on my laptop (an old core
i5-4200M @ 2.50GHz, 8GB RAM, 1TB HDD).
Notice that, since the 'doc.dep' file does not exist, make takes the
time (about 8s) to generate several files in order to create the doc.dep
include file. (If an 'include' file is missing, but a target for the
said file is present in the Makefile, make will execute that target
and, if that file now exists, throw away all its internal data and
re-read and re-parse the Makefile). Having spent the time to include
the 'doc.dep' file, the 'clean' target immediately deletes those files.
The document dependencies specified in the 'doc.dep' include file,
expressed as make targets and prerequisites, do not affect what the
'clean' target removes. Therefore, the time spent in generating the
dependencies is completely wasted effort.
In order to eliminate such wasted effort, use the value of the internal
$(MAKECMDGOALS) variable to only '-include doc.dep' when the target is
not 'clean'. (This drops the time down to 12.364s, on my laptop, giving
an improvement of 47.02%).
Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-12-08 23:31:44 +01:00
|
|
|
endif
|
2005-11-04 09:06:20 +01:00
|
|
|
|
2007-01-19 01:02:13 +01:00
|
|
|
cmds_txt = cmds-ancillaryinterrogators.txt \
|
|
|
|
|
cmds-ancillarymanipulators.txt \
|
|
|
|
|
cmds-mainporcelain.txt \
|
|
|
|
|
cmds-plumbinginterrogators.txt \
|
|
|
|
|
cmds-plumbingmanipulators.txt \
|
2007-01-19 07:32:38 +01:00
|
|
|
cmds-synchingrepositories.txt \
|
|
|
|
|
cmds-synchelpers.txt \
|
2020-08-05 03:19:07 +02:00
|
|
|
cmds-guide.txt \
|
2022-08-04 18:28:34 +02:00
|
|
|
cmds-developerinterfaces.txt \
|
2022-08-04 18:28:33 +02:00
|
|
|
cmds-userinterfaces.txt \
|
2007-01-19 07:32:38 +01:00
|
|
|
cmds-purehelpers.txt \
|
|
|
|
|
cmds-foreignscminterface.txt
|
2007-01-19 01:02:13 +01:00
|
|
|
|
2007-04-06 07:17:20 +02:00
|
|
|
$(cmds_txt): cmd-list.made
|
|
|
|
|
|
2007-12-02 08:39:19 +01:00
|
|
|
cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
|
2021-05-22 00:29:39 +02:00
|
|
|
$(QUIET_GEN)$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \
|
2007-04-06 07:17:20 +02:00
|
|
|
date >$@
|
2005-05-10 23:32:39 +02:00
|
|
|
|
2013-01-28 01:52:26 +01:00
|
|
|
mergetools_txt = mergetools-diff.txt mergetools-merge.txt
|
|
|
|
|
|
|
|
|
|
$(mergetools_txt): mergetools-list.made
|
|
|
|
|
|
|
|
|
|
mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
|
2021-05-22 00:29:39 +02:00
|
|
|
$(QUIET_GEN) \
|
vimdiff: add tool documentation
Running 'git {merge,diff}tool --tool-help' now also prints usage
information about the vimdiff tool (and its variants) instead of just
its name.
Two new functions ('diff_cmd_help()' and 'merge_cmd_help()') have been
added to the set of functions that each merge tool (ie. scripts found
inside "mergetools/") can overwrite to provided tool specific
information.
Right now, only 'mergetools/vimdiff' implements these functions, but
other tools are encouraged to do so in the future, specially if they
take configuration options not explained anywhere else (as it is the
case with the 'vimdiff' tool and the new 'layout' option)
Note that the function 'show_tool_names', used in the implementation of
'git mergetool --tool-help', is also used in Documentation/Makefile to
generate the list of allowed values for the configuration variables
'{diff,merge}.{gui,}tool'. Adjust the rule so its output is an Asciidoc
"description list" instead of a plain list, with the tool name as the
item and the newly added tool description as the description.
In addition, a section has been added to
"Documentation/git-mergetool.txt" to explain the new "layout"
configuration option with examples.
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Fernando Ramos <greenfoo@u92.eu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-30 21:19:08 +02:00
|
|
|
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=diff && \
|
2013-01-28 01:52:26 +01:00
|
|
|
. ../git-mergetool--lib.sh && \
|
vimdiff: add tool documentation
Running 'git {merge,diff}tool --tool-help' now also prints usage
information about the vimdiff tool (and its variants) instead of just
its name.
Two new functions ('diff_cmd_help()' and 'merge_cmd_help()') have been
added to the set of functions that each merge tool (ie. scripts found
inside "mergetools/") can overwrite to provided tool specific
information.
Right now, only 'mergetools/vimdiff' implements these functions, but
other tools are encouraged to do so in the future, specially if they
take configuration options not explained anywhere else (as it is the
case with the 'vimdiff' tool and the new 'layout' option)
Note that the function 'show_tool_names', used in the implementation of
'git mergetool --tool-help', is also used in Documentation/Makefile to
generate the list of allowed values for the configuration variables
'{diff,merge}.{gui,}tool'. Adjust the rule so its output is an Asciidoc
"description list" instead of a plain list, with the tool name as the
item and the newly added tool description as the description.
In addition, a section has been added to
"Documentation/git-mergetool.txt" to explain the new "layout"
configuration option with examples.
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Fernando Ramos <greenfoo@u92.eu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-30 21:19:08 +02:00
|
|
|
show_tool_names can_diff' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-diff.txt && \
|
|
|
|
|
$(SHELL_PATH) -c 'MERGE_TOOLS_DIR=../mergetools && TOOL_MODE=merge && \
|
2013-01-28 01:52:26 +01:00
|
|
|
. ../git-mergetool--lib.sh && \
|
vimdiff: add tool documentation
Running 'git {merge,diff}tool --tool-help' now also prints usage
information about the vimdiff tool (and its variants) instead of just
its name.
Two new functions ('diff_cmd_help()' and 'merge_cmd_help()') have been
added to the set of functions that each merge tool (ie. scripts found
inside "mergetools/") can overwrite to provided tool specific
information.
Right now, only 'mergetools/vimdiff' implements these functions, but
other tools are encouraged to do so in the future, specially if they
take configuration options not explained anywhere else (as it is the
case with the 'vimdiff' tool and the new 'layout' option)
Note that the function 'show_tool_names', used in the implementation of
'git mergetool --tool-help', is also used in Documentation/Makefile to
generate the list of allowed values for the configuration variables
'{diff,merge}.{gui,}tool'. Adjust the rule so its output is an Asciidoc
"description list" instead of a plain list, with the tool name as the
item and the newly added tool description as the description.
In addition, a section has been added to
"Documentation/git-mergetool.txt" to explain the new "layout"
configuration option with examples.
Helped-by: Philippe Blain <levraiphilippeblain@gmail.com>
Signed-off-by: Fernando Ramos <greenfoo@u92.eu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-30 21:19:08 +02:00
|
|
|
show_tool_names can_merge' | sed -e "s/\([a-z0-9]*\)/\`\1\`;;/" >mergetools-merge.txt && \
|
2013-01-28 01:52:26 +01:00
|
|
|
date >$@
|
|
|
|
|
|
2019-03-17 19:36:00 +01:00
|
|
|
TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
|
|
|
|
|
|
|
|
|
|
GIT-ASCIIDOCFLAGS: FORCE
|
|
|
|
|
@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
|
|
|
|
|
if test x"$$FLAGS" != x"`cat GIT-ASCIIDOCFLAGS 2>/dev/null`" ; then \
|
|
|
|
|
echo >&2 " * new asciidoc flags"; \
|
|
|
|
|
echo "$$FLAGS" >GIT-ASCIIDOCFLAGS; \
|
|
|
|
|
fi
|
|
|
|
|
|
2005-05-10 23:32:39 +02:00
|
|
|
clean:
|
2021-10-15 14:39:14 +02:00
|
|
|
$(RM) -rf .build/
|
2008-01-06 04:09:09 +01:00
|
|
|
$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
|
2009-03-27 07:49:39 +01:00
|
|
|
$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
|
2011-08-08 10:33:05 +02:00
|
|
|
$(RM) *.pdf
|
2007-11-25 08:48:04 +01:00
|
|
|
$(RM) howto-index.txt howto/*.html doc.dep
|
2012-10-23 19:58:04 +02:00
|
|
|
$(RM) technical/*.html technical/api-index.txt
|
2017-11-12 23:07:18 +01:00
|
|
|
$(RM) SubmittingPatches.txt
|
2013-01-28 01:52:26 +01:00
|
|
|
$(RM) $(cmds_txt) $(mergetools_txt) *.made
|
2019-03-17 19:36:00 +01:00
|
|
|
$(RM) GIT-ASCIIDOCFLAGS
|
2005-05-10 23:32:39 +02:00
|
|
|
|
2021-05-22 00:29:37 +02:00
|
|
|
$(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -d manpage -o $@ $<
|
2005-05-10 23:32:39 +02:00
|
|
|
|
2021-05-22 00:29:37 +02:00
|
|
|
$(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
|
2013-01-31 22:59:50 +01:00
|
|
|
|
2023-03-22 01:08:15 +01:00
|
|
|
manpage-prereqs := $(wildcard manpage*.xsl)
|
2022-11-27 23:42:51 +01:00
|
|
|
manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
|
|
|
|
|
|
|
|
|
|
%.1 : %.xml $(manpage-prereqs)
|
|
|
|
|
$(manpage-cmd)
|
|
|
|
|
%.5 : %.xml $(manpage-prereqs)
|
|
|
|
|
$(manpage-cmd)
|
|
|
|
|
%.7 : %.xml $(manpage-prereqs)
|
|
|
|
|
$(manpage-cmd)
|
2005-05-10 23:32:39 +02:00
|
|
|
|
2021-05-22 00:29:37 +02:00
|
|
|
%.xml : %.txt $(ASCIIDOC_DEPS)
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
|
2005-08-15 02:24:36 +02:00
|
|
|
|
2019-04-16 12:28:09 +02:00
|
|
|
user-manual.xml: user-manual.txt user-manual.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $<
|
2007-01-08 01:23:49 +01:00
|
|
|
|
2007-11-25 08:48:04 +01:00
|
|
|
technical/api-index.txt: technical/api-index-skel.txt \
|
|
|
|
|
technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
|
2009-03-22 14:20:44 +01:00
|
|
|
$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
|
2007-11-25 08:48:04 +01:00
|
|
|
|
2012-06-07 23:03:23 +02:00
|
|
|
technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
|
2019-03-17 19:36:00 +01:00
|
|
|
$(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \
|
|
|
|
|
asciidoc.conf GIT-ASCIIDOCFLAGS
|
2014-10-27 01:13:42 +01:00
|
|
|
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
|
2007-11-25 08:48:04 +01:00
|
|
|
|
2017-11-12 23:07:18 +01:00
|
|
|
SubmittingPatches.txt: SubmittingPatches
|
|
|
|
|
$(QUIET_GEN) cp $< $@
|
|
|
|
|
|
2007-07-24 09:46:35 +02:00
|
|
|
XSLT = docbook.xsl
|
2020-12-01 10:50:37 +01:00
|
|
|
XSLTOPTS =
|
|
|
|
|
XSLTOPTS += --xinclude
|
|
|
|
|
XSLTOPTS += --stringparam html.stylesheet docbook-xsl.css
|
|
|
|
|
XSLTOPTS += --param generate.consistent.ids 1
|
2007-03-03 19:33:48 +01:00
|
|
|
|
2010-08-21 08:21:22 +02:00
|
|
|
user-manual.html: user-manual.xml $(XSLT)
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
|
2007-01-08 01:23:49 +01:00
|
|
|
|
2007-12-12 22:31:02 +01:00
|
|
|
git.info: user-manual.texi
|
2009-03-27 07:49:38 +01:00
|
|
|
$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
|
2007-12-10 10:15:57 +01:00
|
|
|
|
2007-12-12 22:31:02 +01:00
|
|
|
user-manual.texi: user-manual.xml
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@+ && \
|
|
|
|
|
$(PERL_PATH) fix-texi.perl <$@+ >$@ && \
|
2021-05-22 00:29:41 +02:00
|
|
|
$(RM) $@+
|
2007-12-10 10:15:57 +01:00
|
|
|
|
2008-12-10 23:44:50 +01:00
|
|
|
user-manual.pdf: user-manual.xml
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_DBLATEX)$(DBLATEX) -o $@ $(DBLATEX_COMMON) $<
|
2008-12-10 23:44:50 +01:00
|
|
|
|
Documentation: add XSLT to fix DocBook for Texinfo
There are two ways to create a section in a reference document (i.e.,
manpage) in DocBook 4: refsection elements and refsect, refsect2, and
refsect3 elements. Either form is acceptable as of DocBook 4.2, but
they cannot be mixed. Prior to DocBook 4.2, only the numbered forms
were acceptable.
docbook2texi only accepts the numbered forms, and this has not generally
been a problem, since AsciiDoc produces the numbered forms.
Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
5, and uses the unnumbered refsection elements instead.
If we don't convert the unnumbered form to the numbered form,
docbook2texi omits section headings, which is undesirable. Add an XSLT
stylesheet to transform the unnumbered forms to the numbered forms
automatically, and preprocess the DocBook XML as part of the
transformation to Texinfo format.
Note that this transformation is only necessary for Texinfo, since
docbook2texi provides its own stylesheets. The DocBook stylesheets,
which we use for other formats, provide the full range of DocBook 4 and
5 compatibility, and don't have this issue.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-22 03:41:54 +01:00
|
|
|
gitman.texi: $(MAN_XML) cat-texi.perl texi.xsl
|
2021-05-22 00:29:39 +02:00
|
|
|
$(QUIET_DB2TEXI) \
|
Documentation: add XSLT to fix DocBook for Texinfo
There are two ways to create a section in a reference document (i.e.,
manpage) in DocBook 4: refsection elements and refsect, refsect2, and
refsect3 elements. Either form is acceptable as of DocBook 4.2, but
they cannot be mixed. Prior to DocBook 4.2, only the numbered forms
were acceptable.
docbook2texi only accepts the numbered forms, and this has not generally
been a problem, since AsciiDoc produces the numbered forms.
Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
5, and uses the unnumbered refsection elements instead.
If we don't convert the unnumbered form to the numbered form,
docbook2texi omits section headings, which is undesirable. Add an XSLT
stylesheet to transform the unnumbered forms to the numbered forms
automatically, and preprocess the DocBook XML as part of the
transformation to Texinfo format.
Note that this transformation is only necessary for Texinfo, since
docbook2texi provides its own stylesheets. The DocBook stylesheets,
which we use for other formats, provide the full range of DocBook 4 and
5 compatibility, and don't have this issue.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-01-22 03:41:54 +01:00
|
|
|
($(foreach xml,$(sort $(MAN_XML)),xsltproc -o $(xml)+ texi.xsl $(xml) && \
|
|
|
|
|
$(DOCBOOK2X_TEXI) --encoding=UTF-8 --to-stdout $(xml)+ && \
|
2021-05-22 00:29:41 +02:00
|
|
|
$(RM) $(xml)+ &&) true) > $@+ && \
|
2021-05-22 00:29:40 +02:00
|
|
|
$(PERL_PATH) cat-texi.perl $@ <$@+ >$@ && \
|
2021-05-22 00:29:41 +02:00
|
|
|
$(RM) $@+
|
2007-12-10 10:15:57 +01:00
|
|
|
|
|
|
|
|
gitman.info: gitman.texi
|
Documentation/Makefile: fix "make info" regression in dad9cd7d518
Fix a regression in my dad9cd7d518 (Makefile: move ".SUFFIXES" rule to
shared.mak, 2022-03-03). As explained in the GNU make documentation
for the $* variable, available at:
info make --index-search='$*'
This rule relied on ".texi" being in the default list of suffixes, as
seen at:
make -f/dev/null -p | grep -v -e ^# -e ^$|grep -F .SUFFIXES
The documentation explains what was going on here:
In an explicit rule, there is no stem; so '$*' cannot be determined
in that way. Instead, if the target name ends with a recognized
suffix (*note Old-Fashioned Suffix Rules: Suffix Rules.), '$*' is
set to the target name minus the suffix. For example, if the
target name is 'foo.c', then '$*' is set to 'foo', since '.c' is a
suffix. GNU 'make' does this bizarre thing only for compatibility
with other implementations of 'make'. You should generally avoid
using '$*' except in implicit rules or static pattern rules.
If the target name in an explicit rule does not end with a
recognized suffix, '$*' is set to the empty string for that rule.
I.e. this rule added back in 5cefc33bffd (Documentation: add
gitman.info target, 2007-12-10) was resolving gitman.texi from
gitman.info. We can instead just use the more obvious $< variable
referring to the prerequisite.
This was the only use of $* in our Makefiles in an explicit rule, the
three remaining ones are all implicit rules, and therefore didn't
depend on the ".SUFFIXES" list.
Reported-by: Adam Dinwoodie <adam@dinwoodie.org>
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Tested-by: Adam Dinwoodie <adam@dinwoodie.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-04-05 21:56:20 +02:00
|
|
|
$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $<
|
2007-12-10 10:15:57 +01:00
|
|
|
|
|
|
|
|
$(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@
|
2007-08-06 12:22:57 +02:00
|
|
|
|
2021-04-09 17:02:44 +02:00
|
|
|
howto-index.txt: howto-index.sh $(HOWTO_TXT)
|
2021-05-22 00:29:40 +02:00
|
|
|
$(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@
|
2005-08-25 09:28:18 +02:00
|
|
|
|
2005-08-30 22:51:01 +02:00
|
|
|
$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
|
2014-10-27 01:13:42 +01:00
|
|
|
$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
|
2005-08-25 09:28:18 +02:00
|
|
|
|
|
|
|
|
WEBDOC_DEST = /pub/software/scm/git/docs
|
|
|
|
|
|
2012-06-07 23:03:23 +02:00
|
|
|
howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
|
2021-04-09 17:02:44 +02:00
|
|
|
$(patsubst %.txt,%.html,$(HOWTO_TXT)): %.html : %.txt GIT-ASCIIDOCFLAGS
|
2021-05-22 00:29:39 +02:00
|
|
|
$(QUIET_ASCIIDOC) \
|
2014-10-12 01:37:35 +02:00
|
|
|
sed -e '1,/^$$/d' $< | \
|
2021-05-22 00:29:40 +02:00
|
|
|
$(TXT_TO_HTML) - >$@
|
2005-08-30 07:38:12 +02:00
|
|
|
|
2005-08-25 09:28:18 +02:00
|
|
|
install-webdoc : html
|
2009-03-22 14:20:44 +01:00
|
|
|
'$(SHELL_PATH_SQ)' ./install-webdoc.sh $(WEBDOC_DEST)
|
2006-12-23 17:26:09 +01:00
|
|
|
|
2013-01-21 20:17:53 +01:00
|
|
|
# You must have a clone of 'git-htmldocs' and 'git-manpages' repositories
|
|
|
|
|
# next to the 'git' repository itself for the following to work.
|
2011-11-08 19:17:40 +01:00
|
|
|
|
2008-11-02 18:53:03 +01:00
|
|
|
quick-install: quick-install-man
|
|
|
|
|
|
2011-11-08 19:17:40 +01:00
|
|
|
require-manrepo::
|
|
|
|
|
@if test ! -d $(MAN_REPO); \
|
|
|
|
|
then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi
|
|
|
|
|
|
|
|
|
|
quick-install-man: require-manrepo
|
2017-12-09 23:07:57 +01:00
|
|
|
'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF)
|
2011-11-08 19:17:40 +01:00
|
|
|
|
|
|
|
|
require-htmlrepo::
|
|
|
|
|
@if test ! -d $(HTML_REPO); \
|
|
|
|
|
then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi
|
2007-03-25 13:56:49 +02:00
|
|
|
|
2011-11-08 19:17:40 +01:00
|
|
|
quick-install-html: require-htmlrepo
|
2017-12-09 23:07:57 +01:00
|
|
|
'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF)
|
2008-09-09 22:44:17 +02:00
|
|
|
|
2012-08-08 22:57:52 +02:00
|
|
|
print-man1:
|
|
|
|
|
@for i in $(MAN1_TXT); do echo $$i; done
|
|
|
|
|
|
2021-10-15 14:39:14 +02:00
|
|
|
## Lint: gitlink
|
|
|
|
|
LINT_DOCS_GITLINK = $(patsubst %.txt,.build/lint-docs/gitlink/%.ok,$(HOWTO_TXT) $(DOC_DEP_TXT))
|
|
|
|
|
$(LINT_DOCS_GITLINK): lint-gitlink.perl
|
|
|
|
|
$(LINT_DOCS_GITLINK): .build/lint-docs/gitlink/%.ok: %.txt
|
Makefiles: add and use wildcard "mkdir -p" template
Add a template to do the "mkdir -p" of $(@D) (the parent dir of $@)
for us, and use it for the "make lint-docs" targets I added in
8650c6298c1 (doc lint: make "lint-docs" non-.PHONY, 2021-10-15).
As seen in 4c64fb5aad9 (Documentation/Makefile: fix lint-docs mkdir
dependency, 2021-10-26) maintaining these manual lists of parent
directory dependencies is fragile, in addition to being obviously
verbose.
I used this pattern at the time because I couldn't find another method
than "order-only" prerequisites to avoid doing a "mkdir -p $(@D)" for
every file being created, which as noted in [1] would be significantly
slower.
But as it turns out we can use this neat trick of only doing a "mkdir
-p" if the $(wildcard) macro tells us the path doesn't exist. A re-run
of a performance test similar to that noted downthread of [1] in [2]
shows that this is faster, in addition to being less verbose and more
reliable (this uses my "git-hyperfine" thin wrapper for "hyperfine"[3]):
$ git -c hyperfine.hook.setup= hyperfine -L rev HEAD~1,HEAD~0 -s 'make -C Documentation lint-docs' -p 'rm -rf Documentation/.build' 'make -C Documentation -j1 lint-docs'
Benchmark 1: make -C Documentation -j1 lint-docs' in 'HEAD~1
Time (mean ± σ): 2.914 s ± 0.062 s [User: 2.449 s, System: 0.489 s]
Range (min … max): 2.834 s … 3.020 s 10 runs
Benchmark 2: make -C Documentation -j1 lint-docs' in 'HEAD~0
Time (mean ± σ): 2.315 s ± 0.062 s [User: 1.950 s, System: 0.386 s]
Range (min … max): 2.229 s … 2.397 s 10 runs
Summary
'make -C Documentation -j1 lint-docs' in 'HEAD~0' ran
1.26 ± 0.04 times faster than 'make -C Documentation -j1 lint-docs' in 'HEAD~1'
So let's use that pattern both for the "lint-docs" target, and a few
miscellaneous other targets.
This method of creating parent directories is explicitly racy in that
we don't know if we're going to say always create a "foo" followed by
a "foo/bar" under parallelism, or skip the "foo" because we created
"foo/bar" first. In this case it doesn't matter for anything except
that we aren't guaranteed to get the same number of rules firing when
running make in parallel.
1. https://lore.kernel.org/git/211028.861r45y3pt.gmgdl@evledraar.gmail.com/
2. https://lore.kernel.org/git/211028.86o879vvtp.gmgdl@evledraar.gmail.com/
3. https://gitlab.com/avar/git-hyperfine/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-03 17:04:19 +01:00
|
|
|
$(call mkdir_p_parent_template)
|
2021-10-15 14:39:14 +02:00
|
|
|
$(QUIET_LINT_GITLINK)$(PERL_PATH) lint-gitlink.perl \
|
|
|
|
|
$< \
|
doc lint: fix bugs in, simplify and improve lint script
The lint-gitlink.perl script added in ab81411ced (ci: validate
"linkgit:" in documentation, 2016-05-04) was more complex than it
needed to be. It:
- Was using File::Find to recursively find *.txt files in
Documentation/, let's instead use the Makefile as a source of truth
for *.txt files, and pass it down to the script.
- We now don't lint linkgit:* in RelNotes/* or technical/*, which we
shouldn't have been doing in the first place anyway.
- When the doc-diff script was added in beb188e22a (add a script to
diff rendered documentation, 2018-08-06) we started sometimes having
a "git worktree" under Documentation/.
This tree contains a full checkout of git.git, as a result the
"lint" script would recurse into that, and lint any *.txt file
found in that entire repository.
In practice the only in-tree "linkgit" outside of the
Documentation/ tree is contrib/contacts/git-contacts.txt and
contrib/subtree/git-subtree.txt, so this wouldn't emit any errors
Now we instead simply trust the Makefile to give us *.txt files.
Since the Makefile also knows what sections each page should be in we
don't have to open the files ourselves and try to parse that out. As a
bonus this will also catch bugs with the section line in the files
themselves being incorrect.
The structure of the new script is mostly based on
t/check-non-portable-shell.pl. As an added bonus it will also use
pos() to print where the problems it finds are, e.g. given an issue
like:
diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt
[...]
and line numbers. git-cherry therefore detects when commits have been
-"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or
-linkgit:git-rebase[1].
+"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3] or
+linkgit:git-rebase[4].
We'll now emit:
git-cherry.txt:20: error: git-cherry-pick[2]: wrong section (should be 1), shown with 'HERE' below:
git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2]' <-- HERE
git-cherry.txt:20: error: git-am[3]: wrong section (should be 1), shown with 'HERE' below:
git-cherry.txt:20: '"copied" by means of linkgit:git-cherry-pick[2], linkgit:git-am[3]' <-- HERE
git-cherry.txt:21: error: git-rebase[4]: wrong section (should be 1), shown with 'HERE' below:
git-cherry.txt:21: 'linkgit:git-rebase[4]' <-- HERE
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2021-04-09 17:02:47 +02:00
|
|
|
$(HOWTO_TXT) $(DOC_DEP_TXT) \
|
|
|
|
|
--section=1 $(MAN1_TXT) \
|
|
|
|
|
--section=5 $(MAN5_TXT) \
|
2021-10-15 14:39:14 +02:00
|
|
|
--section=7 $(MAN7_TXT) >$@
|
|
|
|
|
.PHONY: lint-docs-gitlink
|
|
|
|
|
lint-docs-gitlink: $(LINT_DOCS_GITLINK)
|
|
|
|
|
|
|
|
|
|
## Lint: man-end-blurb
|
|
|
|
|
LINT_DOCS_MAN_END_BLURB = $(patsubst %.txt,.build/lint-docs/man-end-blurb/%.ok,$(MAN_TXT))
|
|
|
|
|
$(LINT_DOCS_MAN_END_BLURB): lint-man-end-blurb.perl
|
|
|
|
|
$(LINT_DOCS_MAN_END_BLURB): .build/lint-docs/man-end-blurb/%.ok: %.txt
|
Makefiles: add and use wildcard "mkdir -p" template
Add a template to do the "mkdir -p" of $(@D) (the parent dir of $@)
for us, and use it for the "make lint-docs" targets I added in
8650c6298c1 (doc lint: make "lint-docs" non-.PHONY, 2021-10-15).
As seen in 4c64fb5aad9 (Documentation/Makefile: fix lint-docs mkdir
dependency, 2021-10-26) maintaining these manual lists of parent
directory dependencies is fragile, in addition to being obviously
verbose.
I used this pattern at the time because I couldn't find another method
than "order-only" prerequisites to avoid doing a "mkdir -p $(@D)" for
every file being created, which as noted in [1] would be significantly
slower.
But as it turns out we can use this neat trick of only doing a "mkdir
-p" if the $(wildcard) macro tells us the path doesn't exist. A re-run
of a performance test similar to that noted downthread of [1] in [2]
shows that this is faster, in addition to being less verbose and more
reliable (this uses my "git-hyperfine" thin wrapper for "hyperfine"[3]):
$ git -c hyperfine.hook.setup= hyperfine -L rev HEAD~1,HEAD~0 -s 'make -C Documentation lint-docs' -p 'rm -rf Documentation/.build' 'make -C Documentation -j1 lint-docs'
Benchmark 1: make -C Documentation -j1 lint-docs' in 'HEAD~1
Time (mean ± σ): 2.914 s ± 0.062 s [User: 2.449 s, System: 0.489 s]
Range (min … max): 2.834 s … 3.020 s 10 runs
Benchmark 2: make -C Documentation -j1 lint-docs' in 'HEAD~0
Time (mean ± σ): 2.315 s ± 0.062 s [User: 1.950 s, System: 0.386 s]
Range (min … max): 2.229 s … 2.397 s 10 runs
Summary
'make -C Documentation -j1 lint-docs' in 'HEAD~0' ran
1.26 ± 0.04 times faster than 'make -C Documentation -j1 lint-docs' in 'HEAD~1'
So let's use that pattern both for the "lint-docs" target, and a few
miscellaneous other targets.
This method of creating parent directories is explicitly racy in that
we don't know if we're going to say always create a "foo" followed by
a "foo/bar" under parallelism, or skip the "foo" because we created
"foo/bar" first. In this case it doesn't matter for anything except
that we aren't guaranteed to get the same number of rules firing when
running make in parallel.
1. https://lore.kernel.org/git/211028.861r45y3pt.gmgdl@evledraar.gmail.com/
2. https://lore.kernel.org/git/211028.86o879vvtp.gmgdl@evledraar.gmail.com/
3. https://gitlab.com/avar/git-hyperfine/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-03 17:04:19 +01:00
|
|
|
$(call mkdir_p_parent_template)
|
2021-10-15 14:39:14 +02:00
|
|
|
$(QUIET_LINT_MANEND)$(PERL_PATH) lint-man-end-blurb.perl $< >$@
|
|
|
|
|
.PHONY: lint-docs-man-end-blurb
|
|
|
|
|
|
|
|
|
|
## Lint: man-section-order
|
|
|
|
|
LINT_DOCS_MAN_SECTION_ORDER = $(patsubst %.txt,.build/lint-docs/man-section-order/%.ok,$(MAN_TXT))
|
|
|
|
|
$(LINT_DOCS_MAN_SECTION_ORDER): lint-man-section-order.perl
|
|
|
|
|
$(LINT_DOCS_MAN_SECTION_ORDER): .build/lint-docs/man-section-order/%.ok: %.txt
|
Makefiles: add and use wildcard "mkdir -p" template
Add a template to do the "mkdir -p" of $(@D) (the parent dir of $@)
for us, and use it for the "make lint-docs" targets I added in
8650c6298c1 (doc lint: make "lint-docs" non-.PHONY, 2021-10-15).
As seen in 4c64fb5aad9 (Documentation/Makefile: fix lint-docs mkdir
dependency, 2021-10-26) maintaining these manual lists of parent
directory dependencies is fragile, in addition to being obviously
verbose.
I used this pattern at the time because I couldn't find another method
than "order-only" prerequisites to avoid doing a "mkdir -p $(@D)" for
every file being created, which as noted in [1] would be significantly
slower.
But as it turns out we can use this neat trick of only doing a "mkdir
-p" if the $(wildcard) macro tells us the path doesn't exist. A re-run
of a performance test similar to that noted downthread of [1] in [2]
shows that this is faster, in addition to being less verbose and more
reliable (this uses my "git-hyperfine" thin wrapper for "hyperfine"[3]):
$ git -c hyperfine.hook.setup= hyperfine -L rev HEAD~1,HEAD~0 -s 'make -C Documentation lint-docs' -p 'rm -rf Documentation/.build' 'make -C Documentation -j1 lint-docs'
Benchmark 1: make -C Documentation -j1 lint-docs' in 'HEAD~1
Time (mean ± σ): 2.914 s ± 0.062 s [User: 2.449 s, System: 0.489 s]
Range (min … max): 2.834 s … 3.020 s 10 runs
Benchmark 2: make -C Documentation -j1 lint-docs' in 'HEAD~0
Time (mean ± σ): 2.315 s ± 0.062 s [User: 1.950 s, System: 0.386 s]
Range (min … max): 2.229 s … 2.397 s 10 runs
Summary
'make -C Documentation -j1 lint-docs' in 'HEAD~0' ran
1.26 ± 0.04 times faster than 'make -C Documentation -j1 lint-docs' in 'HEAD~1'
So let's use that pattern both for the "lint-docs" target, and a few
miscellaneous other targets.
This method of creating parent directories is explicitly racy in that
we don't know if we're going to say always create a "foo" followed by
a "foo/bar" under parallelism, or skip the "foo" because we created
"foo/bar" first. In this case it doesn't matter for anything except
that we aren't guaranteed to get the same number of rules firing when
running make in parallel.
1. https://lore.kernel.org/git/211028.861r45y3pt.gmgdl@evledraar.gmail.com/
2. https://lore.kernel.org/git/211028.86o879vvtp.gmgdl@evledraar.gmail.com/
3. https://gitlab.com/avar/git-hyperfine/
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2022-03-03 17:04:19 +01:00
|
|
|
$(call mkdir_p_parent_template)
|
2021-10-15 14:39:14 +02:00
|
|
|
$(QUIET_LINT_MANSEC)$(PERL_PATH) lint-man-section-order.perl $< >$@
|
|
|
|
|
.PHONY: lint-docs-man-section-order
|
|
|
|
|
lint-docs-man-section-order: $(LINT_DOCS_MAN_SECTION_ORDER)
|
|
|
|
|
|
2022-10-26 00:42:24 +02:00
|
|
|
.PHONY: lint-docs-fsck-msgids
|
|
|
|
|
LINT_DOCS_FSCK_MSGIDS = .build/lint-docs/fsck-msgids.ok
|
|
|
|
|
$(LINT_DOCS_FSCK_MSGIDS): lint-fsck-msgids.perl
|
|
|
|
|
$(LINT_DOCS_FSCK_MSGIDS): ../fsck.h fsck-msgids.txt
|
|
|
|
|
$(call mkdir_p_parent_template)
|
|
|
|
|
$(QUIET_GEN)$(PERL_PATH) lint-fsck-msgids.perl \
|
|
|
|
|
../fsck.h fsck-msgids.txt $@
|
|
|
|
|
|
|
|
|
|
lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS)
|
|
|
|
|
|
2021-10-15 14:39:14 +02:00
|
|
|
## Lint: list of targets above
|
|
|
|
|
.PHONY: lint-docs
|
2022-10-26 00:42:24 +02:00
|
|
|
lint-docs: lint-docs-fsck-msgids
|
2021-10-15 14:39:14 +02:00
|
|
|
lint-docs: lint-docs-gitlink
|
|
|
|
|
lint-docs: lint-docs-man-end-blurb
|
|
|
|
|
lint-docs: lint-docs-man-section-order
|
2016-05-04 23:34:23 +02:00
|
|
|
|
2019-01-07 20:21:12 +01:00
|
|
|
ifeq ($(wildcard po/Makefile),po/Makefile)
|
|
|
|
|
doc-l10n install-l10n::
|
|
|
|
|
$(MAKE) -C po $@
|
|
|
|
|
endif
|
|
|
|
|
|
2010-01-06 09:06:58 +01:00
|
|
|
.PHONY: FORCE
|