Login  Register

Custom styles support

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options Options
Embed post
Permalink
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Custom styles support

pepijnve
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?
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

mojavelinux
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.

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?


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Custom-styles-support-tp441.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

pepijnve
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.
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

mojavelinux
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.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Custom-styles-support-tp441p443.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

pepijnve
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).
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

asotobu
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.

Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

asotobu
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.

Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Custom styles support

mojavelinux
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.

-Dan


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.

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).


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Custom-styles-support-tp441p446.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--