Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs
From: Jeff King <hidden>
Date: 2018-06-27 14:14:35
On Wed, Jun 27, 2018 at 12:56:37AM -0400, Todd Zullinger wrote:
Replace `$(prefix)/etc/gitconfig` and `$(prefix)/etc/gitattributes` in generated documentation with the paths chosen when building. Readers of the documentation should not need to know how `$(prefix)` was defined.
Yes, I was just complaining about this yesterday. Besides readers not
having any clue what $(prefix) means here, $(prefix)/etc is not even
correct for builds with prefix=/usr.
So I like the overall direction here, but it leaves me with one
question: what happens for documentation outside of customized builds?
Specifically, I'm thinking of:
1. The pre-built documentation that Junio builds for
quick-install-doc. This _could_ be customized during the "quick"
step, but it's probably not worth the effort. However, we'd want
some kind of generic fill-in then, and hopefully not
"/home/jch/etc" or something.
2. The manpages on git-scm.com, which are built with asciidoctor. I
think we'd want the same generic value there. Ideally it would be
embedded in the asciidoc source as "if this attribute isn't
defined, then use this", but it's not the end of the world to
require a patch to the site to handle this.
(Related, there's a build target in the local Makefile for using
asciidoctor; does it need updated, too?)
quoted hunk ↗ jump to hunk
diff --git a/Documentation/Makefile b/Documentation/Makefile index d079d7c73a..75af671798 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile@@ -95,6 +95,7 @@ DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT)) prefix ?= $(HOME) bindir ?= $(prefix)/bin +sysconfdir ?= $(prefix)/etc htmldir ?= $(prefix)/share/doc/git-doc infodir ?= $(prefix)/share/info pdfdir ?= $(prefix)/share/doc/git-doc@@ -205,6 +206,18 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR)) ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)' endif +ifndef ETC_GITCONFIG +ETC_GITCONFIG = $(sysconfdir)/gitconfig +endif +ETC_GITCONFIG_SQ = $(subst ','\'',$(ETC_GITCONFIG)) +ASCIIDOC_EXTRA += -a 'etc-gitconfig=$(ETC_GITCONFIG_SQ)' + +ifndef ETC_GITATTRIBUTES +ETC_GITATTRIBUTES = $(sysconfdir)/gitattributes +endif +ETC_GITATTRIBUTES_SQ = $(subst ','\'',$(ETC_GITATTRIBUTES)) +ASCIIDOC_EXTRA += -a 'etc-gitattributes=$(ETC_GITATTRIBUTES_SQ)' +
It's a shame we have to repeat this logic from the Makefile, though I guess we already do so for prefix, bindir, etc, so far. Should we factor the path logic from the top-level Makefile into an include that can be used from either?
quoted hunk ↗ jump to hunk
diff --git a/Documentation/config.txt b/Documentation/config.txt index 1cc18a828c..ed903b60bd 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt@@ -5,7 +5,7 @@ The Git configuration file contains a number of variables that affect the Git commands' behavior. The `.git/config` file in each repository is used to store the configuration for that repository, and `$HOME/.gitconfig` is used to store a per-user configuration as -fallback values for the `.git/config` file. The file `/etc/gitconfig` +fallback values for the `.git/config` file. The file +{etc-gitconfig}+
I think the formatting tweak you've done here is the right thing. There's no way to expand within literal backticks (since that's the point). So we only care about the monospacing effect, which ++ should give. -Peff