Re: [PATCH v1 0/3] travis-ci: build docs with asciidoctor

[Lars Schneider <larsxschneider@gmail.com>]

> On 14. Apr 2017, at 00:41, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Lars Schneider <larsxschneider@gmail.com> writes:
> 
>> this is a mini series to build the documentation with asciidoctor in
>> addition to asciidoc on Travis-CI.
> 
> Overall, this looks sensible.  I didn't spot anything questionable
> other than a minor style nit, i.e. write these
> 
>    make doc USE_ASCIIDOCTOR=1
>    make -j2 doc USE_ASCIIDOCTOR=1
> 
> more like this
> 
>    make USE_ASCIIDOCTOR=1 doc
>    make -j2 USE_ASCIIDOCTOR=1 doc

OK! I'll change it and send a new round next week.

> Having said that, I wonder if we get some interesting results out of
> building the documentation twice, though.  By looking at the Travis
> log with timestamps, we probably can see how long each build takes,
> but that is much less interesting than learning if new versions of
> text used mark-up that does not format correctly on one or the other
> (i.e. catch documentation breakage early in each CI run), for
> example.  I have an impression that neither AsciiDoc nor AsciiDoctor
> "fails" in an obvious way that "make" can notice (i.e. they often
> just silently produce nonsense output when fed a malformed input
> instead).

True! But wouldn't we get a syntax check here? Wouldn't asciidoc / ascidoctor bark if we use wrong/unsupported elements?

In addition, we could push the resulting documentation somewhere. However, that would still require a human to look at it. Do you think that could have value?

Thanks,
Lars