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

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

[Todd Zullinger]

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.

It's also more consistent than sometimes using `$(prefix)/etc/gitconfig`
and other times using `/etc/gitconfig` to refer to the system-wide
config file.

Update the SYNOPSIS of gitattributes(5) to include the system-wide
config file as well.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
I noticed this while looking to update gitattributes.txt to
note the system-wide config file.  I tested with and without
RUNTIME_PREFIX as well as make gitattributes.5 from within
Documentation.  I believe all methods do the right thing.

I couldn't figure out a good way to have asciidoc expand the
attributes inside of a "`" literal, so I changed to the "+"
form.  There might be a better way to do this, passing subs=
in asciidoc.conf, but I wasn't clear on where that would
fit.  I tested with asciidoc and not asciidoctor.

 Documentation/Makefile          | 13 +++++++++++++
 Documentation/config.txt        |  4 ++--
 Documentation/git-config.txt    | 10 +++++-----
 Documentation/git.txt           |  4 ++--
 Documentation/gitattributes.txt |  4 ++--
 5 files changed, 24 insertions(+), 11 deletions(-)

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)'
+
 QUIET_SUBDIR0  = +$(MAKE) -C # space to separate -C and subdir
 QUIET_SUBDIR1  =
 
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}+
 can be used to store a system-wide default configuration.
 
 The configuration variables are used by both the Git plumbing
@@ -2815,7 +2815,7 @@ configuration files (e.g. `$HOME/.gitconfig`).
 
 Example:
 
-/etc/gitconfig
+{etc-gitconfig}
   push.pushoption = a
   push.pushoption = b
 
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 18ddc78f42..0d5ea5b58e 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -114,10 +114,10 @@ See also <<FILES>>.
 
 --system::
 	For writing options: write to system-wide
-	`$(prefix)/etc/gitconfig` rather than the repository
+	+{etc-gitconfig}+ rather than the repository
 	`.git/config`.
 +
-For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
+For reading options: read only from system-wide +{etc-gitconfig}+
 rather than from all available files.
 +
 See also <<FILES>>.
@@ -263,7 +263,7 @@ FILES
 If not set explicitly with `--file`, there are four files where
 'git config' will search for configuration options:
 
-$(prefix)/etc/gitconfig::
+{etc-gitconfig}::
 	System-wide configuration file.
 
 $XDG_CONFIG_HOME/git/config::
@@ -310,11 +310,11 @@ ENVIRONMENT
 GIT_CONFIG::
 	Take the configuration from the given file instead of .git/config.
 	Using the "--global" option forces this to ~/.gitconfig. Using the
-	"--system" option forces this to $(prefix)/etc/gitconfig.
+	"--system" option forces this to {etc-gitconfig}.
 
 GIT_CONFIG_NOSYSTEM::
 	Whether to skip reading settings from the system-wide
-	$(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
+	{etc-gitconfig} file. See linkgit:git[1] for details.
 
 See also <<FILES>>.
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index dba7f0c18e..6a4646f991 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -567,10 +567,10 @@ for further details.
 
 `GIT_CONFIG_NOSYSTEM`::
 	Whether to skip reading settings from the system-wide
-	`$(prefix)/etc/gitconfig` file.  This environment variable can
+	+{etc-gitconfig}+ file.  This environment variable can
 	be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
 	predictable environment for a picky script, or you can set it
-	temporarily to avoid using a buggy `/etc/gitconfig` file while
+	temporarily to avoid using a buggy +{etc-gitconfig}+ file while
 	waiting for someone with sufficient permissions to fix it.
 
 `GIT_FLUSH`::
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 92010b062e..528de42593 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -7,7 +7,7 @@ gitattributes - Defining attributes per path
 
 SYNOPSIS
 --------
-$GIT_DIR/info/attributes, .gitattributes
+{etc-gitattributes}, $GIT_DIR/info/attributes, .gitattributes
 
 
 DESCRIPTION
@@ -93,7 +93,7 @@ for a single user should be placed in a file specified by the
 Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
 is either not set or empty, $HOME/.config/git/attributes is used instead.
 Attributes for all users on a system should be placed in the
-`$(prefix)/etc/gitattributes` file.
++{etc-gitattributes}+ file.
 
 Sometimes you would need to override a setting of an attribute
 for a path to `Unspecified` state.  This can be done by listing
-- 
2.18.0

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

[Jeff King]

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

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

> 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

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

[Todd Zullinger]

Jeff King wrote:
> 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.

So what you're saying is that if I had procrastinated a
little, you may have written such a patch for me? :)

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

If building docs separately for such a use, the values can
be overridden by setting ETC_GITCONFIG and ETC_GITATTRIBUTES
(or prefix or sysconfig).  To keep the same values as we
currently use, for example:

    make -C Documentation V=1 \
            ETC_GITCONFIG='$$(prefix)/etc/gitconfig' \
            ETC_GITATTRIBUTES='$$(prefix)/etc/gitattributes'

I don't know if that's sufficient for folks who build
documentation to share with a general audience or not.

It might be enough if the default values are relatively sane
and consistent.  That would be a slight improvement over the
current situation still.

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

We have that for the DEFAULT_(EDITOR|PAGER).  I didn't know
if we'd want that here, but maybe it's worth the effort if
it helps when building docs destined for the website and
such.  It might make the plain text files a bit less
readable though.

The EDITOR/PAGER bits are in git-var.txt, like this:

    GIT_EDITOR::
        Text editor for use by Git commands.  The value is meant to be
        interpreted by the shell when it is used.  Examples: `~/bin/vi`,
        `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe"
        --nofork`.  The order of preference is the `$GIT_EDITOR`
        environment variable, then `core.editor` configuration, then
        `$VISUAL`, then `$EDITOR`, and then the default chosen at compile
        time, which is usually 'vi'.
    ifdef::git-default-editor[]
        The build you are using chose '{git-default-editor}' as the default.
    endif::git-default-editor[]

The ifdef would be a little different to set the var if it
was not set, of course.

I think if we ensure that ETC_GITCONFIG / ETC_GITATTRIBUTES
are set sanely by default (and easily overridden) then we
can probably avoid the need to handle it within the asciidoc
file though.  (There's more on that though below.)

>      (Related, there's a build target in the local Makefile for using
>      asciidoctor; does it need updated, too?)

I didn't test asciidoctor specficially, but it also respects
the ASCIIDOC_EXTRA parameters, so I think it will work just
as well.  I'll try to confirm that later today.

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

Yeah, maybe.  I didn't like the duplication either, but as
you noticed, we do it already for many of the other
variables.  I suspect we could put these defaults into
config.mak.uname which Documentation/Makefile includes and
then you could run 'make -C Documentation' in a fresh clone
or tarball and get docs built with the defaults set for each
platform.

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

Thanks.  It took me longer to decide that I couldn't find a
clean way to do it without using ++ than anything else. :)

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
No one ever went broke underestimating the taste of the American
public.
    -- H. L. Mencken

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

[Todd Zullinger]

I wrote:
> Jeff King wrote:
>>      (Related, there's a build target in the local Makefile for using
>>      asciidoctor; does it need updated, too?)
> 
> I didn't test asciidoctor specficially, but it also respects
> the ASCIIDOC_EXTRA parameters, so I think it will work just
> as well.  I'll try to confirm that later today.

Testing confirmed that asciidoctor works fine with this as
well.

Somewhat tangentially, I looked at using asciidoctor for the
Fedora packages last year and one issue that kept me from
using it then was the '[FIXME: source]' it includes in the
footer of the manpage.  When I dug into it at the time, it
appeared this was due to no <refmiscinfo> declaration
(similarly missing for manual, and version).  It wasn't
clear whether it was possible to include a custom header
template in plain asciidoctor.  I got the impression that it
would require using a custom backend, which in turn required
the rubygem 'tilt' for processing.

I spent about an hour poking around with it and decided that
I'd put off building with asciidoctor until that was fixed.
I felt that displaying '[FIXME: source]' wass worse than
simply not including the version.

It's always possible that I was doing something wrong in my
use of asciidoctor (I just set USE_ASCIIDOCTOR).  Or maybe
the Fedora packages are missing some dependency which I
missed.

It might also be that we need some adjustments similar to
https://patchwork.kernel.org/patch/10360207/ to get the
mansource attribute passed on to asciidoctor.  I only just
ran across that patch and haven't had a chance to test
sometime similar in the git manpage build.  That looks
promising though.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why is it that we rejoice at a birth and grieve at a funeral?  It is
because we are not the person involved.
    -- Mark Twain

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

That is very likely to happen, actually X-<.

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

[Todd Zullinger]

Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
>> 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.
> 
> That is very likely to happen, actually X-<.

Obviously, we don't want the end result to cause regressions
in the common case or any burden on you.  Would setting the
ETC_GIT(CONFIG|ATTRIBUTES) variables in the dist-doc target
alleviate that concern?

Alternately, we can make the default use generic paths and
require some other knob to enable substituting the actual
paths when building documentation.

I tend to think that the default should be to build
documentation that is accurate for that build, but since
it's something I'll set once for my package builds it's not
a big deal either way to me.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Einstein argued that there must be simplified explanations of nature,
because God is not capricious or arbitrary. No such faith comforts the
software engineer.
    -- Fred Brooks

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

[Jeff King]

On Wed, Jun 27, 2018 at 11:03:52AM -0400, Todd Zullinger wrote:

> So what you're saying is that if I had procrastinated a
> little, you may have written such a patch for me? :)

Yes, but that's a dangerous game of chicken. :)

> >   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.
> 
> If building docs separately for such a use, the values can
> be overridden by setting ETC_GITCONFIG and ETC_GITATTRIBUTES
> (or prefix or sysconfig).  To keep the same values as we
> currently use, for example:
> 
>     make -C Documentation V=1 \
>             ETC_GITCONFIG='$$(prefix)/etc/gitconfig' \
>             ETC_GITATTRIBUTES='$$(prefix)/etc/gitattributes'
> 
> I don't know if that's sufficient for folks who build
> documentation to share with a general audience or not.

One downside is that this means the generic-doc builder has to put
nonsense into ETC_GITCONFIG. That means it would be a bad idea to put
this into config.mak, for example, as it would break their regular
build.

We could get rid around that by using $(DOC_ETC_GITCONFIG) or something,
with:

  DOC_ETC_GITCONFIG ?= $(ETC_GITCONFIG)

in the Makefile. But that still leaves the choice of which generic text
to use up to the caller. Maybe we should provide more guidance.

I.e., provide a knob like DOC_GENERIC that fills in generic values for
these values (and maybe some others; it sounds like we have some
existing problem cases).

> It might be enough if the default values are relatively sane
> and consistent.  That would be a slight improvement over the
> current situation still.

Yeah. Taking a step back from the implementation questions, I think
"$(prefix)/etc/gitconfig" is not very helpful text. I'd be happy to see
us come up with a generic way of saying that which is more
comprehensible to end-users. Your patches side-step that by filling in
the real value, but unfortunately we can't do that everywhere. :)

There may not be a good "token" value, though. I.e., we may need to have
two sets of verbiage: the specific one, and the generic one.

> The EDITOR/PAGER bits are in git-var.txt, like this:
> 
>     GIT_EDITOR::
>         Text editor for use by Git commands.  The value is meant to be
>         interpreted by the shell when it is used.  Examples: `~/bin/vi`,
>         `$SOME_ENVIRONMENT_VARIABLE`, `"C:\Program Files\Vim\gvim.exe"
>         --nofork`.  The order of preference is the `$GIT_EDITOR`
>         environment variable, then `core.editor` configuration, then
>         `$VISUAL`, then `$EDITOR`, and then the default chosen at compile
>         time, which is usually 'vi'.
>     ifdef::git-default-editor[]
>         The build you are using chose '{git-default-editor}' as the default.
>     endif::git-default-editor[]
> 
> The ifdef would be a little different to set the var if it
> was not set, of course.

Thanks, I didn't know about those cases. The git-scm.com version gets
that right, because we don't set DEFAULT_* there. I wondered if we might
have problems with other generic builds since we do have defaults for
those DEFAULT_* variables. But it looks like those defaults are applied
within the C code itself. So unless Junio starts setting DEFAULT_PAGER
himself, I think his builds are OK.

> I think if we ensure that ETC_GITCONFIG / ETC_GITATTRIBUTES
> are set sanely by default (and easily overridden) then we
> can probably avoid the need to handle it within the asciidoc
> file though.  (There's more on that though below.)

I think these two differ from the DEFAULT_* in that we'll _always_ have
them set in the Makefile. And we probably always want to report them
unless we're in a generic documentation build.

> > 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?
> 
> Yeah, maybe.  I didn't like the duplication either, but as
> you noticed, we do it already for many of the other
> variables.  I suspect we could put these defaults into
> config.mak.uname which Documentation/Makefile includes and
> then you could run 'make -C Documentation' in a fresh clone
> or tarball and get docs built with the defaults set for each
> platform.

I think it shouldn't go into config.mak.uname, since the idea there was
to keep the long list of platform defaults separate from other logic
(the Makefile is already long enough!). So I'm basically proposing the
same thing but in its own file. :)

-Peff

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

[Jeff King]

On Wed, Jun 27, 2018 at 12:44:43PM -0400, Todd Zullinger wrote:

> I wrote:
> > Jeff King wrote:
> >>      (Related, there's a build target in the local Makefile for using
> >>      asciidoctor; does it need updated, too?)
> > 
> > I didn't test asciidoctor specficially, but it also respects
> > the ASCIIDOC_EXTRA parameters, so I think it will work just
> > as well.  I'll try to confirm that later today.
> 
> Testing confirmed that asciidoctor works fine with this as
> well.

Thanks for checking.

> Somewhat tangentially, I looked at using asciidoctor for the
> Fedora packages last year and one issue that kept me from
> using it then was the '[FIXME: source]' it includes in the
> footer of the manpage.  When I dug into it at the time, it
> appeared this was due to no <refmiscinfo> declaration
> (similarly missing for manual, and version).  It wasn't
> clear whether it was possible to include a custom header
> template in plain asciidoctor.  I got the impression that it
> would require using a custom backend, which in turn required
> the rubygem 'tilt' for processing.
> 
> I spent about an hour poking around with it and decided that
> I'd put off building with asciidoctor until that was fixed.
> I felt that displaying '[FIXME: source]' wass worse than
> simply not including the version.
> 
> It's always possible that I was doing something wrong in my
> use of asciidoctor (I just set USE_ASCIIDOCTOR).  Or maybe
> the Fedora packages are missing some dependency which I
> missed.

Hmm. I don't typically use asciidoctor locally (to be honest, I do not
typically build the documentation at all locally, and just read the
source when I need it). But just setting USE_ASCIIDOCTOR seems to work
fine for me out of the box. I'm on Debian unstable, asciidoctor 1.5.7.1.

At this point I think we still consider the original asciidoc as our
officially supported platform, and mostly are happy if things also work
with asciidoctor. But my impression is that there's no more development
work happening on asciidoc, and the path forward will be asciidoctor. So
at some point we may need to flip that.

One nice thing about switching to asciidoctor fully is that it can do
direct manpage generation. So we could eventually drop the docbook/xmlto
dependencies (right now even with USE_ASCIIDOCTOR we still go through
the xml step).

> It might also be that we need some adjustments similar to
> https://patchwork.kernel.org/patch/10360207/ to get the
> mansource attribute passed on to asciidoctor.  I only just
> ran across that patch and haven't had a chance to test
> sometime similar in the git manpage build.  That looks
> promising though.

Yeah, we have to do similar tricks on git-scm.com to handle things
like linkgit. Our implementation there is quite horrible (regex search
and replace!). It would be wonderful if we could write real ruby
snippets to handle extended cases, and then the git-scm.com doc builder
could just reuse that logic instead of hackily reimplementing it.

Anyway, that's all well outside the scope of your patch today, I think.
:)

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

[Jeff King]

On Wed, Jun 27, 2018 at 04:58:43PM -0400, Todd Zullinger wrote:

> I tend to think that the default should be to build
> documentation that is accurate for that build, but since
> it's something I'll set once for my package builds it's not
> a big deal either way to me.

To be clear, I think so, too. I'd just like to have a single knob that
generic builds can set so that:

  - the decision is only "is this generic", and the exact generic text
    is still inside the source files

  - it would cover this case and similar cases going forward

-Peff

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

[Todd Zullinger]

Jeff King wrote:
> We could get rid around that by using $(DOC_ETC_GITCONFIG) or something,
> with:
> 
>   DOC_ETC_GITCONFIG ?= $(ETC_GITCONFIG)
> 
> in the Makefile. But that still leaves the choice of which generic text
> to use up to the caller. Maybe we should provide more guidance.
> 
> I.e., provide a knob like DOC_GENERIC that fills in generic values for
> these values (and maybe some others; it sounds like we have some
> existing problem cases).

That sounds pretty reasonable.  I have something
implementing this below.

>> It might be enough if the default values are relatively sane
>> and consistent.  That would be a slight improvement over the
>> current situation still.
> 
> Yeah. Taking a step back from the implementation questions, I think
> "$(prefix)/etc/gitconfig" is not very helpful text. I'd be happy to see
> us come up with a generic way of saying that which is more
> comprehensible to end-users. Your patches side-step that by filling in
> the real value, but unfortunately we can't do that everywhere. :)
> 
> There may not be a good "token" value, though. I.e., we may need to have
> two sets of verbiage: the specific one, and the generic one.

Yeah.  About the best generic term I can come up with is
using '$sysconfdir'.  But I have no idea if that's something
most readers will recognize as a placeholder for something
like /etc.

A number of the path references are in the FILES sections of
the man pages.  It might not be much of an improvement if we
try to stuff too much text in those references.  Perhaps if
those used '$sysconfdir/gitconfig' a subsequent note could
expand on that?  It could even be wrapped in an ifdef
similar to that used for the default editor/pager.

I don't want to make the plain .txt files significantly less
readable in the process, of course.

>>> 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?
>> 
>> Yeah, maybe.  I didn't like the duplication either, but as
>> you noticed, we do it already for many of the other
>> variables.  I suspect we could put these defaults into
>> config.mak.uname which Documentation/Makefile includes and
>> then you could run 'make -C Documentation' in a fresh clone
>> or tarball and get docs built with the defaults set for each
>> platform.
> 
> I think it shouldn't go into config.mak.uname, since the idea there was
> to keep the long list of platform defaults separate from other logic
> (the Makefile is already long enough!). So I'm basically proposing the
> same thing but in its own file. :)

Ahh, something that the top-level Makefile would create and
then subdir Makefiles would include, perhaps similar to the
way GIT-VERSION-FILE is updated and included?  That could
prove useful to some of the tools in contrib which duplicate
logic.

Skipping that larger de-duplication cleanup, here's a stab
at implementing the DOC_GENERIC knob (and the DOC_ overrides
for ETC_GIT(CONFIG|ATTRIBUTES).  The defaults with
'/GENERIC-SYSCONFDIR' in them are just placeholders waiting
for a better name. :)

Similarly, the use of {etc-git(config|attributes)} as the
attribute for the replacements could likely be improved for
readers of the .txt files.  {system-wide-gitconfig} is
likely better.  Maybe the default for the generic paths
could be /system-wide/git(config|attributes) too (or in
CAPS to make it more obviously a placeholder)?

Thanks for thinking this through and providing some good
directions to work on!

-- >8 --
Subject: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs

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.

It's also more consistent than sometimes using `$(prefix)/etc/gitconfig`
and other times using `/etc/gitconfig` to refer to the system-wide
config file.

Update the SYNOPSIS of gitattributes(5) to include the system-wide
config file as well.

Support building generic documentation with a DOC_GENERIC Makefile knob.
The default generic paths may be further customized via the
DOC_ETC_GITCONFIG and DOC_ETC_GITATTRIBUTES variables.

Define DOC_GENERIC in dist-doc make target to ensure generic paths are
used in the generated html and manpage tarballs.

Helped-by: Jeff King <peff@peff.net>
Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
 Documentation/Makefile          | 22 ++++++++++++++++++++++
 Documentation/config.txt        |  4 ++--
 Documentation/git-config.txt    | 10 +++++-----
 Documentation/git.txt           |  4 ++--
 Documentation/gitattributes.txt |  4 ++--
 Makefile                        | 10 ++++++++--
 6 files changed, 41 insertions(+), 13 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d079d7c73..2b3540a6c 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,27 @@ DEFAULT_EDITOR_SQ = $(subst ','\'',$(DEFAULT_EDITOR))
 ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'
 endif
 
+ifndef ETC_GITCONFIG
+ETC_GITCONFIG = $(sysconfdir)/gitconfig
+endif
+ifndef ETC_GITATTRIBUTES
+ETC_GITATTRIBUTES = $(sysconfdir)/gitattributes
+endif
+
+ifndef DOC_GENERIC
+DOC_ETC_GITCONFIG ?= $(ETC_GITCONFIG)
+DOC_ETC_GITATTRIBUTES ?= $(ETC_GITATTRIBUTES)
+else
+DOC_ETC_GITCONFIG ?= /GENERIC-SYSCONFDIR/gitconfig
+DOC_ETC_GITATTRIBUTES ?= /GENERIC-SYSCONFDIR/gitattributes
+endif
+
+DOC_ETC_GITCONFIG_SQ = $(subst ','\'',$(DOC_ETC_GITCONFIG))
+ASCIIDOC_EXTRA += -a 'etc-gitconfig=$(DOC_ETC_GITCONFIG_SQ)'
+
+DOC_ETC_GITATTRIBUTES_SQ = $(subst ','\'',$(DOC_ETC_GITATTRIBUTES))
+ASCIIDOC_EXTRA += -a 'etc-gitattributes=$(DOC_ETC_GITATTRIBUTES_SQ)'
+
 QUIET_SUBDIR0  = +$(MAKE) -C # space to separate -C and subdir
 QUIET_SUBDIR1  =
 
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1cc18a828..ed903b60b 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}+
 can be used to store a system-wide default configuration.
 
 The configuration variables are used by both the Git plumbing
@@ -2815,7 +2815,7 @@ configuration files (e.g. `$HOME/.gitconfig`).
 
 Example:
 
-/etc/gitconfig
+{etc-gitconfig}
   push.pushoption = a
   push.pushoption = b
 
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 18ddc78f4..0d5ea5b58 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -114,10 +114,10 @@ See also <<FILES>>.
 
 --system::
 	For writing options: write to system-wide
-	`$(prefix)/etc/gitconfig` rather than the repository
+	+{etc-gitconfig}+ rather than the repository
 	`.git/config`.
 +
-For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
+For reading options: read only from system-wide +{etc-gitconfig}+
 rather than from all available files.
 +
 See also <<FILES>>.
@@ -263,7 +263,7 @@ FILES
 If not set explicitly with `--file`, there are four files where
 'git config' will search for configuration options:
 
-$(prefix)/etc/gitconfig::
+{etc-gitconfig}::
 	System-wide configuration file.
 
 $XDG_CONFIG_HOME/git/config::
@@ -310,11 +310,11 @@ ENVIRONMENT
 GIT_CONFIG::
 	Take the configuration from the given file instead of .git/config.
 	Using the "--global" option forces this to ~/.gitconfig. Using the
-	"--system" option forces this to $(prefix)/etc/gitconfig.
+	"--system" option forces this to {etc-gitconfig}.
 
 GIT_CONFIG_NOSYSTEM::
 	Whether to skip reading settings from the system-wide
-	$(prefix)/etc/gitconfig file. See linkgit:git[1] for details.
+	{etc-gitconfig} file. See linkgit:git[1] for details.
 
 See also <<FILES>>.
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index dba7f0c18..6a4646f99 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -567,10 +567,10 @@ for further details.
 
 `GIT_CONFIG_NOSYSTEM`::
 	Whether to skip reading settings from the system-wide
-	`$(prefix)/etc/gitconfig` file.  This environment variable can
+	+{etc-gitconfig}+ file.  This environment variable can
 	be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
 	predictable environment for a picky script, or you can set it
-	temporarily to avoid using a buggy `/etc/gitconfig` file while
+	temporarily to avoid using a buggy +{etc-gitconfig}+ file while
 	waiting for someone with sufficient permissions to fix it.
 
 `GIT_FLUSH`::
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 92010b062..528de4259 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -7,7 +7,7 @@ gitattributes - Defining attributes per path
 
 SYNOPSIS
 --------
-$GIT_DIR/info/attributes, .gitattributes
+{etc-gitattributes}, $GIT_DIR/info/attributes, .gitattributes
 
 
 DESCRIPTION
@@ -93,7 +93,7 @@ for a single user should be placed in a file specified by the
 Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME
 is either not set or empty, $HOME/.config/git/attributes is used instead.
 Attributes for all users on a system should be placed in the
-`$(prefix)/etc/gitattributes` file.
++{etc-gitattributes}+ file.
 
 Sometimes you would need to override a setting of an attribute
 for a path to `Unspecified` state.  This can be done by listing
diff --git a/Makefile b/Makefile
index 0cb6590f2..f476a6eb5 100644
--- a/Makefile
+++ b/Makefile
@@ -292,6 +292,11 @@ all::
 # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
 # Extensions Lab if you have it available.
 #
+# Define DOC_GENERIC if you're building documentation for a general audience and
+# do not want paths such as ETC_GITCONFIG and ETC_GITATTRIBUTES to be expanded.
+# Define DOC_ETC_GITCONFIG and DOC_ETC_GITATTRIBUTES to override the generic
+# defaults used for those paths.
+#
 # Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).
 #
 # Define NO_PERL if you do not want Perl scripts or libraries at all.
@@ -2870,13 +2875,14 @@ manpages = git-manpages-$(GIT_VERSION)
 dist-doc:
 	$(RM) -r .doc-tmp-dir
 	mkdir .doc-tmp-dir
-	$(MAKE) -C Documentation WEBDOC_DEST=../.doc-tmp-dir install-webdoc
+	$(MAKE) -C Documentation DOC_GENERIC=1 WEBDOC_DEST=../.doc-tmp-dir \
+		install-webdoc
 	cd .doc-tmp-dir && $(TAR) cf ../$(htmldocs).tar .
 	gzip -n -9 -f $(htmldocs).tar
 	:
 	$(RM) -r .doc-tmp-dir
 	mkdir -p .doc-tmp-dir/man1 .doc-tmp-dir/man5 .doc-tmp-dir/man7
-	$(MAKE) -C Documentation DESTDIR=./ \
+	$(MAKE) -C Documentation DESTDIR=./ DOC_GENERIC=1 \
 		man1dir=../.doc-tmp-dir/man1 \
 		man5dir=../.doc-tmp-dir/man5 \
 		man7dir=../.doc-tmp-dir/man7 \

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Thanks, for a country where nobody is allowed to mind his own
business. Thanks, for a nation of finks.
    -- William S. Burroughs, A Thanksgiving Prayer

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

[Jeff King]

On Thu, Jun 28, 2018 at 12:36:06PM -0400, Todd Zullinger wrote:

> >> It might be enough if the default values are relatively sane
> >> and consistent.  That would be a slight improvement over the
> >> current situation still.
> > 
> > Yeah. Taking a step back from the implementation questions, I think
> > "$(prefix)/etc/gitconfig" is not very helpful text. I'd be happy to see
> > us come up with a generic way of saying that which is more
> > comprehensible to end-users. Your patches side-step that by filling in
> > the real value, but unfortunately we can't do that everywhere. :)
> > 
> > There may not be a good "token" value, though. I.e., we may need to have
> > two sets of verbiage: the specific one, and the generic one.
> 
> Yeah.  About the best generic term I can come up with is
> using '$sysconfdir'.  But I have no idea if that's something
> most readers will recognize as a placeholder for something
> like /etc.

I don't that's much better than $(prefix). It's at least _correct_ more
often, but unless you're used to autotools conventions, it's pretty
obscure. Can we just say "the system configuration direction (e.g.,
/etc)" or something like that?

That definitely requires doing some kind of ifdef in the asciidoc
source, but I think the end result will be much more comprehensible to
end users. And IMHO the readability hit to the source is not too bad (at
least I don't find the DEFAULT_PAGER one to be).

Something like this:

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 18ddc78f42..ab20dd5235 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -113,13 +113,16 @@ For reading options: read only from global `~/.gitconfig` and from
 See also <<FILES>>.
 
 --system::
-	For writing options: write to system-wide
-	`$(prefix)/etc/gitconfig` rather than the repository
-	`.git/config`.
+	For writing options: write to the system-wide gitconfig file
+	rather then the repository config.
 +
-For reading options: read only from system-wide `$(prefix)/etc/gitconfig`
+For reading options: read only from system-wide gitconfig file
 rather than from all available files.
 +
+The exact location of the system-wide file is configured when Git is
+built.
+ifdef::git-doc-generic[In many builds, it is `/etc/gitconfig`.]
+ifndef::git-doc-generic[In your build, it is +{etc-gitconfig}+.]
 See also <<FILES>>.
 
 --local::

Though I would also be happy if we simply said "system-wide gitconfig"
here and then had the conditional part in FILES.

I'd actually argue that all of the "source" options should be grouped,
like:

  --local::
  --global::
  --system::
  --file=<file>::
	When writing, write to the repository-local, user-global, or
	system-wide configuration file (or any `<file>` you specify).
	When reading, read from a specific file rather than from all
	available files. See <<FILES> below for more details.

And then let <<FILES>> describe in prose the various files, where they
might be, etc. That also cleans up the `.git/config` thing, which is a
mild fiction (it is really `$GIT_DIR/config`).

> A number of the path references are in the FILES sections of
> the man pages.  It might not be much of an improvement if we
> try to stuff too much text in those references.  Perhaps if
> those used '$sysconfdir/gitconfig' a subsequent note could
> expand on that?  It could even be wrapped in an ifdef
> similar to that used for the default editor/pager.

So yeah, I think I am arguing along the same lines, but just saying
"system-wide gitconfig" or similar instead of $sysconfdir/gitconfig. I
think the English is a little less daunting.

> > I think it shouldn't go into config.mak.uname, since the idea there was
> > to keep the long list of platform defaults separate from other logic
> > (the Makefile is already long enough!). So I'm basically proposing the
> > same thing but in its own file. :)
> 
> Ahh, something that the top-level Makefile would create and
> then subdir Makefiles would include, perhaps similar to the
> way GIT-VERSION-FILE is updated and included?  That could
> prove useful to some of the tools in contrib which duplicate
> logic.

No, I had just envisioned it would be a static file, like
config.mak.paths or something. I'm literally just trying to break out
bits of our Makefile into bite-sized files so they're easier look at.

> Skipping that larger de-duplication cleanup, here's a stab
> at implementing the DOC_GENERIC knob (and the DOC_ overrides
> for ETC_GIT(CONFIG|ATTRIBUTES).  The defaults with
> '/GENERIC-SYSCONFDIR' in them are just placeholders waiting
> for a better name. :)

So obviously I like the direction of this patch, but if you agree with
my line of thinking above you'd need to turn DOC_GENERIC into an
attribute and use in-source conditionals. Hopefully you do agree. :)

> Thanks for thinking this through and providing some good
> directions to work on!

Thank you for working on it! I was thinking about this because of the
response I wrote in:

  https://public-inbox.org/git/20180626124316.GA15419@sigill.intra.peff.net/

If you're interested, this could all be rolled into a cleanup series.
But if not, I can wait for this to resolve and then build on top.

-Peff