Re: [RFC] doc: check-docs and WITH_BREAKING_CHANGES

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

Patrick Steinhardt <ps@pks.im> writes:

>> diff --git i/Makefile w/Makefile
>> index 893070be76..711cade8fd 100644
>> --- i/Makefile
>> +++ w/Makefile
>
> Curious, but what's up with the "i" and "w" prefixes here? :)

They indicate that you are looking at uncommitted "here is what I
typed in the working tree for illustration" changes ;-).

> I think this change makes sense indeed. It means that we stop linting
> the docs, which is a bit of a weird side effect that may or may not be
> sensible. But in any case, we should probably stop installing these man
> pages.
>
> I say "probably" because this got me thinking: we could keep the man
> page for a while, but completely replace their its with a notice saying
> that the command got removed. Even better, we could even tell users what
> the replacement is.

That is true but requires a much larger change.

There is an assumption that programs whose binaries we are not
installing should not get manual pages, which is what allows us to
throw git-http-fetch and git-whatchanged to EXCLUDED_PROGRAMS and
cause (1) them from getting built and installed, and (2) cause their
manual pages not built and not installed, and (3) tell doc-lint that
it is OK to have .adoc for these programs' documentation, even
though they are not listed in the command-list.txt file.  You'd need
to start from disentangling that.

Thanks.