Questions about readDocumentStructure()

> Vincent,
>
> At the moment, there are two slightly competing AST models in AsciidoctorJ. For general purpose tree traversal, I recommend using the lower-level API, which can be reached using the load API.
>
> Let's assume we are reading the following AsciiDoc source:
>
> [source,asciidoc]
> ----
> = Document Title
>
> preamble
>
> == Section A
>
> section content with *bold*
>
> == Section B
>
> section content with *italic*
> ----
>
> Here's how you can load and walk (naively) the tree structure:
>
> [source,java]
> ----
> String source = "...";
> Asciidoctor asciidoctor = JRubyAsciidoctor.create();
> Map options = new HashMap();
> Document document = asciidoctor.load(source, options);
> for (AbstractBlock block : document.blocks()) {
> System.out.println(":" + block.context());
> for (AbstractBlock childBlock : block.blocks()) {
> if (childBlock.context().equals("paragraph")) {
> System.out.println(" :paragraph, lines: " + ((Block) childBlock).lines());
> }
> else {
> System.out.println(" :" + childBlock.context());
> }
> }
> }
>
> ----
>
> NOTE: I'm not sure why the AbstractBlock and Block interfaces are not aligned (hence the cast). That looks like a bug in the AST. The Block interface gives you access to the raw lines (Collection) and raw source (String).
>
> When you run the code in the previous listing, you should see the following output:
>
> ....
> :preamble
> :paragraph, lines: ["preamble"]
> :section
> :paragraph, lines: ["section content with *bold*"]
> :section
> :paragraph, lines: ["section content with *italic*"]
>
> ....
>
>
> The AST only provides access to block-level content (sections, paragraphs, figures, etc). You cannot access inline elements because they are not parsed into a tree in the underlying Ruby implementation. We do have plans to do it (see https://github.com/asciidoctor/asciidoctor/issues/61). As it stands, inline elements are converted as they are parsed (for example, see https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/substitutors.rb#L575). That's why the ContentPart currently gives you converted output (though it should provide lines() and source() methods too).
>
> Currently, not all of the AST methods in the Ruby API are mapped in AsciidoctorJ. For instance, the Ruby API provides access to the line number of a block, but that's not currently available via AsciidoctorJ. ContentPart should also provide access to the Block, where relevant. Let's make it happen.
>
> To help us understand your use case, could you explain what XWiki needs to do with the AST? That way, we can focus on getting the features mapped or implemented that are needed. 

> Thanks Vincent. Your summary gives me a clear picture of what we need.
>  
> On Sun, Sep 21, 2014 at 9:21 AM, vmassol [via Asciidoctor :: Discussion] <[hidden email](/user/SendEmail.jtp?type=node&node=2272&i=0)> wrote:
> > Here what’s important is that I need to represent what AsciiDoctor gives me as an XDOM. Thus if I get only "section content with *bold*” then it won’t be good enough for me since I’ll need to parse this on my side, understanding the full AsciiDoctor syntax for all types of syntax elements: bolds, links, images, etc.  
> >  
> > I can handle not getting an AST at the level of words but I’ll need to get source parts containing asciidoc syntax into Blocks (formatting, links, images, etc).  
> >  
> > For example the following would be fine for "section content with *bold*”:  
> >  
> > TextBlock(“section content with”)  
> > BoldBlock()
> > TextBlock(“bold”)
>  
>  
>  
> I think the strategy to take here is to start developing an inline parser in Asciidoctor alongside the existing streaming transformer. Once it's fully fleshed out, we can switch to it. But the benefit is that you start to get something to use that at least hits the major syntax sooner rather than later. In other words, we can roll it out gradually. I envision the inline parser to be something you can call on a given block. Keep in mind that not all blocks in Asciidoctor have parsed text, or the text is parsed differently, so it makes sense that it's available as an API (at least in the near term) on the node.