Fix issues causing gulp to choke

[joewiz]

Closes #731.

I also spotted several of the files in the listings directory that aren't referenced in the article with <programlisting>, but my primary goal in this PR is to fix the build.

It would be nice if the build process could catch such errors and flag which files are the cause of the error. These errors weren't caught by mvn validate. Only mvn test failed - and didn't tell us which file caused the problem.

[joewiz]

The commit that ultimately fixed the build for me locally was addressing the listings with multiple root nodes - i.e., changing them from .xml to .txt.

[joewiz]

CI has failed:

[INFO] --- frontend-maven-plugin:1.12.1:npm (mocha tests) @ exist-documentation ---
[INFO] Running 'npm test' in /home/runner/work/documentation/documentation
[INFO] 
[INFO] > exist-documentation@5.3.1-SNAPSHOT test
[INFO] > mocha src/test/mocha/ --recursive --exit
[INFO] 
[INFO] 
[INFO] 
[INFO]   running XQsuite test …
[INFO] response body: {"testsuite":{"package":"http://exist-db.org/xquery/documentation/tests","timestamp":"2022-01-12T18:37:42.981Z","tests":"6","failures":"1","errors":"0","pending":"1","time":"PT2.874S","testcase":[{"name":"Listing consistency","class":"tests:equal-listing"},{"name":"section-headings","class":"tests:missing-id"},{"name":"Pro angular brackets","class":"tests:no-ecaped-listings","failure":{"message":"assertEmpty failed.","type":"failure-error-code-1"},"output":"fo-render.xml"},{"name":"wellformed xml","class":"tests:no-txt-xmls","pending":null},{"name":"diagnose listings","class":"tests:orphan-listing"},{"name":"ToC rendering","class":"tests:toc-inline"}]}}
[INFO]         6 xqsuite tests:
[INFO]           Listing consistency
[INFO]           section-headings
[INFO]           [ 'Pro angular brackets', 'assertEmpty failed.' ]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  46.609 s
[INFO] Finished at: 2022-01-12T18:37:43Z
[INFO] ------------------------------------------------------------------------
Error:  Failed to execute goal com.github.eirslett:frontend-maven-plugin:1.12.1:npm (mocha tests) on project exist-documentation: Failed to run task: 'npm test' failed. org.apache.commons.exec.ExecuteException: Process exited with an error: 1 (Exit value: 1) -> [Help 1]

This is puzzling, because when running unit and integration tests locally as described in the README, they all pass.

Any ideas?

[joewiz]

The failing xqsuite test is here: https://github.com/eXist-db/documentation/blob/master/src/main/xar-resources/modules/test-suite.xql#L137-L157.

Running this test locally returns the following output:

<testcase name="Pro angular brackets" class="tests:no-ecaped-listings">
    <failure message="assertEmpty failed." type="failure-error-code-1"/>
    <output>fo-render.xml</output>
</testcase>

So it looks like fo-render.xml contains instances of <programlisting language="xml"/>.

Wouldn't this make more sense to perform this check in Schematron, so that it's caught up front by mvn validate instead of waiting for the integration test?

@adamretter In #726 you committed a lot of files to the listings directory but didn't update the article to reference them all. Is it possible you made the changes locally but didn't commit the updated fo-render.xml file?

[duncdrum]

@joewiz the last changes to how integration tests are run locally are from #599 maybe @adamretter has an idea. The errors flagged by CI in the original PR are reported correctly, so they should never have passed running the tests locally.

6 xqsuite tests:
[INFO]           Listing consistency
[INFO]           section-headings
[INFO]           [ 'Pro angular brackets', 'assertEmpty failed.' ]

this xqs test very likely predates the schema and schematron rules, so refactoring it to be part of one instead of the other is certainly an option.

the basic idea that:

• listingXYZ.xml listing have to be well-formed, non-well formed xml code should use a .txt listing
• avoid pure cdata inline xml listings

are both covered in the author guide. Both lead are due to problems with display and search. Unless we find a way to add a gulp:watch like ability to the maven build, I m afraid contributors will have to continue to inspect articles in the browser. Your fixes go in the right direction.

There should actually be another check to hunt for non-referenced listings, if they exist that's certainly another error.

[adamretter]

avoid pure cdata inline xml listings
are both covered in the author guide.

Actually the style guide says that using CDATA inline is ok. As that is no longer the case, we should update the style guide...

[duncdrum]

[joewiz]

I have realigned the <programlistings> to reference the existing files in the listings directory.

All tests pass locally, including a manually-triggered XQSuite:

<testsuite package="http://exist-db.org/xquery/documentation/tests"
    timestamp="2022-01-13T14:46:04.241-05:00" tests="6" failures="0" errors="0" pending="1"
    time="PT1.517S">
    <testcase name="Listing consistency" class="tests:equal-listing"/>
    <testcase name="section-headings" class="tests:missing-id"/>
    <testcase name="Pro angular brackets" class="tests:no-ecaped-listings"/>
    <testcase name="wellformed xml" class="tests:no-txt-xmls">
        <pending/>
    </testcase>
    <testcase name="diagnose listings" class="tests:orphan-listing"/>
    <testcase name="ToC rendering" class="tests:toc-inline"/>
</testsuite>

Now we'll see if CI agrees...

[joewiz]

It does! :)

[joewiz]

@adamretter @duncdrum @dizzzz @line-o Thanks, guys!