Simplified and generalized quote attributes (BREAKING CHANGE)

91 views
Skip to first unread message

Stuart Rackham

unread,
Aug 17, 2010, 5:05:46 PM8/17/10
to asci...@googlegroups.com
This rather long post details a BREAKING CHANGE.

Currently quoted elements can be preceded by an attributes list which can
include up to three positional attributes (color, background color and
size) and a 'role' named attribute. Examples:

[green,#b0e0e6,2]##fun with text##.
[role="input"]*x = 25*

The positional attributes are only applicable to HTML backends and
they emit hard-coded CSS styles; the 'role' attribute emits DocBook
'role' attributes and HTML 'class' attributes. The number and mixed
applicability of these style related attributes is messy and difficult
to remember.

The whole thing can be replaced by a single positional attribute which
translates to HTML 'class' attributes:

- Directly using the AsciiDoc HTML backends.
- Indirectly using the 'docbook' backend (DocBook XSL Stylesheets
translate DocBook 'phrase' elements with 'role' attributes to HTML
'span' elements with the same 'class' attributes; CSS is then used
http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
generated HTML]).

Examples:

[red]#obvious#
[big red yellowback]*very obvious*

The following CSS rules for 'big', 'red' and 'yellowback' class names could
be used to style outputs generated by the previous examples:

span.big { font-size: 2em; }
span.red { color: #e3372e; }
span.yellowback { background: #faf519; }

.Pros
- Allows CSS styling to be applied to both DocBook and HTML outputs
from the same AsciiDoc source.
- Role names are more obvious and easier to remember than the
color and size positional arguments.
- CSS affords arbitrary styling.
- The new attribute can specify multiple class names.

.Cons
- Breaks existing quote attribute behavior.
- You need to create CSS rules.

I've committed a changeset that implements this enhancement:
http://code.google.com/p/asciidoc/source/detail?r=99df82275a29bec4f73daa357ed929e0efdd5722

To revert to the deprecated quote behavior define the 'deprecated-quotes'
attribute in the global `asciidoc.conf` file or on the command-line.

Apologies for any inconvenience that this regression may cause.


Cheers, Stuart

Lionel

unread,
Aug 20, 2010, 4:00:36 AM8/20/10
to asciidoc


On 17 août, 23:05, Stuart Rackham <srack...@gmail.com> wrote:
> This rather long post details a BREAKING CHANGE.
>
> Currently quoted elements can be preceded by an attributes list which can
> include up to three positional attributes (color, background color and
> size) and a 'role' named attribute. Examples:
>
>    [green,#b0e0e6,2]##fun with text##.
>    [role="input"]*x = 25*
>
> The positional attributes are only applicable to HTML backends and
> they emit hard-coded CSS styles; the 'role' attribute emits DocBook
> 'role' attributes and HTML 'class' attributes. The number and mixed
> applicability of these style related attributes is messy and difficult
> to remember.
>
> The whole thing can be replaced by a single positional attribute which
> translates to HTML 'class' attributes:
>
> - Directly using the AsciiDoc HTML backends.
> - Indirectly using the 'docbook' backend (DocBook XSL Stylesheets
>    translate DocBook 'phrase' elements with 'role' attributes to HTML
>    'span' elements with the same 'class' attributes; CSS is then used
>    http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
>    generated HTML]).

mmmh... What about other outputs from DocBook? I am pretty sure lots
of people use the 'role' attribute through FOP or dblatex. What
happens in such cases?

>
> Examples:
>
>    [red]#obvious#
>    [big red yellowback]*very obvious*
>
> The following CSS rules for 'big', 'red' and 'yellowback' class names could
> be used to style outputs generated by the previous examples:
>
>    span.big { font-size: 2em; }
>    span.red { color: #e3372e; }
>    span.yellowback { background: #faf519; }
>
> .Pros
> - Allows CSS styling to be applied to both DocBook and HTML outputs
>    from the same AsciiDoc source.
> - Role names are more obvious and easier to remember than the
>    color and size positional arguments.
> - CSS affords arbitrary styling.
> - The new attribute can specify multiple class names.
>
> .Cons
> - Breaks existing quote attribute behavior.
> - You need to create CSS rules.
>
> I've committed a changeset that implements this enhancement:http://code.google.com/p/asciidoc/source/detail?r=99df82275a29bec4f73...

Stuart Rackham

unread,
Aug 20, 2010, 5:39:26 AM8/20/10
to asci...@googlegroups.com

On 20/08/10 20:00, Lionel wrote:


>
>
> On 17 ao�t, 23:05, Stuart Rackham<srack...@gmail.com> wrote:
>> This rather long post details a BREAKING CHANGE.
>>
>> Currently quoted elements can be preceded by an attributes list which can
>> include up to three positional attributes (color, background color and
>> size) and a 'role' named attribute. Examples:
>>
>> [green,#b0e0e6,2]##fun with text##.
>> [role="input"]*x = 25*
>>
>> The positional attributes are only applicable to HTML backends and
>> they emit hard-coded CSS styles; the 'role' attribute emits DocBook
>> 'role' attributes and HTML 'class' attributes. The number and mixed
>> applicability of these style related attributes is messy and difficult
>> to remember.
>>
>> The whole thing can be replaced by a single positional attribute which
>> translates to HTML 'class' attributes:
>>
>> - Directly using the AsciiDoc HTML backends.
>> - Indirectly using the 'docbook' backend (DocBook XSL Stylesheets
>> translate DocBook 'phrase' elements with 'role' attributes to HTML
>> 'span' elements with the same 'class' attributes; CSS is then used
>> http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
>> generated HTML]).
>
> mmmh... What about other outputs from DocBook? I am pretty sure lots
> of people use the 'role' attribute through FOP or dblatex. What
> happens in such cases?

The role attribute appears in most DocBook elements and is used to "subclass" an
element -- in the AsciiDoc quote context it subclasses the phrase element (the
generic text element). You don't have to use it but it's a very handy way to
pass CSS styles through to HTML ouputs (this is what DocBook XSL Stylesheets
does with the role attribute). There may well be role usage collision across the
various DocBook processors, but that's between them and doesn't really have
anything to do with AsciiDoc.

Cheers, Stuart

Reply all
Reply to author
Forward
0 new messages