Custom styles support
Locked
 
|
I'm experimenting with writing specifications in asciidoc. In order to make this easier I would like to use custom block styles for things like for instance requirements.
With asciidoc this is possible by adding the [blockdef-*] entries to the config file. I'm now trying to do the same thing with asciidoctor, but this doesn't seem to be supported. I've already tried to be get this to work by adding entries to Asciidoctor::PARAGRAPH_STYLES and/or Asciidoctor::DELIMITED_BLOCKS. This got me one step further, but then I hit checks in lexer.rb that raise 'invalid style' or 'unsupported block type' errors. Are there any plans to support this in asciidoctor? I would be happy to contribute a patch for this, but I would like to know if someone has thought this through already and if so, how they planned to tackle this. My initial thought would be to relax the checks in lexer.rb and catch missing style problems later on during rendering. Is this a good way forward or are the checks in the lexer there for other reasons as well? |
Administrator
|
Yes, this is planned for the upcoming release. It's the last big feature I need to complete, in fact. Here's the issue for tracking this enhancement: In general, you don't want to rely on the parsing constants in asciidoctor.rb or the lexer.rb code directly. That code is very low level and subject to change. (While I'm on the subject, you shouldn't interact with any of the classes in lib/asciidoctor/backends either, since they aren't designed to be extended and may even go away as I further optimize things).
Having said that, what we do want is a nice clean extension system. Issue #79 is the beginning of that development. I'm intentionally starting with a Ruby-based approach to extension because I find using configuration files for such things just ends up limiting you too much to do what you really want. The extension point will receive the text being parsed and have the opportunity to interact with the document in any way, then return a true block object.
The best way to move this feature forward is to either provide feedback on the issue or help review the implementation when I push the code later this week.
Before I close, welcome to the group! -Dan On Thu, Aug 8, 2013 at 1:42 AM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote: I'm experimenting with writing specifications in asciidoc. In order to make this easier I would like to use custom block styles for things like for instance requirements. Dan Allen | http://google.com/profiles/dan.j.allen |
|
|
The proposed API looks exactly like what I need. I'll try to make some time to experiment with the implementation once the code is available.
|
|
Administrator
|
Excellent. Something that would help me while I fiddle with the API is a concrete example of a block that you want to create. Could you post a sample snippet of AsciiDoc you want to be able to handle and the markup you want to produce from it? Thanks! -Dan On Aug 8, 2013 3:47 AM, "pepijnve [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
The proposed API looks exactly like what I need. I'll try to make some time to experiment with the implementation once the code is available. |
|
|
Initially my needs are pretty basic I think. What I want to do is mark paragraphs in the text with a custom style and get them rendered kind of like admonition blocks are rendered.
To be more concrete: [requirement] AsciiDoctor shall support custom block styles should get turned into (for instance) ________________________ *Req {counter:requirement}* AsciiDoctor shall support custom block styles ________________________ In other words, I would like to be able to transform the text from the source document and add autogenerated text to it. The output of the filter in this case is still in asciidoc syntax so it should still be processed for substitutions (or there should be a way to trigger processing on the text via the api). |
|
|
Hi,
first of all welcome to AsciiDoc world :D. I am Alex and I am developing the Asciidoctor-Java-Integration project and also writing about using Asciidoctor for writing documentation (specifications, requirements, user stories, test protocols, manuals) for projects in an Agile way. If you want we can talk about it and of course any question or something you want to discuss feel free to touch me. |
|
|
In reply to this post by pepijnve
Hello,
only one warning, be aware of using counters. Let me show an example where would be better to not use counters: Let's say we are working a PRS (Product Requirement Spec) as: storage-requirements.adoc requirements [[Req-1]] ---- *Req-1* Users shall be able to store data without any interruption ---- And then from a Design document you can do something like: storage-design.adoc Because of link:storage.requirements.html/#Req-1[Requirement-1] we shall use MongoDB ...... Note that in this case we are creating a cross-reference between different documents so you can trace why one decision was taken. With a counter you will never know the requirement number at write time so you won't be able to refer that requirement from another document. In my opinion counters should be used in documents that won't be referenced by any other document, for example in SDS documents. |
|
Administrator
|
In reply to this post by pepijnve
Pepijn, Your example aligns perfectly with the BlockProcessor extension proposed in the changeset for issue #79. The good news is, all the work of inline processing, etc you get for free. All you need to do is decorate the content with the extra text in AsciiDoc format that you need. In your example, you'd create a custom block for the requirement style: class RequirementBlock < BlockProcessor option :contexts, [:paragraph] option :content_model, :simple def process parent, reader, attributes reader.unshift_line "*Req {counter:requirement}*" Block.new parent, :quote, :content_module => @content_model, :source => reader.lines, :attributes => attributes end end That matches your effective AsciiDoc output above, and the following HTML: <div class="blockquote"> <blockquote><strong>Req 1</strong> AsciiDoctor shall support custom block styles.</blockquote> </div> If you need to render a custom template, you change the second argument to Block.new from :quote to the name of your custom template. You'd then need to provide a custom template, which you load using the :template_dirs API option or -T command option. I'll be including a few examples in the release notes so that you can put this into practice. For sure, you're case is covered. On Fri, Aug 9, 2013 at 1:09 AM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote: Initially my needs are pretty basic I think. What I want to do is mark paragraphs in the text with a custom style and get them rendered kind of like admonition blocks are rendered. -- Dan Allen | http://google.com/profiles/dan.j.allen |
«
Return to Asciidoctor :: Discussion
|
1 view|%1 views
| Free forum by Nabble | Edit this page |