zalando
some formatting can't be converted to PDF
Problem Pages 10 (durable references) and 44/45 (common method properties table) of the PDF show some pieces of text as plain HTML instead of formatted properly.
Analysis
When running the make all locally, I get some errors:
...
docker run -v /home/pebermann/projektoj/restful-api-guidelines:/documents/ asciidoctor/docker-asciidoctor:latest asciidoctor \
-D /documents/output index.adoc;
docker run -v /home/pebermann/projektoj/restful-api-guidelines:/documents/ asciidoctor/docker-asciidoctor:latest asciidoctor-pdf \
-D /documents/output index.adoc;
asciidoctor: ERROR: failed to parse formatted text: <code><a href="https://infrastructure-api-repository.zalandoapis.com/" class="bare">https://infrastructure-api-repository.zalandoapis.com/</a></code> <b>–</b> used to refer to user defined, immutable API specification revisions published via the internal API repository.
asciidoctor: ERROR: failed to parse formatted text: <code><a href="https://opensource.zalando.com/restful-api-guidelines/{model.yaml}" class="bare">https://opensource.zalando.com/restful-api-guidelines/{model.yaml}</a></code> <b>–</b> used to refer to guideline defined re-usable API fragments (see <code>{model.yaml}</code> files in <a href="https://github.com/zalando/restful-api-guidelines/tree/master/models">restful-api-guidelines/models</a> for details).
asciidoctor: ERROR: failed to parse formatted text: <span class="should-keyword">⚠️</span> No, but <a anchor="229"><span class="should-keyword"><strong>SHOULD</strong></span> consider to design <code>POST</code> and <code>PATCH</code> idempotent</a>
asciidoctor: ERROR: failed to parse formatted text: <span class="should-keyword">⚠️</span> May, but only if specific <a href="#post"><code>POST</code></a> endpoint is <a anchor="safe">safe</a>. <strong>Hint:</strong> not supported by most caches.
asciidoctor: ERROR: failed to parse formatted text: <span class="should-keyword">⚠️</span> No, but <a anchor="229"><span class="should-keyword"><strong>SHOULD</strong></span> consider to design <code>POST</code> and <code>PATCH</code> idempotent</a>
asciidoctor: ERROR: failed to parse formatted text: <span class="should-keyword">⚠️</span> No, but <a anchor="229"><span class="should-keyword"><strong>SHOULD</strong></span> consider to design <code>POST</code> and <code>PATCH</code> idempotent</a>
asciidoctor: ERROR: failed to parse formatted text: <span class="should-keyword">⚠️</span> May, but only if specific <a href="#post"><code>POST</code></a> endpoint is <a anchor="safe">safe</a>. <strong>Hint:</strong> not supported by most caches.
asciidoctor: ERROR: failed to parse formatted text: <span class="should-keyword">⚠️</span> No, but <a anchor="229"><span class="should-keyword"><strong>SHOULD</strong></span> consider to design <code>POST</code> and <code>PATCH</code> idempotent</a>
mv -f output/index.pdf output/zalando-guidelines.pdf;
...
It looks like the HTML→PDF conversion did break here somehow?
The only thing I can see which those have in common is that some more or less complicated HTML is included via a {...} directive into the actual code here.
I checked this before and back than I found no serious consequences based on this warning for the created pdf-file, so I decided to ignore it.
Yeah, but it has the effect that on two pages the formatting is broken. (The ERRORs are just a symptom which might help identify the problem.)
The icons in front of the Yes/No are broken too, but that seems to be a separate issue and not related to these ERRORs.
If fixing this issue turns out to be not straightforward (asciidoc update?), then we do not further support pdf generation / download option.
The table for rule 149 is fixed, but the link in rule in rule 234 is still broken.
We decided to not invest time into fixing this, instead added #753 for removing the PDF + epub versions.