Force Asciidoctor version when installed as a jekyll-asciidoc dependency?

An open source community I am involved with has a documentation build process that uses an home-grown validation program to check all the generated HTML files for page-to-page x-references that are both unique and accurate (they exist). Our builds fail if these rules are violated. The recent Asciidoctor 1.5.7.x release has broken some of this for us, which makes all our build scripts fail if the new Asciidoctor version is used.

Obviously, we need to fix our content, but that might take a little bit of time - you know, a community of volunteers and all - so we're trying to figure out how to prevent people from using the latest gem accidentally. The problem is if someone doesn't already have the Asciidoctor gem locally, jekyll-asciidoc will install the latest release available, which we specifically don't want yet.

We're going to update our Jenkins jobs and README to add a step to install the older Asciidoctor gem before jekyll-asciidoc (since it won't overwrite it), but it occurred to me this situation may not be the last where we want a specific version of Asciidoctor due to updates we aren't ready for.

Some (not exhaustive) googling didn't reveal a gem command solution, so I thought I'd throw the idea out there to see if anyone else has had this need or any ideas for a potential solution.  Is there a way (or could there be a way?) to specify the dependency version we'd prefer to be installed?

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Force-Asciidoctor-version-when-installed-as-a-jekyll-asciidoc-dependency-tp6338.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

I think there's a misunderstanding in the question about specifying the asciidoctor gem version - I wanted to specify it when it gets installed by the installation of the jekyll-asciidoctor gem because it's a missing dependency.  I know people can install whatever version of Asciidoctor first, I was just trying to reduce steps. But after I updated our internal docs, I realized it's not as big a deal as I thought initially, so I'll just have them install the Asciidoctor gem first so we can always have complete control over it. Not very many of our users install it at all anyway.

mojavelinux wrote

Can you share what chances are causing the violations to break? I'm curious if this is just over-specific validation or whether Asciidoctor is producing unexpected HTML. If it's the former, I might just recommend loosening the rules.

We found two changes where formulating the HTML IDs breaks for us now. The first causes duplicate references, while the second causes references that don't exist:

1) Someone made an entire page of level-2 headings that were just references to other pages, like this:

== <<scalar-math.adoc#scalar-math,Scalar Math>>

Before 1.5.7, the ID would be some formulation of maybe an interim HTML:

<h2 id="a-href-scalar-math-html-scalar-math-scalar-math-a"><a href="scalar-math.html#scalar-math">Scalar Math</a></h2>

That almost looks unintentional, but we never noticed it before because it was unique within the entire corpus of pages.

After 1.5.7, it not-surprisingly looks like this:

<h2 id="scalar-math"><a href="scalar-math.html#scalar-math">Scalar Math</a></h2>

This makes sense - the level-2 heading text that gets converted automatically into an ID is "Scalar Math" and since our idseparator is a dash, it becomes "scalar-math".

The page "scalar-math.html", though, already has a section with that ID (because it's the title of the page), so when our validation looks at all the pages it finds 2 pages with duplicate IDs and fails.

This is *not* a problem that needs to be fixed, in our opinion.  An entire page like this is really not very useful to readers, so I plan to modify it before it's finally published and that will remove the issue for us entirely (or we'll explicitly define anchors). However, it did expose this change which maybe wasn't intentional or will bother other users.

2) This change has to do with how non-alphanumeric characters are parsed when constructing the IDs. If Page A has a section title like:

=== The <metrics><reporters> Element

Before 1.5.7, the brackets were stripped and replaced with whitespace, which was itself replaced by our idseparator  resulting in HTML like:

<h3 id="the-metrics-reporters-element">The &lt;metrics&gt;&lt;reporters&gt; Element</h3>

After 1.5.7, the brackets are stripped but no longer replaced with whitespace, so our idseparator is never inserted:

<h3 id="the-metricsreporters-element">The &lt;metrics&gt;&lt;reporters&gt; Element</h3>

The issue here is that currently another page (Page B) trying to link to this specific section is using the old way, so our validation fails because the reference used on Page B no longer exists anywhere else in the corpus of pages.

This one is a bit more insidious. I get that the idseparator is not inserted because there is no space between "<metrics>" and "<reporters>", but it's subtle and harder for me to figure out how to explain to novices how to construct references. I'm assuming that this was entirely intentional, so maybe you have a simple way of explaining it that I can borrow :-)

We can live with both changes in the long run, but thanks for asking for the details.

- Cassandra

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Force-Asciidoctor-version-when-installed-as-a-jekyll-asciidoc-dependency-tp6338p6346.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML