org.asciidoctor

Class RedPenTreeProcessor

java.lang.Object

org.asciidoctor.extension.Processor

org.asciidoctor.extension.Treeprocessor

org.asciidoctor.RedPenTreeProcessor

public class RedPenTreeProcessor
extends org.asciidoctor.extension.Treeprocessor

AsciiDoctor tree processor, for use with the "redpen" AsciiDoctor backend, used to populate a RedPen document

This (unfortunately) has to be under an 'org' or 'com' package, rather than a 'cc' package, due to the way JRuby and AsciiDoctor handle the registration of this class.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	RedPenTreeProcessor.BlockAccessor helper class to inspect and access important asciidoctor information obscured by JRuby (and AsciiDoctorJ)

Field Summary

Fields inherited from class org.asciidoctor.extension.Processor

config, rubyRuntime

Constructor Summary

Constructors

Constructor and Description
RedPenTreeProcessor(Document.DocumentBuilder documentBuilder, SentenceExtractor sentenceExtractor, Map<String,Object> config) Build a tree processer that uses the supplied documentBuilder and sentenceExtractor

Method Summary

Modifier and Type	Method and Description
protected LineOffset	addSentence(LineOffset lineOffset, String processed, String source, SentenceExtractor sentenceExtractor, List<Sentence> sentences) Add a processed AsciiDoc sentence, using the raw source sentence to guide the character offsets.
org.asciidoctor.ast.Document	process(org.asciidoctor.ast.Document document) Process a AsciiDoctorJ document
protected void	processParagraph(String paragraph, String sourceText, List<Sentence> sentences) Process a paragraph of processed text.

Methods inherited from class org.asciidoctor.extension.Treeprocessor

process

Methods inherited from class org.asciidoctor.extension.Processor

createBlock, createBlock, createInline, createInline, document, getConfig, update_config

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RedPenTreeProcessor

public RedPenTreeProcessor(Document.DocumentBuilder documentBuilder,
                           SentenceExtractor sentenceExtractor,
                           Map<String,Object> config)

Build a tree processer that uses the supplied documentBuilder and sentenceExtractor

Parameters:

documentBuilder - redpen document builder

sentenceExtractor - redpen sentence extractor

config - asciidoctor's configuration map

Method Detail

process

public org.asciidoctor.ast.Document process(org.asciidoctor.ast.Document document)

Process a AsciiDoctorJ document

Specified by:

process in class org.asciidoctor.extension.Treeprocessor

Parameters:

document - this is an AsciiDoctorJ document, not a redpen document

Returns:

processParagraph

protected void processParagraph(String paragraph,
                                String sourceText,
                                List<Sentence> sentences)

Process a paragraph of processed text.

This method takes the processed form of the text generated by the Ruby RedPen AsciiDoctor backend found in AsciiDocParser.java If the source form of the paragraph is also provided, it uses this to calculate the RedPen offsets for the characters in the text.

The AsciiDoctor parser does not return the line numbers via the AsciiDoctorJ Block interface. Therefore, the custom RedPen AsciiDoctor backend encodes the line number between ^A and ^B, if known.

Hence the processed text for a paragraph is typically:

^Alinenumber^Bparagraph_text

This method first breaks the paragraph on these line markers and adjusts the running lineNumber variable, and then processes each sub-paragraph/sentence using standard RedPen sentence-end-position delimiting.

Parameters:

paragraph - the AsciiDoctor processed text, already converted by the RedPen AsciiDoctor backend

sourceText - the raw source text

sentences - A list of sentences discovered in the processed text

addSentence

protected LineOffset addSentence(LineOffset lineOffset,
                                 String processed,
                                 String source,
                                 SentenceExtractor sentenceExtractor,
                                 List<Sentence> sentences)

Add a processed AsciiDoc sentence, using the raw source sentence to guide the character offsets.

Since AsciiDoctor does not return character offset positions for altered/formatted elements, this method attempts to calculate the offsets by comparing the source sentence with the post-processed sentence.

To assist with the calculation, the RedPen AsciiDoctor backend places markers in the text where AsciiDoctor has subsituted or altered the source sentence.

This is a normal function of AsciiDoctor. For example, AsciiDoctor's HTML backend will convert:

This is *bold*.

to:

This is <strong>bold</strong>.

The RedPen AsciiDoctor backend uses ^C and ^D for all such substitutions, regardless of how many characters the markup originally took. For example, both _ and __ markup notations are replaced by a single ^C or ^D. So after processing using the RedPen AsciiDoctor backend, our sentence would look like:

This is ^Cbold^D.

This method uses these ^C/^D markers to calculate what has been omitted from the source sentence, and therefore what the source sentence character offset should be for the normalized sentence.

Parameters:

lineOffset - the position of this line

processed - the RedPen AsciiDoctor backend processed sentence

source - the source sentence

sentenceExtractor - our sentence extractor

sentences - a list of sentences to add discovered sentences to

Returns:

the new offset position, after we've processed these sentences