Bug 604255

Using current 1.6.x branch (which has fixes to callouts not in 1.6.3):

-   <programlisting lang="c++"><![CDATA[
+   <programlisting language="C++"><![CDATA[

No callout numbers in the program listing.

-   <programlisting language="C++"><![CDATA[
+   <programlisting"><![CDATA[

Callout numbers appear, but no highlighting.

Looks like the highlighting module is eating the COs :(

Workarounds:

1: do not set language, avoids highlighting code
2: use an areaset, avoids inline COs

I'll see if I can beat the highlighting code in to submission.

Due to the way the XSL gets processed the tags inside the program listing are processed before the highlighting callback gets called; the COs have already been converted to the output format, be it HTML or XML:FO.

This means we'd have to try and exclude some part of the input being from highlighted, and the mask of that content would change based on what the output format is. Of course if you were trying to highlight HTML or XML source then there probably isn't a reliable way to differentiate call-out markup Vs any other markup.

If it's possible, it's definitely going to take some time to be able to support the combination of highlighting and inline COs.

I don't know exactly how syntax highlighting is implemented. 

Does syntax highlighting ignore characters like these?

DINGBAT NEGATIVE CIRCLED DIGIT ONE
U+2776, character ❶, decimal 10102, hex 0x2776

DINGBAT NEGATIVE CIRCLED DIGIT TWO
U+2777, character ❷, decimal 10103, hex 0x2777

DINGBAT NEGATIVE CIRCLED DIGIT THREE
U+2778, character ❸, decimal 10104, hex 0x2778

Downside: there are only ten of them.
Upside: they might pass through.

We use a CPAN module for the highlighting, I don't think it ignores anything, I haven't found anything to allow specifying things to ignore, so it probably comes down to how the particular language is being parsed.

I think it's safer ATM to say "If you want call-outs and code highlighting, then you have to use an areaspec".

Here is an example of how I'd structure this.

First, I'd move the code out of the XML, having all that XML related stuff buried in your code increases the opportunity of adding typos. It's also annoying to have to take chunks of code and XMLify them.

e.g.

mkdir en-US/extras
gvim en-US/extras/hello.cpp
-- make hello.cpp pure C++ --

Then I'd use an areaspec and xi:include the new cpp file, leaving you with:

<example>
  <title>"Hello world!" in C++</title>
  <programlistingco>
    <areaspec>
      <area id="hello-cpp-open" coords='16'/>
      <area id="hello-cpp-session" coords='17'/>
      <area id="hello-cpp-receiver" coords='19'/>
      <area id="hello-cpp-sender" coords='20'/>
      <area id="hello-cpp-fetch" coords='24'/>
      <area id="hello-cpp-acknowledge" coords='26'/>
      <area id="hello-cpp-close" coords='28'/>
    </areaspec>
<programlisting language="C++"><xi:include parse="text" href="extras/hello.cpp" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
    <calloutlist>
** SNIP There are no changes to the callout list **
    </calloutlist>
  </programlistingco>
</example>

I've gone for the simple coords usage here, just specifying the line number, the callout code will default to lining all the numbers up. You can uses coords='16 34' if you want to override this behavior and specify the line and the column.

Note how programlisting and the xi:include are on the same line, this means the line numbers you use in coords start from line zero. If you had a newline between them, then you'd have to start the line number count from 1.

YMMV, I find keeping the code in a file and only ever treating it as code greatly simplifies the process and allows me to validate the code as code ... not that I make manly typos!

Created attachment 424618 [details]
Example of HTML layout

Hi, I just thought I'd provide a screen shot of the default output as per my example, built from the latest 1.6 branch.

Nice! 

That satisfies my needs. The main disadvantage is that if you add a blank line or something, the callouts can be in the wrong place, but this is plenty good enough for my needs.

(In reply to comment #6)

> That satisfies my needs. The main disadvantage is that if you add a blank line
> or something, the callouts can be in the wrong place, but this is plenty good
> enough for my needs.    

Glad to hear that helps; I'll note the limitation in the User Guide. --Rudi

Expanded the previous FAQ entry on adding code samples into a new section: "3.3. Adding code samples" and discussed recommended callout usage per comment #4.