Listing with source code blocks not being treated as "examples"?

75 views
Skip to first unread message

Yves-Alexis Perez

unread,
Sep 17, 2009, 1:36:07 PM9/17/09
to asci...@googlegroups.com
Ok, yet another problem.

i'm using some listing blocks.

First one like:

.Title1
[source,sh]
----
FOO=BAR
ls /foo
----

.Title2
----
foo
bar
----

The first one is rendered (using docbook+dblatex) as an highlighted
source block, the second is not highlighted: normal.
Both are using monospace font: normal

But the second one is seen as an Example (numeroted and inserted in the
table of examples in frontmatter) while the first isn't. Why adding
source style is changing that, and how can I get a consistent behavior
(preferably the one with both source highlighting and example table).

Thanks,
--
Yves-Alexis

Stuart Rackham

unread,
Sep 20, 2009, 1:03:01 AM9/20/09
to asci...@googlegroups.com

The source filter generates a DocBook programlisting element, to have it appear
as an example it would have to be enveloped by an example element. It makes
sense that if should behave like the normal listing block -- I've added a change
to the trunk which renders titled source listings as examples:

http://hg.sharesource.org/asciidoc/rev/502da3a81812


Cheers, Stuart


>
> Thanks,

Lex Trotman

unread,
Sep 20, 2009, 1:25:49 AM9/20/09
to asci...@googlegroups.com
2009/9/20 Stuart Rackham <srac...@gmail.com>:
How do I turn this off for a particular document?

I have source fragments that represent the interface to items and have
.Interface as the title. They should not be examples.

Cheers
Lex

>
> Cheers, Stuart
>
>
>>
>> Thanks,
>
>
> >
>

Stuart Rackham

unread,
Sep 20, 2009, 2:26:01 AM9/20/09
to asci...@googlegroups.com
The change only affects DocBook outputs. Prior to the patch source listing
titles were ignored in DocBook outputs (but not HTML outputs).

Am I missing something here?


Cheers, Stuart

Lex Trotman

unread,
Sep 20, 2009, 3:58:36 AM9/20/09
to asci...@googlegroups.com
Hi Stuart,

Apologies for the previous rushed & unclear question.

The question is a general one on how to stop listings with titles
being treated as examples. This happens in docbook/PDF with 8.4.5, it
wasn't actually relating to the patch, just that the post about the
patch triggered my dodgy memory to ask the question :-)

.Interface
-------------------------------
listing
------------------------------

renders "correctly" in html as a highlighted listing block titled
"Interface", but renders as "Example 2.1 Interface" in docbook/PDF.

I would not have expected that a titled listing had to be an example,
and in fact in my use case semantically it is not.

Is there a way to change the behaviour by default or per document?

Cheers
Lex

2009/9/20 Stuart Rackham <srac...@gmail.com>:

Stuart Rackham

unread,
Sep 20, 2009, 5:20:17 AM9/20/09
to asci...@googlegroups.com
Hi Lex

Lex Trotman wrote:
> Hi Stuart,
>
> Apologies for the previous rushed & unclear question.
>
> The question is a general one on how to stop listings with titles
> being treated as examples. This happens in docbook/PDF with 8.4.5, it
> wasn't actually relating to the patch, just that the post about the
> patch triggered my dodgy memory to ask the question :-)
>
> .Interface
> -------------------------------
> listing
> ------------------------------
>
> renders "correctly" in html as a highlighted listing block titled
> "Interface", but renders as "Example 2.1 Interface" in docbook/PDF.
>
> I would not have expected that a titled listing had to be an example,
> and in fact in my use case semantically it is not.
>
> Is there a way to change the behaviour by default or per document?

I don't know of any way of associating a title with a DocBook screen or
programlisting element other than wrapping it in an example element.

You could precede the listing with a floating title e.g.

[float]
===== Example source listing

---------------------------
Listing
---------------------------

This works but it's not very satisfying (the title is spaced to far from the
listing (dblatex and FOP)).


Cheers, Stuart

Lex Trotman

unread,
Sep 20, 2009, 6:33:16 AM9/20/09
to asci...@googlegroups.com
Hi Stuart,

Ok, I see where you are coming from.

Where the docbook.xml had:
<example><title>interface</title>
<screen> the listing </screen>
</example>

After some head scratching with docbook documentation (my first look
at it, I had, to date, used asciidoc to avoid it) I hand edited the
above xml (well one instance of it) to:

<formalpara><title>Interface</title>
<para><screen> the listing </screen></para>
</formalpara>

and ran it through a2x -s

This produced a titled highlighted listing block in the way I would
have expected. Can that be the titled listing encoding and an example
be ... well... an example :-)

Stuart Rackham

unread,
Sep 20, 2009, 11:18:39 PM9/20/09
to asci...@googlegroups.com
Lex Trotman wrote:
> Hi Stuart,
>
> Ok, I see where you are coming from.
>
> Where the docbook.xml had:
> <example><title>interface</title>
> <screen> the listing </screen>
> </example>
>
> After some head scratching with docbook documentation (my first look
> at it, I had, to date, used asciidoc to avoid it) I hand edited the
> above xml (well one instance of it) to:
>
> <formalpara><title>Interface</title>
> <para><screen> the listing </screen></para>
> </formalpara>
>
> and ran it through a2x -s
>
> This produced a titled highlighted listing block in the way I would
> have expected. Can that be the titled listing encoding and an example
> be ... well... an example :-)

I didn't think of using a nested para to get screen inside a formalpara, it
works, and I agree that silently promoting titled listings to examples is not
what you would expect. If you want a listing to be an example put it inside an
example block e.g.

.Example source listing
===========================
---------------------------
Listing
---------------------------
===========================

I've added this to the trunk so that titled list and literal blocks are not
examples, nor are titled source highlight list blocks:

http://hg.sharesource.org/asciidoc/rev/f73a86b5e213

Lex Trotman

unread,
Sep 21, 2009, 3:50:07 AM9/21/09
to asci...@googlegroups.com
Thank You
Cheers
Lex

2009/9/21 Stuart Rackham <srac...@gmail.com>:
Reply all
Reply to author
Forward
0 new messages