ODF support in AsciiDoc

89 views
Skip to first unread message

Dag Wieers

unread,
Dec 9, 2011, 11:17:09 AM12/9/11
to asci...@googlegroups.com
Hi,

It's clear that ODF support will not be part of AsciiDoc. Which, if you
had told me from the start, would probably have not motivated me to write
the ODF backend, but I am at a point of no return now... Well played ;-)

But I am concerned that an output backend may never become really popular
(or even known) if it is not mentioned in the User Guide as prominently as
the other output backends (eg. in the list of attributes each backend
supports etc...). And I wouldn't be the author if I wasn't convinced about
the potential the ODF backend brings to AsciiDoc.

So is there something we can do to promote backends more/better in a
future release ?

Also, I plan to release the ODF backend (as-is) when the next AsciiDoc
version is ready. Even if not everything works exactly as I want, I hope a
wider availability might bring more people to this project to help adding
more themes or finish the backend.

It should be clear however that format style (names), attributes and
constructs may still change when we improve the functionality. (eg. the
book doctype currently hardcodes a lot of how the cover looks, which we
might influence through attributes instead)

Thanks for your help throughout !
--
-- dag wieers, d...@wieers.com, http://dag.wieers.com/
-- dagit linux solutions, in...@dagit.net, http://dagit.net/

[Any errors in spelling, tact or fact are transmission errors]

Lex Trotman

unread,
Dec 9, 2011, 5:50:28 PM12/9/11
to asci...@googlegroups.com
On Sat, Dec 10, 2011 at 3:17 AM, Dag Wieers <d...@wieers.com> wrote:
> Hi,
>
> It's clear that ODF support will not be part of AsciiDoc. Which, if you had
> told me from the start, would probably have not motivated me to write the
> ODF backend, but I am at a point of no return now... Well played ;-)

I think you give too much credit for pre-planning :)

>
> But I am concerned that an output backend may never become really popular
> (or even known) if it is not mentioned in the User Guide as prominently as
> the other output backends (eg. in the list of attributes each backend
> supports etc...). And I wouldn't be the author if I wasn't convinced about
> the potential the ODF backend brings to AsciiDoc.
>

As asciidoc only just supports plugin backends (and a2x plugins next
release) its not surprising that the documentation doesn't say much
about them. Especially as there are no mature full service plugin
backends yet (all so far are for specialised uses).

If there are places where the documentation should better address
plugin backends then changes should be proposed to Stuart. But
expanding the manual to cover each backend that goes on the plugins
page just isn't viable. Each plugin should have its own manual
addressing the differences from asciidoc/a2x

For ODT, the only documentation available is the readme file.

> So is there something we can do to promote backends more/better in a future
> release ?

Well if you think it is mature enough then it should be proposed to
Stuart that it be added to the plugins page on the website, even if
marked as in-development. But it needs a proper manual, see the slidy
backend for example.

>
> Also, I plan to release the ODF backend (as-is) when the next AsciiDoc
> version is ready. Even if not everything works exactly as I want, I hope a
> wider availability might bring more people to this project to help adding
> more themes or finish the backend.

Putting it on the website should get more bugs to fix :) I don't know
about more help. To quote some bloke who knows a thing or two about
open source software (Linus Torvolds) "when you release open source
software you have to assume you will be doing all the work yourself,
and be prepared for that". Only in the longer term will you get more
contributors. (maybe I souldn't have pointed that out :)

>
> It should be clear however that format style (names), attributes and
> constructs may still change when we improve the functionality. (eg. the book
> doctype currently hardcodes a lot of how the cover looks, which we might
> influence through attributes instead)

Well, such comments mark the backend as immature and discourage users,
so it won't get tested so much.

So you need to decide on backward compatibility or other means to
support users' existing documents. Adding extra capabilities like
adjustable cover pages is fine, but it should still support any
existing files.

As the asciidoc project is not supporting the ODT backend it is better
from a purely practiacal point of view for it to remain a separate
entity (on github, or wherever) so that it can be accessed by us,
especially whilst still in heavy development.

For something like the ODT backend to be included in the standard
asciidoc distribution it needs to be far more mature than it is now,
it needs to be properly documented and it needs to have a sufficient
user base that Stuart is convinced it is worth it.

The available maintainer effort for asciidoc is small, so the project
taking on an immature backend is going to use all those resources,
preventing work on other parts of asciidoc. Thats why I am
emphasising maturity, there should not be big changes and lots of bugs
if it is to be considered to be included as part of the asciidoc
project.

As no popular "full service" backend plugin exists, the possibility of
packaging such plugins with the asciidoc distribution has not been
considered yet.

That stage is a long way away IMHO, making comments that "it will
never be part of asciidoc" is way premature at the moment.

Cheers
Lex

PS the comments above are my own and have not been discussed or
endorsed by Stuart.

Dag Wieers

unread,
Dec 9, 2011, 6:42:50 PM12/9/11
to asci...@googlegroups.com
On Sat, 10 Dec 2011, Lex Trotman wrote:

> On Sat, Dec 10, 2011 at 3:17 AM, Dag Wieers <d...@wieers.com> wrote:
>
>> It's clear that ODF support will not be part of AsciiDoc. Which, if you had
>> told me from the start, would probably have not motivated me to write the
>> ODF backend, but I am at a point of no return now... Well played ;-)
>
> I think you give too much credit for pre-planning :)

I was only kidding :-) I don't regret anything, it's been all joy !


> As asciidoc only just supports plugin backends (and a2x plugins next
> release) its not surprising that the documentation doesn't say much
> about them. Especially as there are no mature full service plugin
> backends yet (all so far are for specialised uses).
>
> If there are places where the documentation should better address
> plugin backends then changes should be proposed to Stuart. But
> expanding the manual to cover each backend that goes on the plugins
> page just isn't viable. Each plugin should have its own manual
> addressing the differences from asciidoc/a2x

Well, I would prefer if the plugins/backends were mentioned
in a section of the User Guide and that eg. output-specific attribute
overview would also include other backends (to give it somewhat more
exposure). This would allow for converging attributes and functionality,
or can motivate others to contribute similar functionality in other
backends.


> For ODT, the only documentation available is the readme file.

Currently, yes. But I am happy to help wherever needed.


>> So is there something we can do to promote backends more/better in a future
>> release ?
>
> Well if you think it is mature enough then it should be proposed to
> Stuart that it be added to the plugins page on the website, even if
> marked as in-development. But it needs a proper manual, see the slidy
> backend for example.

Yes, and an installable zip-file. We'll get to that eventually once I know
for sure the number of changes will be manageable.


>> Also, I plan to release the ODF backend (as-is) when the next AsciiDoc
>> version is ready. Even if not everything works exactly as I want, I hope a
>> wider availability might bring more people to this project to help adding
>> more themes or finish the backend.
>
> Putting it on the website should get more bugs to fix :) I don't know
> about more help. To quote some bloke who knows a thing or two about
> open source software (Linus Torvolds) "when you release open source
> software you have to assume you will be doing all the work yourself,
> and be prepared for that". Only in the longer term will you get more
> contributors. (maybe I souldn't have pointed that out :)

Haha :)


>> It should be clear however that format style (names), attributes and
>> constructs may still change when we improve the functionality. (eg. the book
>> doctype currently hardcodes a lot of how the cover looks, which we might
>> influence through attributes instead)
>
> Well, such comments mark the backend as immature and discourage users,
> so it won't get tested so much.

True.


> That stage is a long way away IMHO, making comments that "it will
> never be part of asciidoc" is way premature at the moment.

That's not what I understood from the discussions. But we'll see where
this is going first, I agree with your reasoning though.

Stuart Rackham

unread,
Dec 9, 2011, 7:24:17 PM12/9/11
to asci...@googlegroups.com

On 10/12/11 05:17, Dag Wieers wrote:
> Hi,
>
> It's clear that ODF support will not be part of AsciiDoc. Which, if you had told
> me from the start, would probably have not motivated me to write the ODF
> backend, but I am at a point of no return now... Well played ;-)
>

There was no intention to mislead, my desire to keep new filters (and by
extension backends) out of the AsciiDoc distribution was no secret, but maybe I
should have been more explicit:

http://groups.google.com/group/asciidoc/browse_thread/thread/40c64cd33ee1905c/578e9469fbaf5

The primary motivation for the plugin architecture was to enable filters and
backends to be implemented as plugins. The idea is to decouple the AsciiDoc core
from backends and filters.

The HTML and DocBook backends (and successors) will stay in the core
distribution but I envisage that all new backends will be implemented as
plugins. From a maintenance standpoint it's the only sane way forward.

The ODF backend is a great use-case for the plugin architecture -- if we can get
it working as a plugin then almost any XML/SGML backend should be possible.


> But I am concerned that an output backend may never become really popular (or
> even known) if it is not mentioned in the User Guide as prominently as the other
> output backends (eg. in the list of attributes each backend supports etc...).
> And I wouldn't be the author if I wasn't convinced about the potential the ODF
> backend brings to AsciiDoc.
>
> So is there something we can do to promote backends more/better in a future
> release ?
>

You've got a point, section 4 of the manual needs to draw the readers attention
to the plugins webpage (http://www.methods.co.nz/asciidoc/plugins.html) and any
other locations in the manual and website that discuss backends.

Personally I'd like to push the slidy and wordpress plugins along with all
filters (with the exception of the source filter) out of the core, but that
would probably raise a backward incompatibility hue and cry.

I'm not sure that popularity is all it's cracked up to be, one of the nice
things about AsciiDoc is that it flies under the radar -- users are generally
motivated discerning types that know what they're looking for, consequently the
mailing list is relatively low noise.


> Also, I plan to release the ODF backend (as-is) when the next AsciiDoc version
> is ready. Even if not everything works exactly as I want, I hope a wider
> availability might bring more people to this project to help adding more themes
> or finish the backend.
>

With your permission I'll cite the ODF backend prominently in the next release
announcement. All that's holding back the next AsciiDoc release are: any ODF
show-stoppers; finalizing and implementing the comment/annotation syntax; the
documentation changes discussed above; and I need to read the 'Sections with
multiple columns' thread.

Cheers, Stuart

Dag Wieers

unread,
Dec 9, 2011, 7:45:48 PM12/9/11
to asci...@googlegroups.com

Too late ! Already implemented ;-) But your advise is very welcome
nevertheless...

Currently I do it like this:

[columns,2]
====
body
====


Which works for the intended purpose, and the stylesheet is more simple
than my example. You don't have to specify the weight of each column if
you want them to be proportional (and honestly, who wouldn't want that
anyway). But the stylesheet allows any customization nevertheless.

Now I am going to start implementing the new comment/annotation proposal.
Using a comment-block instead of a listingblock !

Stuart Rackham

unread,
Dec 9, 2011, 7:53:44 PM12/9/11
to asci...@googlegroups.com

Great quote, certainly echoes my experience.

I agree with all this Lex.

I'm not saying that non-HTML and DocBook will never be in the core, just that
this is the current position.

I guess the problem is how to ensure backend plugins are prominently visible and
are not seen as second class citizens. As well as raising user awareness in the
documentation they also have to be painless to install and uninstall -- maybe
the backend option should accept a URL as well as a file name e.g.

asciidoc --backend install
https://github.com/downloads/srackham/asciidoc-fossil-backend/fossil.zip

Cheers, Stuart

Dag Wieers

unread,
Dec 9, 2011, 8:35:17 PM12/9/11
to asci...@googlegroups.com
On Sat, 10 Dec 2011, Dag Wieers wrote:

> Now I am going to start implementing the new comment/annotation proposal.
> Using a comment-block instead of a listingblock !

I get the following error I do not understand:

asciidoc: WARNING: test-odt.txt: line 257: missing section: [comment]

While I am using the following in odt.conf:

[blockdef-comment]
delimiter=^/{4,}$
options=skip
posattrs=style
annotation-style=template="annotationblock",options="sectionbody",posattrs=["style","name","date"]
comment-style=template="commentblock",options="sectionbody"

[annotationblock]
{hideannotations%}<text:p text:style-name="empty"><office:annotation><dc:creator>{name=AsciiDoc}</dc:creator><dc:date>{date=}</dc:date><text:p>|</text:p></office:annotation></text:p>

[commentblock]
{showcomments#}<text:p text:style-name="comment">|</text:p>

This would allow for:

== Comments and annotations
// This is a comment

[annotation,dag,2011-12-03]
////
This is an example annotation that should be a proper annotation in
LibreOffice or OpenOffice.
////

[annotation]
////
This is an anonymous annotation.
////

[comment]
////
This is a block comment.
////

Line 257 is the line containing "[comment]". If I add a section:

[comment]
DUH!

to my odt.conf, DUH! is only printed once for that chapter (even though
more than one block was specified). I do not understand this behavior. It
seems different than the other blocks.

Help is required !

Lex Trotman

unread,
Dec 9, 2011, 8:45:31 PM12/9/11
to asci...@googlegroups.com
Hi Stuart,

[...]


> I guess the problem is how to ensure backend plugins are prominently visible

Probably need to mention them on the home page, install page, start of
the user guide, all pointing to where they are at the end of the user
guide.

> and are not seen as second class citizens. As well as raising user awareness
> in the documentation they also have to be painless to install and uninstall
> -- maybe the backend option should accept a URL as well as a file name e.g.
>
>  asciidoc --backend install
> https://github.com/downloads/srackham/asciidoc-fossil-backend/fossil.zip

That would help.

For what its worth my experience from another project that gathered a
number of plugins is that:

1. a few are distributed with the project and automatically installed
with the base package, this got into the major distros

2. eventually a combined plugins project was created with a bunch of
the popular plugins all in the same VCS repository but still with
their individual maintainers and with a shared website and all
installed in one package, this also got into the major distros

3. there are a few plugins that remain defiantly independent but are
pointed to from the plugin project website

The big thing was distro acceptance, base project ok, fine and so
those plugins were always available (though the user has to enable
them) but individual plugins were never accepted by the distros, it
took the combined package to get them accepted.

Packages in the distro repositories provides a better user experience
since they install with their normal installer/uninstaller and have to
install at most two packages.

In this model the main project is responsible for the combined plugins
package and the maintainers of individual plugins send pull requests
from their own github forks. As the main project has always got the
blame for malcontent plugins it is now starting to be more assertive
regarding plugin quality.

Cheers
Lex

Lex Trotman

unread,
Dec 9, 2011, 8:57:50 PM12/9/11
to asci...@googlegroups.com
On Sat, Dec 10, 2011 at 12:35 PM, Dag Wieers <d...@wieers.com> wrote:
> On Sat, 10 Dec 2011, Dag Wieers wrote:
>
>> Now I am going to start implementing the new comment/annotation proposal.
>> Using a comment-block instead of a listingblock !
>
>
> I get the following error I do not understand:
>
>    asciidoc: WARNING: test-odt.txt: line 257: missing section: [comment]
>
> While I am using the following in odt.conf:
>
>    [blockdef-comment]
>    delimiter=^/{4,}$
>    options=skip

The above makes it a real comment, ie not output. This option should
be part of the default style definition so only that gets skipped, ie
a real comment. (I think, I havn't had a chance to try it).

Cheers
Lex

[...]

Dag Wieers

unread,
Dec 9, 2011, 9:03:25 PM12/9/11
to asci...@googlegroups.com

I tried this too (which I liked more), but to no avail:

[blockdef-comment]
delimiter=^/{4,}$
options=sectionbody
posattrs=style,name,date
default-style=options="skip"
annotation-style=template="annotationblock"
comment-style=template="commentblock"

But it spawns the same error:

asciidoc: WARNING: test-odt.txt: line 257: missing section: [comment]

So I have been trying a lot of other stuff. But I rather understand what
this error means. And why defining a [comment] section fixes both this
error and the same error for [annotation] while only showing DUH! once :-(

Lex Trotman

unread,
Dec 9, 2011, 10:07:40 PM12/9/11
to asci...@googlegroups.com

Unfortunately I think there is some internal hardcoded processing of
blocks called "comment" in asciidoc.py. The following works fine:

[blockdef-fred]
delimiter=^%{4,}$
posattrs=style,name,date
style=default
default-style=template="skipcomment",options=("skip",)
annotation-style=template="annotationblock"
comment-style=template="commentblock"

[annotationblock]
{hideannotations%}<text:p
text:style-name="empty"><office:annotation><dc:creator>{name=AsciiDoc}</dc:creator><dc:date>{date=}</dc:date><text:p>|</text:p></office:annotation></text:p>

[commentblock]
{showcomments#}<text:p text:style-name="comment">|</text:p>

[skipcomment]
{empty}

If the block name is [blockdef-comment] it doesn't work.

(had to change the delimeter otherwise the standard comment is
recognised first and it never gets to this, but the point is that if
the block name is different its ok)

I don't think Stuart has made the fix yet to allow his suggested:

[style]
////
a styled comment
////

syntax.

Cheers
Lex

>
> --
> -- dag wieers, d...@wieers.com, http://dag.wieers.com/
> -- dagit linux solutions, in...@dagit.net, http://dagit.net/
>
> [Any errors in spelling, tact or fact are transmission errors]
>

> --
> You received this message because you are subscribed to the Google Groups
> "asciidoc" group.
> To post to this group, send email to asci...@googlegroups.com.
> To unsubscribe from this group, send email to
> asciidoc+u...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/asciidoc?hl=en.
>

Stuart Rackham

unread,
Dec 9, 2011, 11:43:43 PM12/9/11
to asci...@googlegroups.com

Correct! The devil is always in the details. asciidoc does not consume attribute
lists that precede comments. I'm working on the complete annotation block
comment patch, but here's the diff:

8<-----------------------------
diff -r 480a633f0fb7 asciidoc.conf
--- a/asciidoc.conf�����Sun Dec 04 12:31:25 2011 +1300
+++ b/asciidoc.conf�����Sat Dec 10 17:23:24 2011 +1300
@@ -288,6 +288,8 @@


[blockdef-comment]
delimiter=^/{4,}$
options=skip

+posattrs=style
+annotation-style=template="commentblock",options=(),subs=["verbatim"]

[blockdef-sidebar]
delimiter=^\*{4,}$
diff -r 480a633f0fb7 asciidoc.py
--- a/asciidoc.py�������Sun Dec 04 12:31:25 2011 +1300
+++ b/asciidoc.py�������Sat Dec 10 17:23:24 2011 +1300
@@ -3030,9 +3030,8 @@
AbstractBlock.translate(self)
reader.read() # Discard delimiter.
attrs = {}
- if self.short_name() != 'comment':
- BlockTitle.consume(attrs)
- AttributeList.consume(attrs)
+ BlockTitle.consume(attrs)
+ AttributeList.consume(attrs)
self.merge_attributes(attrs)
self.push_blockname()
options = self.parameters.options
8<---------------------------

Cheers, Stuart

Stuart Rackham

unread,
Dec 9, 2011, 11:59:33 PM12/9/11
to asci...@googlegroups.com

On 10/12/11 14:45, Lex Trotman wrote:

Really good to hear about this plugin experience. I like the idea of a separate
'AsciiDoc Plugins' project that would work to create a plugins bundle. It's not
something I have spare time for though.

Cheers, Stuart

> Cheers
> Lex
>

Stuart Rackham

unread,
Dec 10, 2011, 12:26:48 AM12/10/11
to asci...@googlegroups.com

Ok. This is one of the neat things about Open Source: you don't need the boss's
permission to proceed. This is also an argument in favor of backend plugins.


> Currently I do it like this:
>
> [columns,2]
> ====
> body
> ====
>
>
> Which works for the intended purpose, and the stylesheet is more simple than my
> example. You don't have to specify the weight of each column if you want them to
> be proportional (and honestly, who wouldn't want that anyway). But the
> stylesheet allows any customization nevertheless.
>
> Now I am going to start implementing the new comment/annotation proposal. Using
> a comment-block instead of a listingblock !
>

I'll do likewise for HTML and DocBook backends.

Cheers, Stuart

Dag Wieers

unread,
Dec 10, 2011, 3:06:44 AM12/10/11
to asci...@googlegroups.com
On Sat, 10 Dec 2011, Stuart Rackham wrote:

> On 10/12/11 16:07, Lex Trotman wrote:
>>
>> Unfortunately I think there is some internal hardcoded processing of
>> blocks called "comment" in asciidoc.py. The following works fine:
>

> Correct! The devil is always in the details. asciidoc does not consume
> attribute lists that precede comments. I'm working on the complete annotation
> block comment patch, but here's the diff:

Even with this, it doesn't work. I tried this as well. (Looking for
'comment' was quite easy, there were two conditional statements I removed
to make comments in line with other blocks. To no avail :-/

Stuart Rackham

unread,
Dec 10, 2011, 10:31:09 PM12/10/11
to asci...@googlegroups.com

On 10/12/11 21:06, Dag Wieers wrote:
> On Sat, 10 Dec 2011, Stuart Rackham wrote:
>
>> On 10/12/11 16:07, Lex Trotman wrote:
>>>
>>> Unfortunately I think there is some internal hardcoded processing of
>>> blocks called "comment" in asciidoc.py. The following works fine:
>>
>> Correct! The devil is always in the details. asciidoc does not consume
>> attribute lists that precede comments. I'm working on the complete annotation
>> block comment patch, but here's the diff:
>
> Even with this, it doesn't work. I tried this as well. (Looking for 'comment'
> was quite easy, there were two conditional statements I removed to make comments
> in line with other blocks. To no avail :-/
>

Hi Dag

I've attached a patch which works with the xhtml11 backend.

I'm not happy with it though:

- I haven't included the hideannotations attribute as it requires an asciidoc
code change (the template is split at '|' before attributes are processed which
makes it impossible to drop the template completely).

- The DocBook 'remark' element will limit the annotation to a single paragraph
because 'remark' can't contain block elements.

For such a small addition on top of the existing comments mechanism I'm getting
that uneasy feeling that the cure is worse than the disease. Outside of ODF
there's never been a request or a use-case for a displayable block comments, so
for now I'm not adding it to the default AsciiDoc syntax. I think the best
course of action is to go back to the original annotation listingblock style in
odf.conf. Source containing annotations will be ODF specific but they won't
break other backends -- you'll get a 'missing style' warning but the annotation
will be displayed in a listing block.

Cheers, Stuart

annotation.patch

Dag Wieers

unread,
Dec 11, 2011, 4:20:53 PM12/11/11
to asci...@googlegroups.com
On Sun, 11 Dec 2011, Stuart Rackham wrote:

> On 10/12/11 21:06, Dag Wieers wrote:
>> On Sat, 10 Dec 2011, Stuart Rackham wrote:
>> > On 10/12/11 16:07, Lex Trotman wrote:
>> >
>> > > Unfortunately I think there is some internal hardcoded processing of
>> > > blocks called "comment" in asciidoc.py. The following works fine:
>> >
>> > Correct! The devil is always in the details. asciidoc does not consume
>> > attribute lists that precede comments. I'm working on the complete
>> > annotation
>> > block comment patch, but here's the diff:
>>
>> Even with this, it doesn't work. I tried this as well. (Looking for
>> 'comment'
>> was quite easy, there were two conditional statements I removed to make
>> comments
>> in line with other blocks. To no avail :-/
>>
>

> I've attached a patch which works with the xhtml11 backend.

Thanks.


> For such a small addition on top of the existing comments mechanism I'm
> getting that uneasy feeling that the cure is worse than the disease. Outside
> of ODF there's never been a request or a use-case for a displayable block
> comments, so for now I'm not adding it to the default AsciiDoc syntax. I
> think the best course of action is to go back to the original annotation
> listingblock style in odf.conf. Source containing annotations will be ODF
> specific but they won't break other backends -- you'll get a 'missing style'
> warning but the annotation will be displayed in a listing block.

Can we however still allow using comment blocks for ODF ? E.g. by making
the special 'comment' behaviour optional (but default as is now). I really
want to use comment blocks, rather than listing blocks in this case.

However, I still cannot make it work. With the changes you suggested, the
comment blocks are still not visible. See asciidoc-odf odt.conf and
examples/test-odt.txt. Only the inline comment is being outputted.

Dag Wieers

unread,
Dec 11, 2011, 5:03:00 PM12/11/11
to asci...@googlegroups.com
On Sun, 11 Dec 2011, Dag Wieers wrote:

> On Sun, 11 Dec 2011, Stuart Rackham wrote:
>
> Can we however still allow using comment blocks for ODF ? E.g. by making the
> special 'comment' behaviour optional (but default as is now). I really want
> to use comment blocks, rather than listing blocks in this case.

Still relevant :)


> However, I still cannot make it work. With the changes you suggested, the
> comment blocks are still not visible. See asciidoc-odf odt.conf and
> examples/test-odt.txt. Only the inline comment is being outputted.

No longer relevant. After looking at your xhtml11 example and applying
that to what I was doing, it magically worked ! :)

Stuart Rackham

unread,
Dec 11, 2011, 6:31:38 PM12/11/11
to asci...@googlegroups.com

On 12/12/11 11:03, Dag Wieers wrote:
> On Sun, 11 Dec 2011, Dag Wieers wrote:
>
>> On Sun, 11 Dec 2011, Stuart Rackham wrote:
>>
>> Can we however still allow using comment blocks for ODF ? E.g. by making the
>> special 'comment' behaviour optional (but default as is now). I really want to
>> use comment blocks, rather than listing blocks in this case.
>
> Still relevant :)

On the face of it, it seems reasonable that comment blocks should consume
preceding attribute lists just like other delimited blocks. But I've just
discovered that it introduces backward incompatibility and fails the following
example from the test suite (from tests/data/testcases.txt):

[[comment_block]]
.Block title
/////////////////////////////////////////////////////////////////////
Delimited comment block does not consume titles or attributes.
/////////////////////////////////////////////////////////////////////
Lorum ipsum.

Both the block title and the comment_block anchor attributes will be consumed by
the comment block which is neither the intended or the obvious behavior.

Dag Wieers

unread,
Dec 12, 2011, 5:51:46 PM12/12/11
to asci...@googlegroups.com
On Mon, 12 Dec 2011, Stuart Rackham wrote:

> On 12/12/11 11:03, Dag Wieers wrote:
>> On Sun, 11 Dec 2011, Dag Wieers wrote:
>>
>> > On Sun, 11 Dec 2011, Stuart Rackham wrote:
>> >
>> > Can we however still allow using comment blocks for ODF ? E.g. by making
>> > the
>> > special 'comment' behaviour optional (but default as is now). I really
>> > want to
>> > use comment blocks, rather than listing blocks in this case.
>>
>> Still relevant :)
>
> On the face of it, it seems reasonable that comment blocks should consume
> preceding attribute lists just like other delimited blocks. But I've just
> discovered that it introduces backward incompatibility and fails the
> following example from the test suite (from tests/data/testcases.txt):
>
> [[comment_block]]
> .Block title
> /////////////////////////////////////////////////////////////////////
> Delimited comment block does not consume titles or attributes.
> /////////////////////////////////////////////////////////////////////
> Lorum ipsum.
>
> Both the block title and the comment_block anchor attributes will be consumed
> by the comment block which is neither the intended or the obvious behavior.

Right, but that should not be a problem if the old behavior is possible
by the default 'options'.

In that case, only annotation-style would show the new behavior. That's
what I meant before with: making the old behavior optional (but default).

Stuart Rackham

unread,
Dec 12, 2011, 10:10:13 PM12/12/11
to asci...@googlegroups.com

Ok, there is no 'comment' option but there is a 'skip' option. So change the
hardwired "skip attributes list if comment block syntax" to "skip if 'skip'
option is set".

Problem is that there's a Catch 22: You need to read and process the attribute
list to determine if you should read and process the attribute list.

So needed to process attributes list and then un-process it if there is a 'skip'
option, quite tricky.

It's in the trunk, hope it doesn't introduce any regressions:
http://code.google.com/p/asciidoc/source/detail?r=320117a96e0ac6ae260a934ec74c967dbc5a5686

Cheers, Stuart

Dag Wieers

unread,
Dec 13, 2011, 9:20:23 AM12/13/11
to asci...@googlegroups.com

Thanks for clarifying. I understand that I may oversimplify my wishes to
stay away from understanding what asciidoc is doing under the hood ;-) But
I am very grateful for your help and feedback !


> It's in the trunk, hope it doesn't introduce any regressions:
> http://code.google.com/p/asciidoc/source/detail?r=320117a96e0ac6ae260a934ec74c967dbc5a5686

I will test right away !

Reply all
Reply to author
Forward
0 new messages