Re: testing out Docker CI scripts?

[David Kastrup]

Han-Wen Nienhuys <address@hidden> writes:

> On Sat, Feb 22, 2020 at 9:54 PM David Kastrup <address@hidden> wrote:
>> > On Sat, Feb 22, 2020 at 5:23 PM Jonas Hahnfeld <address@hidden> wrote:
>> >> > I would be interested in your feedback.
>> >>
>> >> Not having run any of this, my immediate response would that it's not
>> >> running 'make doc' AFAICS.
>> >
>> > For changes to the code, it should be irrelevant to run make doc: the
>> > regression test should cover all the behaviors we care about from a
>> > programming perspective.
>>
>> It would be nice if you considered asking questions instead of just
>> assuming that our established procedures do not make sense and are not
>> actually rooted in any relevant experience.
>>
>> We had a considerable amount of documentation building failures due to
>> "code-only" changes that "couldn't possibly" affect the doc build.  To a
>> good degree this is because the in-code documentation (like of
>> properties, music functions and a whole bunch of stuff ending up in the
>> Internals Reference) is run through various interpreters of Texinfo.
>
> I think we could and should run the documentation as part of the regtests.
>
>> > The time that David quotes for 'make doc' (~40 minutes) sounds wrong.
>> >
>> > $ ls -1 input/regression/*.ly|wc
>> >    1347    1347   55843
>> >
>> > $ grep @lilypond $(find  Documentation/ -name '*.*tely' | grep -v
>> > 'Documentation/[a-z][a-z]/')|wc
>> >    1828    1938  136964
>> >
>> > Building the docs should take about 1.5x the time of building the
>> > regtests. lilypond-book uses a shared database for snippets across all
>> > languages, so there should be neglible additional cost for the rest of
>> > the languages.
>>
>> Assuming that all translations are kept at exactly the same level and
>> the example code is not at all adapted to the language in question in
>> lyrics and code comments.
>>
>> And assuming that our regtests make up 40% of the LilyPond material in
>> the documentation and are not getting recompiled as part of including
>> them into the various forms of the documentation.
>>
>> Since the documentation graphics are produced in PNG format for HTML
>> inclusion and in PDF format for PDF inclusion, that seems audacious.
>
> I don't understand you; what seems audacious?
>
> I think the runtime of make doc is off by a factor of about 5, which
> could be explained if somehow each language recompiles the snippets
> afresh.
>
> You seem dismissive of my analysis, so I guess you don't want to look
> into this further?

Clicking on the images in the HTML documentation leads you to the source
code of the respective snippet as generated by lilypond-book.  Doing
this on corresponding images in different translations leads you to the
same source file.

That does appear like the basic database mechanism is working.

Most of the non-English documentation is outdated to some smaller or
larger degree, meaning that there is considerable variance in the
contained snippets compared to the upstream English version.

The generation of snippets as PNG (not needed for running the regtests)
creates them as larger size bitmaps in Ghostscript, scaling them down
for quality.  There is also extensive Ghostscript carnage happening for
making sure that we don't get per-image font subsets in the snippets for
PDF generation since that allows to condense the final PDFs in an
additional pass to contain just single font copies for most of the
material.

That has been necessitated by us moving to text fonts supporting a
humongous amount of Unicode characters as far as I remember.

The download size for the notation manual comes out at 35MB which is
about double than what we had for 2.16.  I actually find that somewhat
irritating.  I'd have to check the old conversations about
extractpdfmark and see whether this is indeed where our change of text
fonts would have placed us even after the extractpdfmark work.  Though I
do seem to remember that the subsetting problem depended on the kind of
font used, and the newer fonts were in a different form.

At any rate, that stuff comes at considerable cost in file generation
time (partly during font embedding, partly during postprocessing passes)
for considerable benefits in the resulting PDF download sizes (the
intermediate generated PDF sizes are actually horrendous before
extractpdfmark does its work).

There has been a continuity in the development of documentation
generation times, and the reasons it has increased over time are not
that people just don't notice or care (considering the actually taken
amounts of time, a somewhat unlikely hypothesis), but that there are
actual bonafide reasons for accepting the costs after extensive analysis
and tests of the various options.

Essentially, if you consider me "dismissive of your analysis" and "guess
I don't want to look into this further?", one cause might be that you
have been missing out on information and discussions that have caused
the choices leading to the results you are seeing, with significant
changes accompanied by extensive analysis from several contributors and
partly offset by developing new tools, mechanisms, ways of calling
LilyPond and processing its output, and the integration into the scripts
and build systems.

Yes, the taken times are a nuisance.  And no, they are unfortunately no
accident that nobody has bothered looking into yet.

-- 
David Kastrup
My replies have a tendency to cause friction.  To help mitigating
damage, feel free to forward problematic posts to me adding a subject
like "timeout 1d" (for a suggested timeout of 1 day) or "offensive".