Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Activity
djencks
@djencks
Ewan, I assume you’ve figured out the differences between block processors, block macros, and inline macros by now :-) ?
Ewan Edwards
@eskwayrd
@djencks I did look at your asciidoctor-antora-indexer, but the setup to render a sub-document seemed overly complex for what I was trying to do. I did try adapting that work, but never managed to get it to work correctly in my extension.
Debugging this is difficult, since there is a lot of context in flight. A single console.log tends to emit hundreds or thousands of lines of detail.
djencks
@djencks
:-)
Ewan Edwards
@eskwayrd
I feel that I’m aware of the diffrerences in the processors and macros. I likely started off on the wrong foot by trying to coerce an inline macro to create multiple blocks. :-)
djencks
@djencks
Have you tried registering your earlier code as a block macro rather than inline macro? As an inline macro, the markup is going to appear as content, as you saw. As a block macro, there’s some chance it will get processed as desired:-)
Ewan Edwards
@eskwayrd
I’ll give that a shot. I should be able to see if that is promising in a few minutes.
djencks
@djencks
As Dan said, inline macros generally aren’t suitable for producing blocks.
👍
Ewan Edwards
@eskwayrd
What does self.onContexts do? I imagine it narrows the scope of where the macro can be invoked. So, I’d want paragraph as my context?
Dan Allen
@mojavelinux
if you are making a custom block, then onContexts determines which block delimiters it can be used on. so, for example, to use it over a ====, you set it to example (technically, this is not a context, but rather a structural container, but here the term is used interchangeably)
this does not apply to block macros, only blocks
Ewan Edwards
@eskwayrd
:+1:
Dan Allen
@mojavelinux
this is information that still needs to make its way into the docs: asciidoctor/asciidoctor-documentation-planning#30
basically, for 5 years (in some cases more), all docs issues stalled because Antora didn't exist
I expect things to change radically now that we have a real documentation site and not just some strung together pages
you could almost argue that the problem with docs in Asciidoctor is what led us to create Antora. It was always in the back of my mind, but that really forced it over the edge. so this is very much coming full circle right now
I kept filing issues with information, but it was just never going anywhere
James Elliott
@brunchboy
That’s so cool, and the ice is about to break!
Dan Allen
@mojavelinux
maybe we can even attract some docs writers :heart_eyes:
indeed!
Ewan Edwards
@eskwayrd
I expect that we’ll see plenty more extensions being created once potential authors get a little more hand-holding. You and David provide great support, but it’s very hard to find relevant content within these Gitter conversations.
Dan Allen
@mojavelinux
as someone who has now been heavily using Antora, I can say from my own experience that I love it. there are definitely still gaps, but nothing that stops me from getting writing done and published.
James Elliott
@brunchboy
And interactive support doesn’t scale nearly as well as a good documentation site.
Dan Allen
@mojavelinux
absolutely
on the other hand, I cannot do it all myself. I already work close to 24/7/365 days of the year (that's hardly an exaggeration)
(accepting that has been very hard for me to do)
Ewan Edwards
@eskwayrd

After trying a few variations, these few lines appear to do what I’m looking for:

      const wrapper = self.createBlock(parent, 'open', [], {})
      self.parseContent(wrapper, output.join('\n'))
      parent.blocks.push(wrapper)

The next iteration would be to remove the open block, which likely means creating each listing block separately.

djencks
@djencks
👍
Ewan Edwards
@eskwayrd
Thanks for the assist!
Actually. what’s happening is that the markup for the source blocks is being parsed correctly, but the include within is appearing as text, rather than functioning as an include. What would I need to do to achieve that?
Likely, I need to enable macro substitutions. :-)
Ewan Edwards
@eskwayrd
This doesn’t appear to be doing anything:
output = parent.$apply_subs(output.join('\n'), ['macros'])
djencks
@djencks
I don’t think include:: is a macro, it just looks like one.
djencks
@djencks
It’s been a while since I looked at this bit of code. You might need to do something like turn your generated content into the sort of reader that can deal with includes. This is when I end up spending serious time with the debugger:-)
Alternatively you might consider doing the includes yourself using the antora content catalog.
djencks
@djencks
Back at my computer... Yes, you need to make sure you supply a PreprocessorReader rather than a plain Reader, which is what you get calling parseContent with just text. You can see an example that works (but probably has a lot more Opalese than you need) in my https://gitlab.com/djencks/asciidoctor-ainclude in lib/ainclude.js line 105.
2 replies
Dan Allen
@mojavelinux
you don't need to run parseContent. that's already going to happen when you return the block
6 replies
you only use parseContent when you need to convert it, then extract something, then put it back into the tree
that's rare
Dan Allen
@mojavelinux
since you are writing extensions in asciidoctor.js, you may want to bring it up in the asciidoctor/asciidoctor.js channel. I'm sure Guillaume would be keen to get more advanced examples added to the new docs: https://asciidoctor-docs.netlify.app/asciidoctor.js/latest/extend/extensions/
that's really where information about writing extensions in asciidoctor.js should point. Antora should really only cover it to the extent of how to integrate them into the playbook and perhaps how to access Antora's context
part of the focus of the new docs is to make sure the docs for each project is providing the docs for its own part and we aren't trying to duplicate docs all over the place
djencks
@djencks
speaking of duplication, since I've been thinking about extension docs, I was wondering if it would be a good idea to have one set of extension docs for all languages, e.g. generic text and then a tabset for the implementation in each of ruby, js, java
hmm, re using an explicit PreprocessorReader, I guess my example needs it because of some faulty assumptions in asciidoctor about subdocuments (that they are always table cells).
Dan Allen
@mojavelinux
yes, it would be useful to talk about extensions in general (showing the signature in a pseudo language perhaps) and then getting into specific Ruby examples separately. since the extension model is defined in Asciidoctor, those docs would live in Asciidoctor. but they don't have to jump right into the Ruby API specifically. as for showing a specific example in different languages, that's a big trickier. I'd have to think about that. because I don't really want the examples for AsciidoctorJ and Asciidoctor.js to cross over into Asciidoctor. but we could maybe imagine importing it from the other repo (using an include) if it is present.
but before we get into all that, I think we need some basic concrete docs in the interim because I think the extension model is really glossed over for being such an important part of Asciidoctor
djencks
@djencks
Sure. Just an idea to consider. There’s lots to write before we need to decide.
Dan Allen
@mojavelinux
indeed. an idea to consider for sure. and I'm itching to see some tabsets put to use.
Guillaume Grossetie
@Mogztter
since you are writing extensions in asciidoctor.js, you may want to bring it up in the asciidoctor/asciidoctor.js channel. I'm sure Guillaume would be keen to get more advanced examples added to the new doc
:+1: