Re: suggestion for git glossary: "ort"

[Junio C Hamano <gitster@pobox.com>]

scs@eskimo.com (Steve Summit) writes:

>> ...I doubt it would help all that much to add a new entry to the
>> glossary, especially if they do not think of first taking a look at
>> "git merge --help", which has its own large section on "ort".
>
> Call me stupid :-),

I see a smiley, but FWIW I didn't (and I wouldn't).

What I meant is that the most effective place to give additional
information may not be another end-user facing documentation page
(i.e. git help glossary) when a newcomer is puzzled about a word in
the source and another end-user facing documentation page already
explains the word.  After all, not all the words we see in the
documentation sources are necessarily end-user facing.

The implication is that we need to look elsewhere to find a more
effective place, if glossary isn't the place.

If we use "ort" (or "recursive" for that matter) in our sources in a
context where it is not obvious that we refer to one of our merge
strategies, we can be a bit more helpful by saying "ort strategy" or
"recursive strategy".  There shouldn't be too many places that refer
to these words outside the files that _are_ about these strategies
where they should not need repeated explanations (for example, the
big comment that starts merge-ort.c file should suffice for mentions
of "ort" in four merge-ort* files).

    $ git grep -l -E -e '(^|[^a-z])ort([^a-z])' -i \*.[ch]
    builtin/merge.c
    builtin/rebase.c
    log-tree.c
    merge-ort-wrappers.c
    merge-ort-wrappers.h
    merge-ort.c
    merge-ort.h
    merge-recursive.c
    sequencer.c
    t/helper/test-fast-rebase.c


On the other hand, if the source to a "mergy" subcommand whose name
is NOT "merge" refers to "ort" out of context, and it is not clear
that the word refers to one of the merge strategies, the reader
definitely deserves help.  It is understandable that without
familiarity of the architecture of Git, it would not be obvious that
mergy operations like cherry-pick, revert and rebase heavily depend
on the merge strategy backends.  We should update the mention of
"ort" in these source files to make it more clear that it is one of
the "merge strategies", at which point "git merge --help" would be
an obvious next step, because that is where the strategies are
listed and explained.

The mention of "ort" in builtin/rebase.c looks like this:

		if (!options.strategy)
			options.strategy = "ort";

The name of the member getting assigned to, .strategy, makes it
already clear that this refers to rebase_options.strategy so perhaps

	/* choice of merge strategy, e.g. "ort" */
	char *strategy, *strategy_opts;

in the definition of the rebase_options structure might help.

The only reference in merge-recursive.c is

	/* Not supported; option specific to merge-ort */

which would be enough for readers to notice merge-ort.c is next door,
which has this at the top,

        /*
         * "Ostensibly Recursive's Twin" merge strategy, or "ort" for short.  Meant
         * as a drop-in replacement for the "recursive" merge strategy, allowing one
         * to replace ...

so I do not think there is anything to add there.

Some mentions in sequencer.c can probably use improvements.