spring-projects-issues
commented
7 years ago Dan Allen commented
I'd like to offer some insight that may help with this transition / migration.
As the Asciidoctor project lead, it's my vision to see users eventually migrate away from DocBook. While I consider it important to have the option to export to DocBook and reuse that toolchain, I don't consider this to be the most efficient or friendly route. Instead, I'm aiming for direct conversion from AsciiDoc to the target output (HTML, multi-page HTML, PDF, etc). I'm confident it can be achieved. Of note, the latest Asciidoctor PDF gets us much closer to parity with the DocBook toolchain...and progress continues.
Multi-page support has traditionally been handled by the DocBook toolchain, a philosophy inherited from AsciiDoc Python. Obviously, it's not ideal to rely on DocBook and its convoluted configuration in order to produce this format. And there's absolutely no reason to. Asciidoctor parses the document into an AST. Any engineer with a modest amount of talent and sufficient time can generate from this model exactly what DocBook produces, if not better. In fact, better is the goal.
The main issue I have with multi-page support is that it's often done with absolutely no thought. Many sites force users to step through the docs paragraph-by-paragraph because the tool mindlessly minced the original document.
What constitutes a page? This is not something a tool can decide for you. It's an information architecture problem. The author or information architect needs to define the parameters of a page and the tool needs to carry out those directives.
We could have a convention where splits occur at annotated section nodes (in AsciiDoc terminology, a role or dedicated attribute). This decision has to be made first before a good tool can be created. Again, any engineer should be able to make the tool carve up the document according to these hints, or by falling back to an intelligent convention.
There's a similar consideration for the ToC and site navigation. What belongs in those catalogs? Where does the information originate? You should design an intuitive hierarchy that's easily navigable. The user doesn't necessarily want a list of every section title. They may even want to look at the content from different perspectives, known as topic-based entries.
Once you start dividing up the document, you really need to think about linking. I actually don't think the built-in linking mechanism in AsciiDoc is sufficient for an enterprise site (not even inter-document xrefs). Those are just handy defaults. The tools are there to create a more sophisticated and more loosely-coupled mechanism.
I recommend introducing an inline macro named something like xlink that defines the parameters of a link, but doesn't concern itself with how to make it. The converter can then take that information, consider what it's making, and produce the appropriate link for the context. (It's also possible to piggyback off the default link so that previews still work, but use the additional metadata when compiling and chunking the documentation for publication).
You may also want automatic links to navigate around the hierarchy or to related topics. The hierarchy links are easy to calculate at build time. Related topics can be achieved by adding metadata (custom attributes) to the document header. If you decide on a standard set of attributes, the converter can make use of these to generate links to other sections, topics, or document roots.
The best way to support AsciidoctorJ, the Maven plugin, and the Gradle plugin is to write the code in Ruby. The Ruby API gives you access to everything, whereas the AsciidoctorJ API is still catching up. If Ruby isn't an option and you must write the extension in Java, then you definitely should be using the alpha for AsciidoctorJ 1.6.0. The AST has been radically improved in that version and gets you much closer to what the Ruby version provides.
In general, my advice is to think outside the box and consider leveraging extensions. AsciiDoc provides both a starting point and an extensible framework for composing and converting documents that fit your needs. If you find yourself having to be too specific or verbose in the AsciiDoc, that's usually a sign you should introduce an abstraction (i.e., syntax extension or declarative metadata).
Brian Clozel opened SPR-14997 and commented
This should in fact:
Also, the documentation could use the dedicated asciidoctor plugin to switch from java to xml config in the HTML backend.
Reference URL: https://github.com/spring-projects/spring-boot/issues/7447
Issue Links:
20031 AsciiDoctor task does not support Rouge on MS Windows