the callout-list css alignment is wrong when using docbook

43 views
Skip to first unread message

Lionel

unread,
Feb 14, 2010, 11:11:20 AM2/14/10
to asciidoc
Hi,

I am in the process of translating a currently existing documentation
from docbook to asciidoc, and I render the output in both chunked and
single html output from docbook.

I noticed that the alignment for my calloutlist (when using callouts
icons) is quite wrong. I had a look under Firebug but I'm not a CSS
master and I don't see where it comes from (maybe the fact that the
text is top-aligned and that the line-height may be too big).

The problem is visible as well on the asciidoc user guide rendered
from docbook, see here : http://www.methods.co.nz/asciidoc/asciidoc.html#_callouts

I hope there's an easy solution (I suppose there is, CSS is flexible
enough) because the original documentation makes an extensive use of
callouts. Any ideas ?

Thanks a lot,
Lionel

Stuart Rackham

unread,
Feb 14, 2010, 2:30:42 PM2/14/10
to asci...@googlegroups.com
Lionel wrote:
> Hi,
>
> I am in the process of translating a currently existing documentation
> from docbook to asciidoc, and I render the output in both chunked and
> single html output from docbook.
>
> I noticed that the alignment for my calloutlist (when using callouts
> icons) is quite wrong.

I'm guessing that you mean the vertical alignment of the callout icons in the
callout list. This is the default styling of the DocBook XSL output, it hasn't
been altered by the AsciiDoc docbook-xsl.css tweaks. Did your previous DocBook
source to HTML translation fix it? If yes then it most probably introduced some
customization. What version of AsciiDoc are you using? What version of DocBook
XSL are you using?

Cheers, Stuart

Lionel

unread,
Feb 15, 2010, 3:42:33 AM2/15/10
to asciidoc
Hi Stuart,

To answer your questions first: the orginal docbook does not show this
alignment problem. It uses docbook-xsl-stylesheets v1.74.0. For
asciidoc, I use a2x and the latest mercurial tip, so the stylesheets
associated with this version.

I could eventually see the difference.

In the original docbook, the text in each callout-list item is
enclosed in a <para/> element, i.e. we have <td><p>item description</
p></td> instead of <td>item description</td>.

in docbook.conf, section [listtags-callout], I replaced

text=<simpara>|</simpara>

by

text=<para>|</para>

and the result seems correctly aligned. I don't know what docbook
expects best here. para or simpara ?

Anyway, the default asciidoc stylesheet makes the line height very
high, and I'd like the callout list to be more compact. Here is the
addition I made to docbook-xsl.css:

div.calloutlist p {
margin: 0;
}

There is not "customization" done by the original docbook css, but
there is no margin added to standard elements, which is reflected in
those elements eventually in asciidoc and makes the alignmen problem
well visible.

Am I going in the right direction ?

Thanks for your hints,
Lionel

Stuart Rackham

unread,
Feb 17, 2010, 12:24:54 AM2/17/10
to asci...@googlegroups.com
Lionel wrote:
> Hi Stuart,
>
> To answer your questions first: the orginal docbook does not show this
> alignment problem. It uses docbook-xsl-stylesheets v1.74.0. For
> asciidoc, I use a2x and the latest mercurial tip, so the stylesheets
> associated with this version.
>
> I could eventually see the difference.
>
> In the original docbook, the text in each callout-list item is
> enclosed in a <para/> element, i.e. we have <td><p>item description</
> p></td> instead of <td>item description</td>.
>
> in docbook.conf, section [listtags-callout], I replaced
>
> text=<simpara>|</simpara>
>
> by
>
> text=<para>|</para>
>
> and the result seems correctly aligned. I don't know what docbook
> expects best here. para or simpara ?

The stylesheets are treating translating simpara and para in the differently:
when simpara encloses the item text no HTML tags are emitted, when para encloses
the item text it is enclosed in the HTML p tag. I've no idea why, probably no
reason. The result being that as it was the callout icons get enclosed by p tags
but the item text was not, hence the vertical misalignment.

Thanks for spotting that, I didn't think simpara and para would be treated
differently.


>
> Anyway, the default asciidoc stylesheet makes the line height very
> high, and I'd like the callout list to be more compact. Here is the
> addition I made to docbook-xsl.css:
>
> div.calloutlist p {
> margin: 0;
> }
>
> There is not "customization" done by the original docbook css, but
> there is no margin added to standard elements, which is reflected in
> those elements eventually in asciidoc and makes the alignmen problem
> well visible.
>
> Am I going in the right direction ?

Yes, I've committed you changes to the trunk (added a 0.4em item spacing).

http://code.google.com/p/asciidoc/source/detail?r=918c378a378260dfd46633530b6c15a169812d23

If you wondering about the Google Code URL, I'm in the process of moving the
asciidoc repo to Google Code.

Cheers, Stuart


>
> Thanks for your hints,
> Lionel
>

Lionel

unread,
Feb 17, 2010, 3:00:48 AM2/17/10
to asciidoc

On 17 fév, 06:24, Stuart Rackham <srack...@gmail.com> wrote:

> The stylesheets are treating translating simpara and para in the differently:
> when simpara encloses the item text no HTML tags are emitted, when para encloses
> the item text it is enclosed in the HTML p tag. I've no idea why, probably no
> reason. The result being that as it was the callout icons get enclosed by p tags
> but the item text was not, hence the vertical misalignment.
>
> Thanks for spotting that, I didn't think simpara and para would be treated
> differently.
>

Yes indeed I noticed the presence/absence of <p/> tag but was unsure
about the consequences. It's clearer now.


> > Am I going in the right direction ?
>
> Yes, I've committed you changes to the trunk (added a 0.4em item spacing).
>

> http://code.google.com/p/asciidoc/source/detail?r=918c378a378260dfd46...


>
> If you wondering about the Google Code URL, I'm in the process of moving the
> asciidoc repo to Google Code.
>
> Cheers, Stuart
>

Thank a lot for committing these! It helps a lot.

For information, the project that currently moves its documentation
from docbook to asciidoc is the Waf build system, another good piece
of code in python: http://waf.googlecode.com

Regards,
Lionel

Reply all
Reply to author
Forward
0 new messages