[publican-list] [Bug 604255] Problem with callouts

[bugzilla at redhat.com]

Please do not reply directly to this email. All additional
comments should be made in the comments box of this bug.


https://bugzilla.redhat.com/show_bug.cgi?id=604255

--- Comment #4 from Jeff Fearn <jfearn at redhat.com> 2010-06-16 19:40:46 EDT ---
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!

-- 
Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.