Asciidoctor issues

[lesserwhirls]

This is a running list of problems regarding the html -> asciidoctor conversion (started from the comment by @JohnLCaron on /pull/254:

• No shading on blocks (

  )

• No lines in tables
• [source,xml] in red - Issue: docs need code highlighting enabled #260
• code blocks need to be delimited

[cwardgar]

When using AsciiDoc callouts in XML snippets, the callouts need to be of the form <!--1-->, not // <1>, # <2>, or ;; <3>. We're currently using the incorrect form in FeatureCollections.adoc, and probably elsewhere.

EDIT: After playing around with asciidoctor locally, callouts in XML using the 3 default forms were still being rendered okay. It's still probably a good idea to use the XML comment form so that the snippets remain copy-pasteable even when grabbed from the raw adoc.

[cwardgar]

Also, we need to make sure that the Unidata CSS renders callouts in the first place.

[lesserwhirls]

/pull/265 addresses several things here, as well as provides the infrastructure to link a common thredds css file (for tds and netcdf-java docs). This common css file will be heavily used to tweak the look and feel of the rendered html files.

[JohnLCaron]

callouts wrong only in XML, or everywhere?

On Thu, Oct 29, 2015 at 3:16 PM, Christian W [email protected]
wrote:

When using AsciiDoc callouts
http:https://asciidoctor.org/docs/user-manual/#callouts in XML, the callouts
need to be of the form , not // <1>, # <2>, or ;; <3>. We're
currently using the incorrect form in FeatureCollections.adoc, and probably
elsewhere.

—
Reply to this email directly or view it on GitHub
#258 (comment).

[cwardgar]

Just the XML snippets; the manual says you're supposed to use <!--1--> in those because XML doesn't have line comments. For Java code, something like // <1> should still work.

[lesserwhirls]

@cwardgar - would it be possible to fix the xml docs using a massive search/replace for the xml snippets, or is our usage just too variable to do that?

[cwardgar]

It seems pretty variable, unfortunately. Also, see #398. I learned that I needed to add:

// Enables non-selectable callout icons drawn using CSS.
:icons: font

to the document in order for the callouts to render properly.

[lesserwhirls]

Cool - it looks like it's working...

http:https://www.unidata.ucar.edu/software/thredds/v5.0/tds/tutorial/CatalogPrimer.html

Might not be supper pretty, but better than having the (1) text in the xml snippet that gets picked up in a copy/paste.

[cwardgar]

Awesome. But oh man is that page ugly. It'll be a good topic for our meeting.