Java 10 And Cross References In Asciidoctor

CodeFX Weekly #43 — 11th of November 2017

Nicolai Parlog
Nov 14, 2017 · 6 min read

Java 10, this time for real

JDK 10 has its own project site, which lists known and proposed features (more on that later) and gives the schedule:

  • 11 Jan 2018: All Tests Run
  • 18 Jan 2018: Rampdown Phase Two
  • 22 Feb 2018: Final Release Candidate
  • 20 Mar 2018: General Availability

Features

So which features can you expect to be using in March? Here’s the current list (I removed those that are mostly internal):

Talks at Devoxx

There were a few interesting talks at Devoxx Belgium 2017 that covered Java’s present and future:

  • in some future Java version, method references can be used in annotations

Asciidoctor References

Last week I complained that Asciidoctor wasn’t powerful enough for me and, in accordance with Cunningham’s Law, I was proven wrong. It took me some time to get it working, so I decided to write it down and send it out.

The problem

For The Java Module System I use Asciidoctor, in which cross references work by setting an anchor with [[anchor-name]] and referencing it with <<anchor-name>>. The text that shows for the reference can be defined following the anchor, i.e. Learn more about <<anchor-name, that thing>>. I link the section numbers, so my text is full of See section <<anchor-name, 6.2>>.

How reference texts are picked out

Important caveat #1: If you use <<anchor-name, the text>> to define a text in the place where you make the reference, nothing else happens and that text is chosen. Makes sense, right?

== [[inline-anchor]]A header [[id]]
== An xreflabel header [[header-xreflabel,xreflabel header]]
[reftext="reftext header"]
== A reftext header [[header-reftext]]

Configure reference style

Since Asciidoctor 1.5.6 that last resort to determine a reference text can be configured. By setting the document attribute xrefstyle to either full, short, or basic various outputs can be achieved. The documentation goes into more details, but I want to focus on my use case - auto-numbering chapters and sections.

  • I only want to link the numbers, not the preceding chapter, section, …
  • I occasionally enumerate several chapters and sections and prefer see sections X, Y, Z over see section X, section Y, section Z.
= Reference Experiment
Nicolai Parlog
:doctype: article
:sectnums:
:xrefstyle: short
:!chapter-refsig:
:!section-refsig:
:!appendix-refsig:
== Many headers=== An xreflabel header [[header-xreflabel,xreflabel header]]See <<header-xreflabel>>.[reftext="reftext header"]
=== A reftext header [[header-reftext]]
See <<header-reftext>>.=== A blank header [[header-blank]]See section <<header-blank>>.
1. Many headers1.1. An xreflabel headerSee [xreflabel header].1.2. A reftext headerSee [reftext header].1.3. A blank headerSee section [1.3].

Project of the week: GDH

GDH, short for Generalized Diffie-Hellman Key Exchange Platform, writes about itself:



CodeFX Weekly

Whatever caught my interest throughout the week: libraries or tools I am using, what I’ve written or read that might interest you, fascinating questions on StackOverflow, conferences visits, odd tweets, anything really that connects to Java, software development, or writing.

Nicolai Parlog

Written by

Developer (mostly Java), blogger (http://codefx.org/), author (http://tiny.cc/jms), trainer (http://courses.codefx.org & https://www.youtube.com/c/codefx)

CodeFX Weekly

Whatever caught my interest throughout the week: libraries or tools I am using, what I’ve written or read that might interest you, fascinating questions on StackOverflow, conferences visits, odd tweets, anything really that connects to Java, software development, or writing.