{"thread":{"id":"48786","subject":"[PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","startedAt":"2018-06-27T04:56:42Z","lastAt":"2018-06-28T18:16:34Z","messageCount":11,"participants":["Todd Zullinger","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"351061","messageId":"20180627045637.13818-1-tmz@pobox.com","threadId":"48786","inReplyTo":null,"subject":"[PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2018-06-27T04:56:37Z","receivedAt":"2018-06-27T04:56:42Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Replace `$(prefix)/etc/gitconfig` and `$(prefix)/etc/gitattributes` in\ngenerated documentation with the paths chosen when building. Readers of\nthe documentation should not need to know how `$(prefix)` was defined.\n\nIt's also more consistent than sometimes using `$(prefix)/etc/gitconfig`\nand other times using `/etc/gitconfig` to refer to the system-wide\nconfig file.\n\nUpdate the SYNOPSIS of gitattributes(5) to include the system-wide\nconfig file as well.\n\nSigned-off-by: Todd Zullinger \n---\nI noticed this while looking to update gitattributes.txt to\nnote the system-wide config file. I tested with and without\nRUNTIME_PREFIX as well as make gitattributes.5 from within\nDocumentation. I believe all methods do the right thing.\n\nI couldn't figure out a good way to have asciidoc expand the\nattributes inside of a \"`\" literal, so I changed to the \"+\"\nform. There might be a better way to do this, passing subs=\nin asciidoc.conf, but I wasn't clear on where that would\nfit. I tested with asciidoc and not asciidoctor.\n\n Documentation/Makefile | 13 +++++++++++++\n Documentation/config.txt | 4 ++--\n Documentation/git-config.txt | 10 +++++-----\n Documentation/git.txt | 4 ++--\n Documentation/gitattributes.txt | 4 ++--\n 5 files changed, 24 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d079d7c73a..75af671798 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -95,6 +95,7 @@ DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))\n \n prefix ?= $(HOME)\n bindir ?= $(prefix)/bin\n+sysconfdir ?= $(prefix)/etc\n htmldir ?= $(prefix)/share/doc/git-doc\n infodir ?= $(prefix)/share/info\n pdfdir ?= $(prefix)/share/doc/git-doc\n@@ -205,6 +206,18 @@ DEFAULT_EDITOR_SQ = $(subst ','\\'',$(DEFAULT_EDITOR))\n ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'\n endif\n \n+ifndef ETC_GITCONFIG\n+ETC_GITCONFIG = $(sysconfdir)/gitconfig\n+endif\n+ETC_GITCONFIG_SQ = $(subst ','\\'',$(ETC_GITCONFIG))\n+ASCIIDOC_EXTRA += -a 'etc-gitconfig=$(ETC_GITCONFIG_SQ)'\n+\n+ifndef ETC_GITATTRIBUTES\n+ETC_GITATTRIBUTES = $(sysconfdir)/gitattributes\n+endif\n+ETC_GITATTRIBUTES_SQ = $(subst ','\\'',$(ETC_GITATTRIBUTES))\n+ASCIIDOC_EXTRA += -a 'etc-gitattributes=$(ETC_GITATTRIBUTES_SQ)'\n+\n QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir\n QUIET_SUBDIR1 =\n \ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 1cc18a828c..ed903b60bd 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -5,7 +5,7 @@ The Git configuration file contains a number of variables that affect\n the Git commands' behavior. The `.git/config` file in each repository\n is used to store the configuration for that repository, and\n `$HOME/.gitconfig` is used to store a per-user configuration as\n-fallback values for the `.git/config` file. The file `/etc/gitconfig`\n+fallback values for the `.git/config` file. The file +{etc-gitconfig}+\n can be used to store a system-wide default configuration.\n \n The configuration variables are used by both the Git plumbing\n@@ -2815,7 +2815,7 @@ configuration files (e.g. `$HOME/.gitconfig`).\n \n Example:\n \n-/etc/gitconfig\n+{etc-gitconfig}\n push.pushoption = a\n push.pushoption = b\n \ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 18ddc78f42..0d5ea5b58e 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -114,10 +114,10 @@ See also <>.\n \n --system::\n \tFor writing options: write to system-wide\n-\t`$(prefix)/etc/gitconfig` rather than the repository\n+\t+{etc-gitconfig}+ rather than the repository\n \t`.git/config`.\n +\n-For reading options: read only from system-wide `$(prefix)/etc/gitconfig`\n+For reading options: read only from system-wide +{etc-gitconfig}+\n rather than from all available files.\n +\n See also <>.\n@@ -263,7 +263,7 @@ FILES\n If not set explicitly with `--file`, there are four files where\n 'git config' will search for configuration options:\n \n-$(prefix)/etc/gitconfig::\n+{etc-gitconfig}::\n \tSystem-wide configuration file.\n \n $XDG_CONFIG_HOME/git/config::\n@@ -310,11 +310,11 @@ ENVIRONMENT\n GIT_CONFIG::\n \tTake the configuration from the given file instead of .git/config.\n \tUsing the \"--global\" option forces this to ~/.gitconfig. Using the\n-\t\"--system\" option forces this to $(prefix)/etc/gitconfig.\n+\t\"--system\" option forces this to {etc-gitconfig}.\n \n GIT_CONFIG_NOSYSTEM::\n \tWhether to skip reading settings from the system-wide\n-\t$(prefix)/etc/gitconfig file. See linkgit:git[1] for details.\n+\t{etc-gitconfig} file. See linkgit:git[1] for details.\n \n See also <>.\n \ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex dba7f0c18e..6a4646f991 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -567,10 +567,10 @@ for further details.\n \n `GIT_CONFIG_NOSYSTEM`::\n \tWhether to skip reading settings from the system-wide\n-\t`$(prefix)/etc/gitconfig` file. This environment variable can\n+\t+{etc-gitconfig}+ file. This environment variable can\n \tbe used along with `$HOME` and `$XDG_CONFIG_HOME` to create a\n \tpredictable environment for a picky script, or you can set it\n-\ttemporarily to avoid using a buggy `/etc/gitconfig` file while\n+\ttemporarily to avoid using a buggy +{etc-gitconfig}+ file while\n \twaiting for someone with sufficient permissions to fix it.\n \n `GIT_FLUSH`::\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex 92010b062e..528de42593 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -7,7 +7,7 @@ gitattributes - Defining attributes per path\n \n SYNOPSIS\n --------\n-$GIT_DIR/info/attributes, .gitattributes\n+{etc-gitattributes}, $GIT_DIR/info/attributes, .gitattributes\n \n \n DESCRIPTION\n@@ -93,7 +93,7 @@ for a single user should be placed in a file specified by the\n Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME\n is either not set or empty, $HOME/.config/git/attributes is used instead.\n Attributes for all users on a system should be placed in the\n-`$(prefix)/etc/gitattributes` file.\n++{etc-gitattributes}+ file.\n \n Sometimes you would need to override a setting of an attribute\n for a path to `Unspecified` state. This can be done by listing\n-- \n2.18.0\n\n"},{"id":"351110","messageId":"20180627141430.GA13904@sigill.intra.peff.net","threadId":"48786","inReplyTo":"20180627045637.13818-1-tmz@pobox.com","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-06-27T14:14:30Z","receivedAt":"2018-06-27T14:14:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jun 27, 2018 at 12:56:37AM -0400, Todd Zullinger wrote:\n\n> Replace `$(prefix)/etc/gitconfig` and `$(prefix)/etc/gitattributes` in\n> generated documentation with the paths chosen when building. Readers of\n> the documentation should not need to know how `$(prefix)` was defined.\n\nYes, I was just complaining about this yesterday. Besides readers not\nhaving any clue what $(prefix) means here, $(prefix)/etc is not even\ncorrect for builds with prefix=/usr.\n\nSo I like the overall direction here, but it leaves me with one\nquestion: what happens for documentation outside of customized builds?\n\nSpecifically, I'm thinking of:\n\n 1. The pre-built documentation that Junio builds for\n quick-install-doc. This _could_ be customized during the \"quick\"\n step, but it's probably not worth the effort. However, we'd want\n some kind of generic fill-in then, and hopefully not\n \"/home/jch/etc\" or something.\n\n 2. The manpages on git-scm.com, which are built with asciidoctor. I\n think we'd want the same generic value there. Ideally it would be\n embedded in the asciidoc source as \"if this attribute isn't\n defined, then use this\", but it's not the end of the world to\n require a patch to the site to handle this.\n\n (Related, there's a build target in the local Makefile for using\n asciidoctor; does it need updated, too?)\n\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index d079d7c73a..75af671798 100644\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -95,6 +95,7 @@ DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))\n> \n> prefix ?= $(HOME)\n> bindir ?= $(prefix)/bin\n> +sysconfdir ?= $(prefix)/etc\n> htmldir ?= $(prefix)/share/doc/git-doc\n> infodir ?= $(prefix)/share/info\n> pdfdir ?= $(prefix)/share/doc/git-doc\n> @@ -205,6 +206,18 @@ DEFAULT_EDITOR_SQ = $(subst ','\\'',$(DEFAULT_EDITOR))\n> ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'\n> endif\n> \n> +ifndef ETC_GITCONFIG\n> +ETC_GITCONFIG = $(sysconfdir)/gitconfig\n> +endif\n> +ETC_GITCONFIG_SQ = $(subst ','\\'',$(ETC_GITCONFIG))\n> +ASCIIDOC_EXTRA += -a 'etc-gitconfig=$(ETC_GITCONFIG_SQ)'\n> +\n> +ifndef ETC_GITATTRIBUTES\n> +ETC_GITATTRIBUTES = $(sysconfdir)/gitattributes\n> +endif\n> +ETC_GITATTRIBUTES_SQ = $(subst ','\\'',$(ETC_GITATTRIBUTES))\n> +ASCIIDOC_EXTRA += -a 'etc-gitattributes=$(ETC_GITATTRIBUTES_SQ)'\n> +\n\nIt's a shame we have to repeat this logic from the Makefile, though I\nguess we already do so for prefix, bindir, etc, so far.\n\nShould we factor the path logic from the top-level Makefile into an\ninclude that can be used from either?\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index 1cc18a828c..ed903b60bd 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -5,7 +5,7 @@ The Git configuration file contains a number of variables that affect\n> the Git commands' behavior. The `.git/config` file in each repository\n> is used to store the configuration for that repository, and\n> `$HOME/.gitconfig` is used to store a per-user configuration as\n> -fallback values for the `.git/config` file. The file `/etc/gitconfig`\n> +fallback values for the `.git/config` file. The file +{etc-gitconfig}+\n\nI think the formatting tweak you've done here is the right thing.\nThere's no way to expand within literal backticks (since that's the\npoint). So we only care about the monospacing effect, which ++ should\ngive.\n\n-Peff\n"},{"id":"351113","messageId":"20180627150352.GJ20217@zaya.teonanacatl.net","threadId":"48786","inReplyTo":"20180627141430.GA13904@sigill.intra.peff.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2018-06-27T15:03:52Z","receivedAt":"2018-06-27T15:03:59Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Jeff King wrote:\n> On Wed, Jun 27, 2018 at 12:56:37AM -0400, Todd Zullinger wrote:\n> \n>> Replace `$(prefix)/etc/gitconfig` and `$(prefix)/etc/gitattributes` in\n>> generated documentation with the paths chosen when building. Readers of\n>> the documentation should not need to know how `$(prefix)` was defined.\n> \n> Yes, I was just complaining about this yesterday.\n\nSo what you're saying is that if I had procrastinated a\nlittle, you may have written such a patch for me? :)\n\n> Besides readers not\n> having any clue what $(prefix) means here, $(prefix)/etc is not even\n> correct for builds with prefix=/usr.\n>\n> So I like the overall direction here, but it leaves me with one\n> question: what happens for documentation outside of customized builds?\n> \n> Specifically, I'm thinking of:\n> \n> 1. The pre-built documentation that Junio builds for\n> quick-install-doc. This _could_ be customized during the \"quick\"\n> step, but it's probably not worth the effort. However, we'd want\n> some kind of generic fill-in then, and hopefully not\n> \"/home/jch/etc\" or something.\n\nIf building docs separately for such a use, the values can\nbe overridden by setting ETC_GITCONFIG and ETC_GITATTRIBUTES\n(or prefix or sysconfig). To keep the same values as we\ncurrently use, for example:\n\n make -C Documentation V=1 \\\n ETC_GITCONFIG='$$(prefix)/etc/gitconfig' \\\n ETC_GITATTRIBUTES='$$(prefix)/etc/gitattributes'\n\nI don't know if that's sufficient for folks who build\ndocumentation to share with a general audience or not.\n\nIt might be enough if the default values are relatively sane\nand consistent. That would be a slight improvement over the\ncurrent situation still.\n\n> 2. The manpages on git-scm.com, which are built with asciidoctor. I\n> think we'd want the same generic value there. Ideally it would be\n> embedded in the asciidoc source as \"if this attribute isn't\n> defined, then use this\", but it's not the end of the world to\n> require a patch to the site to handle this.\n\nWe have that for the DEFAULT_(EDITOR|PAGER). I didn't know\nif we'd want that here, but maybe it's worth the effort if\nit helps when building docs destined for the website and\nsuch. It might make the plain text files a bit less\nreadable though.\n\nThe EDITOR/PAGER bits are in git-var.txt, like this:\n\n GIT_EDITOR::\n Text editor for use by Git commands. The value is meant to be\n interpreted by the shell when it is used. Examples: `~/bin/vi`,\n `$SOME_ENVIRONMENT_VARIABLE`, `\"C:\\Program Files\\Vim\\gvim.exe\"\n --nofork`. The order of preference is the `$GIT_EDITOR`\n environment variable, then `core.editor` configuration, then\n `$VISUAL`, then `$EDITOR`, and then the default chosen at compile\n time, which is usually 'vi'.\n ifdef::git-default-editor[]\n The build you are using chose '{git-default-editor}' as the default.\n endif::git-default-editor[]\n\nThe ifdef would be a little different to set the var if it\nwas not set, of course.\n\nI think if we ensure that ETC_GITCONFIG / ETC_GITATTRIBUTES\nare set sanely by default (and easily overridden) then we\ncan probably avoid the need to handle it within the asciidoc\nfile though. (There's more on that though below.)\n\n> (Related, there's a build target in the local Makefile for using\n> asciidoctor; does it need updated, too?)\n\nI didn't test asciidoctor specficially, but it also respects\nthe ASCIIDOC_EXTRA parameters, so I think it will work just\nas well. I'll try to confirm that later today.\n\n>> diff --git a/Documentation/Makefile b/Documentation/Makefile\n>> index d079d7c73a..75af671798 100644\n>> --- a/Documentation/Makefile\n>> +++ b/Documentation/Makefile\n>> @@ -95,6 +95,7 @@ DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))\n>> \n>> prefix ?= $(HOME)\n>> bindir ?= $(prefix)/bin\n>> +sysconfdir ?= $(prefix)/etc\n>> htmldir ?= $(prefix)/share/doc/git-doc\n>> infodir ?= $(prefix)/share/info\n>> pdfdir ?= $(prefix)/share/doc/git-doc\n>> @@ -205,6 +206,18 @@ DEFAULT_EDITOR_SQ = $(subst ','\\'',$(DEFAULT_EDITOR))\n>> ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'\n>> endif\n>> \n>> +ifndef ETC_GITCONFIG\n>> +ETC_GITCONFIG = $(sysconfdir)/gitconfig\n>> +endif\n>> +ETC_GITCONFIG_SQ = $(subst ','\\'',$(ETC_GITCONFIG))\n>> +ASCIIDOC_EXTRA += -a 'etc-gitconfig=$(ETC_GITCONFIG_SQ)'\n>> +\n>> +ifndef ETC_GITATTRIBUTES\n>> +ETC_GITATTRIBUTES = $(sysconfdir)/gitattributes\n>> +endif\n>> +ETC_GITATTRIBUTES_SQ = $(subst ','\\'',$(ETC_GITATTRIBUTES))\n>> +ASCIIDOC_EXTRA += -a 'etc-gitattributes=$(ETC_GITATTRIBUTES_SQ)'\n>> +\n> \n> It's a shame we have to repeat this logic from the Makefile, though I\n> guess we already do so for prefix, bindir, etc, so far.\n> \n> Should we factor the path logic from the top-level Makefile into an\n> include that can be used from either?\n\nYeah, maybe. I didn't like the duplication either, but as\nyou noticed, we do it already for many of the other\nvariables. I suspect we could put these defaults into\nconfig.mak.uname which Documentation/Makefile includes and\nthen you could run 'make -C Documentation' in a fresh clone\nor tarball and get docs built with the defaults set for each\nplatform.\n\n>> diff --git a/Documentation/config.txt b/Documentation/config.txt\n>> index 1cc18a828c..ed903b60bd 100644\n>> --- a/Documentation/config.txt\n>> +++ b/Documentation/config.txt\n>> @@ -5,7 +5,7 @@ The Git configuration file contains a number of variables that affect\n>> the Git commands' behavior. The `.git/config` file in each repository\n>> is used to store the configuration for that repository, and\n>> `$HOME/.gitconfig` is used to store a per-user configuration as\n>> -fallback values for the `.git/config` file. The file `/etc/gitconfig`\n>> +fallback values for the `.git/config` file. The file +{etc-gitconfig}+\n> \n> I think the formatting tweak you've done here is the right thing.\n> There's no way to expand within literal backticks (since that's the\n> point). So we only care about the monospacing effect, which ++ should\n> give.\n\nThanks. It took me longer to decide that I couldn't find a\nclean way to do it without using ++ than anything else. :)\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nNo one ever went broke underestimating the taste of the American\npublic.\n -- H. L. Mencken\n\n"},{"id":"351119","messageId":"20180627164443.GK20217@zaya.teonanacatl.net","threadId":"48786","inReplyTo":"20180627150352.GJ20217@zaya.teonanacatl.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2018-06-27T16:44:43Z","receivedAt":"2018-06-27T16:44:49Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"I wrote:\n> Jeff King wrote:\n>> (Related, there's a build target in the local Makefile for using\n>> asciidoctor; does it need updated, too?)\n> \n> I didn't test asciidoctor specficially, but it also respects\n> the ASCIIDOC_EXTRA parameters, so I think it will work just\n> as well. I'll try to confirm that later today.\n\nTesting confirmed that asciidoctor works fine with this as\nwell.\n\nSomewhat tangentially, I looked at using asciidoctor for the\nFedora packages last year and one issue that kept me from\nusing it then was the '[FIXME: source]' it includes in the\nfooter of the manpage. When I dug into it at the time, it\nappeared this was due to no declaration\n(similarly missing for manual, and version). It wasn't\nclear whether it was possible to include a custom header\ntemplate in plain asciidoctor. I got the impression that it\nwould require using a custom backend, which in turn required\nthe rubygem 'tilt' for processing.\n\nI spent about an hour poking around with it and decided that\nI'd put off building with asciidoctor until that was fixed.\nI felt that displaying '[FIXME: source]' wass worse than\nsimply not including the version.\n\nIt's always possible that I was doing something wrong in my\nuse of asciidoctor (I just set USE_ASCIIDOCTOR). Or maybe\nthe Fedora packages are missing some dependency which I\nmissed.\n\nIt might also be that we need some adjustments similar to\nhttps://patchwork.kernel.org/patch/10360207/ to get the\nmansource attribute passed on to asciidoctor. I only just\nran across that patch and haven't had a chance to test\nsometime similar in the git manpage build. That looks\npromising though.\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nWhy is it that we rejoice at a birth and grieve at a funeral? It is\nbecause we are not the person involved.\n -- Mark Twain\n\n"},{"id":"351120","messageId":"xmqqlgb0goui.fsf@gitster-ct.c.googlers.com","threadId":"48786","inReplyTo":"20180627141430.GA13904@sigill.intra.peff.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2018-06-27T16:45:41Z","receivedAt":"2018-06-27T16:45:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Specifically, I'm thinking of:\n>\n> 1. The pre-built documentation that Junio builds for\n> quick-install-doc. This _could_ be customized during the \"quick\"\n> step, but it's probably not worth the effort. However, we'd want\n> some kind of generic fill-in then, and hopefully not\n> \"/home/jch/etc\" or something.\n\nThat is very likely to happen, actually X-<.\n"},{"id":"351161","messageId":"20180627205843.GM20217@zaya.teonanacatl.net","threadId":"48786","inReplyTo":"xmqqlgb0goui.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2018-06-27T20:58:43Z","receivedAt":"2018-06-27T20:58:50Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Junio C Hamano wrote:\n> Jeff King writes:\n> \n>> Specifically, I'm thinking of:\n>>\n>> 1. The pre-built documentation that Junio builds for\n>> quick-install-doc. This _could_ be customized during the \"quick\"\n>> step, but it's probably not worth the effort. However, we'd want\n>> some kind of generic fill-in then, and hopefully not\n>> \"/home/jch/etc\" or something.\n> \n> That is very likely to happen, actually X-<.\n\nObviously, we don't want the end result to cause regressions\nin the common case or any burden on you. Would setting the\nETC_GIT(CONFIG|ATTRIBUTES) variables in the dist-doc target\nalleviate that concern?\n\nAlternately, we can make the default use generic paths and\nrequire some other knob to enable substituting the actual\npaths when building documentation.\n\nI tend to think that the default should be to build\ndocumentation that is accurate for that build, but since\nit's something I'll set once for my package builds it's not\na big deal either way to me.\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nEinstein argued that there must be simplified explanations of nature,\nbecause God is not capricious or arbitrary. No such faith comforts the\nsoftware engineer.\n -- Fred Brooks\n\n"},{"id":"351220","messageId":"20180628141556.GA15799@sigill.intra.peff.net","threadId":"48786","inReplyTo":"20180627150352.GJ20217@zaya.teonanacatl.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-06-28T14:15:57Z","receivedAt":"2018-06-28T14:16:03Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jun 27, 2018 at 11:03:52AM -0400, Todd Zullinger wrote:\n\n> So what you're saying is that if I had procrastinated a\n> little, you may have written such a patch for me? :)\n\nYes, but that's a dangerous game of chicken. :)\n\n> > 1. The pre-built documentation that Junio builds for\n> > quick-install-doc. This _could_ be customized during the \"quick\"\n> > step, but it's probably not worth the effort. However, we'd want\n> > some kind of generic fill-in then, and hopefully not\n> > \"/home/jch/etc\" or something.\n> \n> If building docs separately for such a use, the values can\n> be overridden by setting ETC_GITCONFIG and ETC_GITATTRIBUTES\n> (or prefix or sysconfig). To keep the same values as we\n> currently use, for example:\n> \n> make -C Documentation V=1 \\\n> ETC_GITCONFIG='$$(prefix)/etc/gitconfig' \\\n> ETC_GITATTRIBUTES='$$(prefix)/etc/gitattributes'\n> \n> I don't know if that's sufficient for folks who build\n> documentation to share with a general audience or not.\n\nOne downside is that this means the generic-doc builder has to put\nnonsense into ETC_GITCONFIG. That means it would be a bad idea to put\nthis into config.mak, for example, as it would break their regular\nbuild.\n\nWe could get rid around that by using $(DOC_ETC_GITCONFIG) or something,\nwith:\n\n DOC_ETC_GITCONFIG ?= $(ETC_GITCONFIG)\n\nin the Makefile. But that still leaves the choice of which generic text\nto use up to the caller. Maybe we should provide more guidance.\n\nI.e., provide a knob like DOC_GENERIC that fills in generic values for\nthese values (and maybe some others; it sounds like we have some\nexisting problem cases).\n\n> It might be enough if the default values are relatively sane\n> and consistent. That would be a slight improvement over the\n> current situation still.\n\nYeah. Taking a step back from the implementation questions, I think\n\"$(prefix)/etc/gitconfig\" is not very helpful text. I'd be happy to see\nus come up with a generic way of saying that which is more\ncomprehensible to end-users. Your patches side-step that by filling in\nthe real value, but unfortunately we can't do that everywhere. :)\n\nThere may not be a good \"token\" value, though. I.e., we may need to have\ntwo sets of verbiage: the specific one, and the generic one.\n\n> The EDITOR/PAGER bits are in git-var.txt, like this:\n> \n> GIT_EDITOR::\n> Text editor for use by Git commands. The value is meant to be\n> interpreted by the shell when it is used. Examples: `~/bin/vi`,\n> `$SOME_ENVIRONMENT_VARIABLE`, `\"C:\\Program Files\\Vim\\gvim.exe\"\n> --nofork`. The order of preference is the `$GIT_EDITOR`\n> environment variable, then `core.editor` configuration, then\n> `$VISUAL`, then `$EDITOR`, and then the default chosen at compile\n> time, which is usually 'vi'.\n> ifdef::git-default-editor[]\n> The build you are using chose '{git-default-editor}' as the default.\n> endif::git-default-editor[]\n> \n> The ifdef would be a little different to set the var if it\n> was not set, of course.\n\nThanks, I didn't know about those cases. The git-scm.com version gets\nthat right, because we don't set DEFAULT_* there. I wondered if we might\nhave problems with other generic builds since we do have defaults for\nthose DEFAULT_* variables. But it looks like those defaults are applied\nwithin the C code itself. So unless Junio starts setting DEFAULT_PAGER\nhimself, I think his builds are OK.\n\n> I think if we ensure that ETC_GITCONFIG / ETC_GITATTRIBUTES\n> are set sanely by default (and easily overridden) then we\n> can probably avoid the need to handle it within the asciidoc\n> file though. (There's more on that though below.)\n\nI think these two differ from the DEFAULT_* in that we'll _always_ have\nthem set in the Makefile. And we probably always want to report them\nunless we're in a generic documentation build.\n\n> > It's a shame we have to repeat this logic from the Makefile, though I\n> > guess we already do so for prefix, bindir, etc, so far.\n> > \n> > Should we factor the path logic from the top-level Makefile into an\n> > include that can be used from either?\n> \n> Yeah, maybe. I didn't like the duplication either, but as\n> you noticed, we do it already for many of the other\n> variables. I suspect we could put these defaults into\n> config.mak.uname which Documentation/Makefile includes and\n> then you could run 'make -C Documentation' in a fresh clone\n> or tarball and get docs built with the defaults set for each\n> platform.\n\nI think it shouldn't go into config.mak.uname, since the idea there was\nto keep the long list of platform defaults separate from other logic\n(the Makefile is already long enough!). So I'm basically proposing the\nsame thing but in its own file. :)\n\n-Peff\n"},{"id":"351221","messageId":"20180628142705.GB15799@sigill.intra.peff.net","threadId":"48786","inReplyTo":"20180627164443.GK20217@zaya.teonanacatl.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-06-28T14:27:05Z","receivedAt":"2018-06-28T14:27:10Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jun 27, 2018 at 12:44:43PM -0400, Todd Zullinger wrote:\n\n> I wrote:\n> > Jeff King wrote:\n> >> (Related, there's a build target in the local Makefile for using\n> >> asciidoctor; does it need updated, too?)\n> > \n> > I didn't test asciidoctor specficially, but it also respects\n> > the ASCIIDOC_EXTRA parameters, so I think it will work just\n> > as well. I'll try to confirm that later today.\n> \n> Testing confirmed that asciidoctor works fine with this as\n> well.\n\nThanks for checking.\n\n> Somewhat tangentially, I looked at using asciidoctor for the\n> Fedora packages last year and one issue that kept me from\n> using it then was the '[FIXME: source]' it includes in the\n> footer of the manpage. When I dug into it at the time, it\n> appeared this was due to no declaration\n> (similarly missing for manual, and version). It wasn't\n> clear whether it was possible to include a custom header\n> template in plain asciidoctor. I got the impression that it\n> would require using a custom backend, which in turn required\n> the rubygem 'tilt' for processing.\n> \n> I spent about an hour poking around with it and decided that\n> I'd put off building with asciidoctor until that was fixed.\n> I felt that displaying '[FIXME: source]' wass worse than\n> simply not including the version.\n> \n> It's always possible that I was doing something wrong in my\n> use of asciidoctor (I just set USE_ASCIIDOCTOR). Or maybe\n> the Fedora packages are missing some dependency which I\n> missed.\n\nHmm. I don't typically use asciidoctor locally (to be honest, I do not\ntypically build the documentation at all locally, and just read the\nsource when I need it). But just setting USE_ASCIIDOCTOR seems to work\nfine for me out of the box. I'm on Debian unstable, asciidoctor 1.5.7.1.\n\nAt this point I think we still consider the original asciidoc as our\nofficially supported platform, and mostly are happy if things also work\nwith asciidoctor. But my impression is that there's no more development\nwork happening on asciidoc, and the path forward will be asciidoctor. So\nat some point we may need to flip that.\n\nOne nice thing about switching to asciidoctor fully is that it can do\ndirect manpage generation. So we could eventually drop the docbook/xmlto\ndependencies (right now even with USE_ASCIIDOCTOR we still go through\nthe xml step).\n\n> It might also be that we need some adjustments similar to\n> https://patchwork.kernel.org/patch/10360207/ to get the\n> mansource attribute passed on to asciidoctor. I only just\n> ran across that patch and haven't had a chance to test\n> sometime similar in the git manpage build. That looks\n> promising though.\n\nYeah, we have to do similar tricks on git-scm.com to handle things\nlike linkgit. Our implementation there is quite horrible (regex search\nand replace!). It would be wonderful if we could write real ruby\nsnippets to handle extended cases, and then the git-scm.com doc builder\ncould just reuse that logic instead of hackily reimplementing it.\n\nAnyway, that's all well outside the scope of your patch today, I think.\n:)\n"},{"id":"351222","messageId":"20180628142842.GC15799@sigill.intra.peff.net","threadId":"48786","inReplyTo":"20180627205843.GM20217@zaya.teonanacatl.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-06-28T14:28:42Z","receivedAt":"2018-06-28T14:28:47Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jun 27, 2018 at 04:58:43PM -0400, Todd Zullinger wrote:\n\n> I tend to think that the default should be to build\n> documentation that is accurate for that build, but since\n> it's something I'll set once for my package builds it's not\n> a big deal either way to me.\n\nTo be clear, I think so, too. I'd just like to have a single knob that\ngeneric builds can set so that:\n\n - the decision is only \"is this generic\", and the exact generic text\n is still inside the source files\n\n - it would cover this case and similar cases going forward\n\n-Peff\n"},{"id":"351233","messageId":"20180628163606.GP20217@zaya.teonanacatl.net","threadId":"48786","inReplyTo":"20180628141556.GA15799@sigill.intra.peff.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2018-06-28T16:36:06Z","receivedAt":"2018-06-28T16:36:20Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Jeff King wrote:\n> We could get rid around that by using $(DOC_ETC_GITCONFIG) or something,\n> with:\n> \n> DOC_ETC_GITCONFIG ?= $(ETC_GITCONFIG)\n> \n> in the Makefile. But that still leaves the choice of which generic text\n> to use up to the caller. Maybe we should provide more guidance.\n> \n> I.e., provide a knob like DOC_GENERIC that fills in generic values for\n> these values (and maybe some others; it sounds like we have some\n> existing problem cases).\n\nThat sounds pretty reasonable. I have something\nimplementing this below.\n\n>> It might be enough if the default values are relatively sane\n>> and consistent. That would be a slight improvement over the\n>> current situation still.\n> \n> Yeah. Taking a step back from the implementation questions, I think\n> \"$(prefix)/etc/gitconfig\" is not very helpful text. I'd be happy to see\n> us come up with a generic way of saying that which is more\n> comprehensible to end-users. Your patches side-step that by filling in\n> the real value, but unfortunately we can't do that everywhere. :)\n> \n> There may not be a good \"token\" value, though. I.e., we may need to have\n> two sets of verbiage: the specific one, and the generic one.\n\nYeah. About the best generic term I can come up with is\nusing '$sysconfdir'. But I have no idea if that's something\nmost readers will recognize as a placeholder for something\nlike /etc.\n\nA number of the path references are in the FILES sections of\nthe man pages. It might not be much of an improvement if we\ntry to stuff too much text in those references. Perhaps if\nthose used '$sysconfdir/gitconfig' a subsequent note could\nexpand on that? It could even be wrapped in an ifdef\nsimilar to that used for the default editor/pager.\n\nI don't want to make the plain .txt files significantly less\nreadable in the process, of course.\n\n>>> It's a shame we have to repeat this logic from the Makefile, though I\n>>> guess we already do so for prefix, bindir, etc, so far.\n>>> \n>>> Should we factor the path logic from the top-level Makefile into an\n>>> include that can be used from either?\n>> \n>> Yeah, maybe. I didn't like the duplication either, but as\n>> you noticed, we do it already for many of the other\n>> variables. I suspect we could put these defaults into\n>> config.mak.uname which Documentation/Makefile includes and\n>> then you could run 'make -C Documentation' in a fresh clone\n>> or tarball and get docs built with the defaults set for each\n>> platform.\n> \n> I think it shouldn't go into config.mak.uname, since the idea there was\n> to keep the long list of platform defaults separate from other logic\n> (the Makefile is already long enough!). So I'm basically proposing the\n> same thing but in its own file. :)\n\nAhh, something that the top-level Makefile would create and\nthen subdir Makefiles would include, perhaps similar to the\nway GIT-VERSION-FILE is updated and included? That could\nprove useful to some of the tools in contrib which duplicate\nlogic.\n\nSkipping that larger de-duplication cleanup, here's a stab\nat implementing the DOC_GENERIC knob (and the DOC_ overrides\nfor ETC_GIT(CONFIG|ATTRIBUTES). The defaults with\n'/GENERIC-SYSCONFDIR' in them are just placeholders waiting\nfor a better name. :)\n\nSimilarly, the use of {etc-git(config|attributes)} as the\nattribute for the replacements could likely be improved for\nreaders of the .txt files. {system-wide-gitconfig} is\nlikely better. Maybe the default for the generic paths\ncould be /system-wide/git(config|attributes) too (or in\nCAPS to make it more obviously a placeholder)?\n\nThanks for thinking this through and providing some good\ndirections to work on!\n\n-- >8 --\nSubject: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs\n\nReplace `$(prefix)/etc/gitconfig` and `$(prefix)/etc/gitattributes` in\ngenerated documentation with the paths chosen when building. Readers of\nthe documentation should not need to know how `$(prefix)` was defined.\n\nIt's also more consistent than sometimes using `$(prefix)/etc/gitconfig`\nand other times using `/etc/gitconfig` to refer to the system-wide\nconfig file.\n\nUpdate the SYNOPSIS of gitattributes(5) to include the system-wide\nconfig file as well.\n\nSupport building generic documentation with a DOC_GENERIC Makefile knob.\nThe default generic paths may be further customized via the\nDOC_ETC_GITCONFIG and DOC_ETC_GITATTRIBUTES variables.\n\nDefine DOC_GENERIC in dist-doc make target to ensure generic paths are\nused in the generated html and manpage tarballs.\n\nHelped-by: Jeff King \nSigned-off-by: Todd Zullinger \n---\n Documentation/Makefile | 22 ++++++++++++++++++++++\n Documentation/config.txt | 4 ++--\n Documentation/git-config.txt | 10 +++++-----\n Documentation/git.txt | 4 ++--\n Documentation/gitattributes.txt | 4 ++--\n Makefile | 10 ++++++++--\n 6 files changed, 41 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d079d7c73..2b3540a6c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -95,6 +95,7 @@ DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))\n \n prefix ?= $(HOME)\n bindir ?= $(prefix)/bin\n+sysconfdir ?= $(prefix)/etc\n htmldir ?= $(prefix)/share/doc/git-doc\n infodir ?= $(prefix)/share/info\n pdfdir ?= $(prefix)/share/doc/git-doc\n@@ -205,6 +206,27 @@ DEFAULT_EDITOR_SQ = $(subst ','\\'',$(DEFAULT_EDITOR))\n ASCIIDOC_EXTRA += -a 'git-default-editor=$(DEFAULT_EDITOR_SQ)'\n endif\n \n+ifndef ETC_GITCONFIG\n+ETC_GITCONFIG = $(sysconfdir)/gitconfig\n+endif\n+ifndef ETC_GITATTRIBUTES\n+ETC_GITATTRIBUTES = $(sysconfdir)/gitattributes\n+endif\n+\n+ifndef DOC_GENERIC\n+DOC_ETC_GITCONFIG ?= $(ETC_GITCONFIG)\n+DOC_ETC_GITATTRIBUTES ?= $(ETC_GITATTRIBUTES)\n+else\n+DOC_ETC_GITCONFIG ?= /GENERIC-SYSCONFDIR/gitconfig\n+DOC_ETC_GITATTRIBUTES ?= /GENERIC-SYSCONFDIR/gitattributes\n+endif\n+\n+DOC_ETC_GITCONFIG_SQ = $(subst ','\\'',$(DOC_ETC_GITCONFIG))\n+ASCIIDOC_EXTRA += -a 'etc-gitconfig=$(DOC_ETC_GITCONFIG_SQ)'\n+\n+DOC_ETC_GITATTRIBUTES_SQ = $(subst ','\\'',$(DOC_ETC_GITATTRIBUTES))\n+ASCIIDOC_EXTRA += -a 'etc-gitattributes=$(DOC_ETC_GITATTRIBUTES_SQ)'\n+\n QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir\n QUIET_SUBDIR1 =\n \ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 1cc18a828..ed903b60b 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -5,7 +5,7 @@ The Git configuration file contains a number of variables that affect\n the Git commands' behavior. The `.git/config` file in each repository\n is used to store the configuration for that repository, and\n `$HOME/.gitconfig` is used to store a per-user configuration as\n-fallback values for the `.git/config` file. The file `/etc/gitconfig`\n+fallback values for the `.git/config` file. The file +{etc-gitconfig}+\n can be used to store a system-wide default configuration.\n \n The configuration variables are used by both the Git plumbing\n@@ -2815,7 +2815,7 @@ configuration files (e.g. `$HOME/.gitconfig`).\n \n Example:\n \n-/etc/gitconfig\n+{etc-gitconfig}\n push.pushoption = a\n push.pushoption = b\n \ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 18ddc78f4..0d5ea5b58 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -114,10 +114,10 @@ See also <>.\n \n --system::\n \tFor writing options: write to system-wide\n-\t`$(prefix)/etc/gitconfig` rather than the repository\n+\t+{etc-gitconfig}+ rather than the repository\n \t`.git/config`.\n +\n-For reading options: read only from system-wide `$(prefix)/etc/gitconfig`\n+For reading options: read only from system-wide +{etc-gitconfig}+\n rather than from all available files.\n +\n See also <>.\n@@ -263,7 +263,7 @@ FILES\n If not set explicitly with `--file`, there are four files where\n 'git config' will search for configuration options:\n \n-$(prefix)/etc/gitconfig::\n+{etc-gitconfig}::\n \tSystem-wide configuration file.\n \n $XDG_CONFIG_HOME/git/config::\n@@ -310,11 +310,11 @@ ENVIRONMENT\n GIT_CONFIG::\n \tTake the configuration from the given file instead of .git/config.\n \tUsing the \"--global\" option forces this to ~/.gitconfig. Using the\n-\t\"--system\" option forces this to $(prefix)/etc/gitconfig.\n+\t\"--system\" option forces this to {etc-gitconfig}.\n \n GIT_CONFIG_NOSYSTEM::\n \tWhether to skip reading settings from the system-wide\n-\t$(prefix)/etc/gitconfig file. See linkgit:git[1] for details.\n+\t{etc-gitconfig} file. See linkgit:git[1] for details.\n \n See also <>.\n \ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex dba7f0c18..6a4646f99 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -567,10 +567,10 @@ for further details.\n \n `GIT_CONFIG_NOSYSTEM`::\n \tWhether to skip reading settings from the system-wide\n-\t`$(prefix)/etc/gitconfig` file. This environment variable can\n+\t+{etc-gitconfig}+ file. This environment variable can\n \tbe used along with `$HOME` and `$XDG_CONFIG_HOME` to create a\n \tpredictable environment for a picky script, or you can set it\n-\ttemporarily to avoid using a buggy `/etc/gitconfig` file while\n+\ttemporarily to avoid using a buggy +{etc-gitconfig}+ file while\n \twaiting for someone with sufficient permissions to fix it.\n \n `GIT_FLUSH`::\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex 92010b062..528de4259 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -7,7 +7,7 @@ gitattributes - Defining attributes per path\n \n SYNOPSIS\n --------\n-$GIT_DIR/info/attributes, .gitattributes\n+{etc-gitattributes}, $GIT_DIR/info/attributes, .gitattributes\n \n \n DESCRIPTION\n@@ -93,7 +93,7 @@ for a single user should be placed in a file specified by the\n Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME\n is either not set or empty, $HOME/.config/git/attributes is used instead.\n Attributes for all users on a system should be placed in the\n-`$(prefix)/etc/gitattributes` file.\n++{etc-gitattributes}+ file.\n \n Sometimes you would need to override a setting of an attribute\n for a path to `Unspecified` state. This can be done by listing\ndiff --git a/Makefile b/Makefile\nindex 0cb6590f2..f476a6eb5 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -292,6 +292,11 @@ all::\n # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor\n # Extensions Lab if you have it available.\n #\n+# Define DOC_GENERIC if you're building documentation for a general audience and\n+# do not want paths such as ETC_GITCONFIG and ETC_GITATTRIBUTES to be expanded.\n+# Define DOC_ETC_GITCONFIG and DOC_ETC_GITATTRIBUTES to override the generic\n+# defaults used for those paths.\n+#\n # Define PERL_PATH to the path of your Perl binary (usually /usr/bin/perl).\n #\n # Define NO_PERL if you do not want Perl scripts or libraries at all.\n@@ -2870,13 +2875,14 @@ manpages = git-manpages-$(GIT_VERSION)\n dist-doc:\n \t$(RM) -r .doc-tmp-dir\n \tmkdir .doc-tmp-dir\n-\t$(MAKE) -C Documentation WEBDOC_DEST=../.doc-tmp-dir install-webdoc\n+\t$(MAKE) -C Documentation DOC_GENERIC=1 WEBDOC_DEST=../.doc-tmp-dir \\\n+\t\tinstall-webdoc\n \tcd .doc-tmp-dir && $(TAR) cf ../$(htmldocs).tar .\n \tgzip -n -9 -f $(htmldocs).tar\n \t:\n \t$(RM) -r .doc-tmp-dir\n \tmkdir -p .doc-tmp-dir/man1 .doc-tmp-dir/man5 .doc-tmp-dir/man7\n-\t$(MAKE) -C Documentation DESTDIR=./ \\\n+\t$(MAKE) -C Documentation DESTDIR=./ DOC_GENERIC=1 \\\n \t\tman1dir=../.doc-tmp-dir/man1 \\\n \t\tman5dir=../.doc-tmp-dir/man5 \\\n \t\tman7dir=../.doc-tmp-dir/man7 \\\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nThanks, for a country where nobody is allowed to mind his own\nbusiness. Thanks, for a nation of finks.\n -- William S. Burroughs, A Thanksgiving Prayer\n\n"},{"id":"351251","messageId":"20180628181629.GF31766@sigill.intra.peff.net","threadId":"48786","inReplyTo":"20180628163606.GP20217@zaya.teonanacatl.net","subject":"Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2018-06-28T18:16:29Z","receivedAt":"2018-06-28T18:16:34Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jun 28, 2018 at 12:36:06PM -0400, Todd Zullinger wrote:\n\n> >> It might be enough if the default values are relatively sane\n> >> and consistent. That would be a slight improvement over the\n> >> current situation still.\n> > \n> > Yeah. Taking a step back from the implementation questions, I think\n> > \"$(prefix)/etc/gitconfig\" is not very helpful text. I'd be happy to see\n> > us come up with a generic way of saying that which is more\n> > comprehensible to end-users. Your patches side-step that by filling in\n> > the real value, but unfortunately we can't do that everywhere. :)\n> > \n> > There may not be a good \"token\" value, though. I.e., we may need to have\n> > two sets of verbiage: the specific one, and the generic one.\n> \n> Yeah. About the best generic term I can come up with is\n> using '$sysconfdir'. But I have no idea if that's something\n> most readers will recognize as a placeholder for something\n> like /etc.\n\nI don't that's much better than $(prefix). It's at least _correct_ more\noften, but unless you're used to autotools conventions, it's pretty\nobscure. Can we just say \"the system configuration direction (e.g.,\n/etc)\" or something like that?\n\nThat definitely requires doing some kind of ifdef in the asciidoc\nsource, but I think the end result will be much more comprehensible to\nend users. And IMHO the readability hit to the source is not too bad (at\nleast I don't find the DEFAULT_PAGER one to be).\n\nSomething like this:\n\ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 18ddc78f42..ab20dd5235 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -113,13 +113,16 @@ For reading options: read only from global `~/.gitconfig` and from\n See also <>.\n \n --system::\n-\tFor writing options: write to system-wide\n-\t`$(prefix)/etc/gitconfig` rather than the repository\n-\t`.git/config`.\n+\tFor writing options: write to the system-wide gitconfig file\n+\trather then the repository config.\n +\n-For reading options: read only from system-wide `$(prefix)/etc/gitconfig`\n+For reading options: read only from system-wide gitconfig file\n rather than from all available files.\n +\n+The exact location of the system-wide file is configured when Git is\n+built.\n+ifdef::git-doc-generic[In many builds, it is `/etc/gitconfig`.]\n+ifndef::git-doc-generic[In your build, it is +{etc-gitconfig}+.]\n See also <>.\n \n --local::\n\nThough I would also be happy if we simply said \"system-wide gitconfig\"\nhere and then had the conditional part in FILES.\n\nI'd actually argue that all of the \"source\" options should be grouped,\nlike:\n\n --local::\n --global::\n --system::\n --file=::\n\tWhen writing, write to the repository-local, user-global, or\n\tsystem-wide configuration file (or any `` you specify).\n\tWhen reading, read from a specific file rather than from all\n\tavailable files. See < below for more details.\n\nAnd then let <> describe in prose the various files, where they\nmight be, etc. That also cleans up the `.git/config` thing, which is a\nmild fiction (it is really `$GIT_DIR/config`).\n\n> A number of the path references are in the FILES sections of\n> the man pages. It might not be much of an improvement if we\n> try to stuff too much text in those references. Perhaps if\n> those used '$sysconfdir/gitconfig' a subsequent note could\n> expand on that? It could even be wrapped in an ifdef\n> similar to that used for the default editor/pager.\n\nSo yeah, I think I am arguing along the same lines, but just saying\n\"system-wide gitconfig\" or similar instead of $sysconfdir/gitconfig. I\nthink the English is a little less daunting.\n\n> > I think it shouldn't go into config.mak.uname, since the idea there was\n> > to keep the long list of platform defaults separate from other logic\n> > (the Makefile is already long enough!). So I'm basically proposing the\n> > same thing but in its own file. :)\n> \n> Ahh, something that the top-level Makefile would create and\n> then subdir Makefiles would include, perhaps similar to the\n> way GIT-VERSION-FILE is updated and included? That could\n> prove useful to some of the tools in contrib which duplicate\n> logic.\n\nNo, I had just envisioned it would be a static file, like\nconfig.mak.paths or something. I'm literally just trying to break out\nbits of our Makefile into bite-sized files so they're easier look at.\n\n> Skipping that larger de-duplication cleanup, here's a stab\n> at implementing the DOC_GENERIC knob (and the DOC_ overrides\n> for ETC_GIT(CONFIG|ATTRIBUTES). The defaults with\n> '/GENERIC-SYSCONFDIR' in them are just placeholders waiting\n> for a better name. :)\n\nSo obviously I like the direction of this patch, but if you agree with\nmy line of thinking above you'd need to turn DOC_GENERIC into an\nattribute and use in-source conditionals. Hopefully you do agree. :)\n\n> Thanks for thinking this through and providing some good\n> directions to work on!\n\nThank you for working on it! I was thinking about this because of the\nresponse I wrote in:\n\n https://public-inbox.org/git/20180626124316.GA15419@sigill.intra.peff.net/\n\nIf you're interested, this could all be rolled into a cleanup series.\nBut if not, I can wait for this to resolve and then build on top.\n\n-Peff\n"}]}