Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs

From: Jeff King <peff@peff.net>
Date: Jun 27, 2018, 14:14 UTC
Message-ID: <20180627141430.GA13904@sigill.intra.peff.net>
In-Reply-To: <20180627045637.13818-1-tmz@pobox.com>

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?)

Show 28 quoted lines

> 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?

Show 10 quoted lines

> 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