git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	"SZEDER Gábor" <szeder.dev@gmail.com>,
	git@vger.kernel.org, "Olivier Bornet" <olivier.bornet@puck.ch>
Subject: Re: [PATCH] Documentation/git-fsck.txt: include fsck.* config variables
Date: Mon, 29 Jul 2019 16:12:36 -0400	[thread overview]
Message-ID: <20190729201236.GF14943@sigill.intra.peff.net> (raw)
In-Reply-To: <xmqq36iox2nn.fsf@gitster-ct.c.googlers.com>

On Mon, Jul 29, 2019 at 08:48:28AM -0700, Junio C Hamano wrote:

> > Before this include let's add:
> >
> >     The below documentation is the same as what’s found in
> >     git-config(1):
> 
> I actually do not think we would want to do that.  I am all for the
> kind of 'include' proposed by this patch, and we should strive to
> make it easier for us to make sure the duplicated text are in sync.
> 
> But that would mean that the readers will have to see the "is the
> same as the other one" over and over.  If our documentation set is
> consistent, they should not have to.
> 
> I think we *must* make such a note in a total opposite case,
> i.e. "here are the summary of the most often used options; for full
> list, see git-config(1)".

I disagree. _We_ know that the content is the same, because we are
looking at the source that says "include". But as a user, how do I know
when I get to one section or the other that it is something I have
already read and can skip over?

Perhaps if Git were entirely consistent here, they could make the
assumption that "CONFIG" sections were always duplicated and know this
already.  But I think even that is asking a bit much. Unless they are
intimately familiar with our documentation, they don't know that we are,
in fact, consistent. And we are in an uphill battle with every other
thing the user has read, which may not agree with our assumptions of
consistency. ;)

So IMHO it's worth leaving a note that guides the reader, as long as
it's short (and I think this one is).


That said, I think an even _better_ solution would be to avoid includes,
and instead make it clear when we are pointing the user to shared
content. Then we get them to the right place _and_ explicitly instruct
them that concepts/content are shared. For config, for example, I've
worked with a previous system that did something like:

  - include fsck.* documentation in the git-fsck manpage

  - make a master table of config options in git-config.1 with _just_
    the names and the associated manpage where the definition can be
    found. This serves as an index if you don't know where to look.

This would probably involve creating new concept-based pages for some of
the groupings (e.g., where does "remote.*" config go?), but I think that
would probably help round out our documentation (if there is a concept
with related config options but we don't explain it anywhere, that is
probably a gap we should fix).

The biggest downside is that chasing down references in manpages sucks.
For the HTML documentation we'd ideally hyperlink from the git-config.1
index into each definition, but there's no way to do that with a regular
manpage.

-Peff

PS This is an approach I've advocated for a while:

    https://public-inbox.org/git/20110120233429.GB9442@sigill.intra.peff.net/

   but haven't actually done much about, so perhaps I should be putting
   my money where my mouth is. ;)

  reply	other threads:[~2019-07-29 20:12 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-07-29  7:58 Problem with fsck and invalid submodule path in history Olivier Bornet
2019-07-29  9:39 ` SZEDER Gábor
2019-07-29  9:59   ` [PATCH] Documentation/git-fsck.txt: include fsck.* config variables SZEDER Gábor
2019-07-29 15:33     ` Ævar Arnfjörð Bjarmason
2019-07-29 15:48       ` Junio C Hamano
2019-07-29 20:12         ` Jeff King [this message]
2019-07-29 21:32           ` Junio C Hamano
2019-07-29 14:31   ` Problem with fsck and invalid submodule path in history Olivier Bornet

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190729201236.GF14943@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=olivier.bornet@puck.ch \
    --cc=szeder.dev@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).