Open lesserwhirls opened 8 years ago
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.
Also, we need to make sure that the Unidata CSS renders callouts in the first place.
Unidata/thredds/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.
callouts wrong only in XML, or everywhere?
On Thu, Oct 29, 2015 at 3:16 PM, Christian W notifications@github.com wrote:
When using AsciiDoc callouts http://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 https://github.com/Unidata/thredds/issues/258#issuecomment-152330721.
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.
@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?
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.
Cool - it looks like it's working...
http://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.
Awesome. But oh man is that page ugly. It'll be a good topic for our meeting.
This is a running list of problems regarding the html -> asciidoctor conversion (started from the comment by @JohnLCaron on Unidata/thredds/pull/254: