Bug 579069

Created attachment 404180 [details]
Screenshot of the weird rendering

It might be related to the same problem, but I get a weird rendering of the callout in HTML (see attached picture): the reference callout image in the program listing is way bigger than the same image in the calloutlist afterwards (but the latter is inside a link while the former is not). It's also on a line of its own instead of being at the end of the line where it was in the source.

BTW, I'm using docbook-xsl 1.75.2 (latest version from Debian Unstable).

Created attachment 404203 [details]
Possible patch

The "anchor" template is not always called from the start of a new tag in the generic docbook XSL stylesheets (I gave an example where this legitimately happened). Thus it should output a tag on its own and not expect to be able to add an attribute to its parent tag.

I'm not sure why it was overridden from the default docbook-xsl stylesheet but in any case the override is not correct.

(In reply to comment #2)
> Created an attachment (id=404203) [details]
> Possible patch
> 
> The "anchor" template is not always called from the start of a new tag in the
> generic docbook XSL stylesheets (I gave an example where this legitimately
> happened). Thus it should output a tag on its own and not expect to be able to
> add an attribute to its parent tag.
> 
> I'm not sure why it was overridden from the default docbook-xsl stylesheet but
> in any case the override is not correct.    

The generic XSL outputs invalid XHTML. It is never valid to have an anchor tag with no content in XHTML, so we don't do that.

I'll look in to where this tag is being called from and see if I can get it to generate valid XHTML.

FWIW http://www.docbook.org/tdg/en/html/programlistingco.html has been tested and works, and since this is what you seem to be trying to achieve you could try that out until I can get to this.

Cheers, Jeff.

You might want to report that the docbook-xsl folks then I guess instead of fixing it only for publican.

I sent a mail upstream without checking your assertion that <a/> is invalid in XHTML and upstream says that the DTD allows <a> to be an empty tag: http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg14001.html

So what was the concrete problem that you tried to avoid?

(In reply to comment #5)
> I sent a mail upstream without checking your assertion that <a/> is invalid in
> XHTML and upstream says that the DTD allows <a> to be an empty tag:
> http://www.mail-archive.com/docbook-apps@lists.oasis-open.org/msg14001.html
> 
> So what was the concrete problem that you tried to avoid?    

hmm this change was made several years ago, probably 3 or 4 years ago, way before we made publican open source, so it's a bit dim in my memory. On further thinking I believe my original response is incorrect.

If I recall correctly, and this was a long time ago, it was actually because the anchors are emitted in places where they are invalid. Anchors only have 8 or so valid parents in XHTML 1.0 Strict mode, assuming you categorize the various H tags as counting as one, and the anchors are emitted all over the place.

I think I looked in to everywhere it was called, and it was a big job to change the incorrect ones. Since it's never used anywhere there isn't another tag to link to, it was just easier to put the ID in the real tag instead of injecting a tag just to put an ID in.

The way we tested this was to build the Deployment Guide in html-single then run that through http://validator.w3.org, it generated massive numbers of errors in XHTML 1.0 Strict mode and we went about tidying them up.

I might actually give this another go since it's been a while since we've done that and invalid markup may have crept in.

FYI I've checked a fix for this in to the 1.6 branch and it will be available in 1.6.3 which will probably come out in the next week or so.

Thanks, I informed the docbook-xsl authors and gave them the URL of the deployment guide so that they can try to reproduce the original problem.

Thanks for the fix too, but it's only a partial fix for me. I have other cases where the anchor template is called without being at the start of a new tag, for example when processing the following docbook:

<sect1>
 <title>Some title</title>
 <para>Some text</para>
 <screen id="sample">
 </screen>
</sect1>

The problem comes when converting <screen>, it has an id tag to be able to refer to it and the docbook-xsl does:
<xsl:template match="programlisting|screen|synopsis">
  <xsl:param name="suppress-numbers" select="'0'"/>
  <xsl:variable name="id">
    <xsl:call-template name="object.id"/>
  </xsl:variable>

  <xsl:call-template name="anchor"/>
[...]

There's no new parent tag yet at that point.

(In reply to comment #7)
> Thanks, I informed the docbook-xsl authors and gave them the URL of the
> deployment guide so that they can try to reproduce the original problem.
> 
> Thanks for the fix too, but it's only a partial fix for me. I have other cases
> where the anchor template is called without being at the start of a new tag,
> for example when processing the following docbook:
> 
> <sect1>
>  <title>Some title</title>
>  <para>Some text</para>
>  <screen id="sample">
>  </screen>
> </sect1>
> 
> The problem comes when converting <screen>, it has an id tag to be able to
> refer to it and the docbook-xsl does:
> <xsl:template match="programlisting|screen|synopsis">
>   <xsl:param name="suppress-numbers" select="'0'"/>
>   <xsl:variable name="id">
>     <xsl:call-template name="object.id"/>
>   </xsl:variable>
> 
>   <xsl:call-template name="anchor"/>
> [...]
> 
> There's no new parent tag yet at that point.    

Hi Raphaël, we discourage linking to objects that don't have titles, because it is makes translation difficult. I'll sit down with Rudi and Manuel and add some text to the Users Guide on linking to informal objects and how that impacts translation.

It's very similar to the discussions in file:///usr/share/doc/publican-doc-1.6.2/en-US/index.html#appe-Users_Guide-Disallowed_elements_and_attributes

If you want to link to something you should be using a formal object, like an example, since this fits in to translation work flow.

I will look in to fixing this issue for any tags you bring to my attention though.

Right, in my case the references pointing to the object were <xref ... xrefstyle="page"> so it only had to contain a page number and no translatable material. Obviously this only works with the PDF output (my content comes from a published/printed book so it was ok in that context).

Hi, I took a different approach. First I emptied out the anchor  template so it does nothing. Then I overrode common.html.attributes to set the ID if it's present.

Need to QA the output, but it seems like an overall better approach as it shouldn't require overriding a bunch of templates.

Confirmed working in 1.6.3.t150 -- callout numbers appear suitably small and located beside the actual line of code to which they apply.

publican-1.6.3-0.fc13 has been submitted as an update for Fedora 13.
http://admin.fedoraproject.org/updates/publican-1.6.3-0.fc13

publican-1.6.3-0.fc12 has been submitted as an update for Fedora 12.
http://admin.fedoraproject.org/updates/publican-1.6.3-0.fc12

publican-1.6.3-0.fc12 has been pushed to the Fedora 12 testing repository.  If problems still persist, please make note of it in this bug report.
 If you want to test the update, you can install it with 
 su -c 'yum --enablerepo=updates-testing update publican'.  You can provide feedback for this update here: http://admin.fedoraproject.org/updates/publican-1.6.3-0.fc12

publican-1.6.3-0.fc13 has been pushed to the Fedora 13 testing repository.  If problems still persist, please make note of it in this bug report.
 If you want to test the update, you can install it with 
 su -c 'yum --enablerepo=updates-testing update publican'.  You can provide feedback for this update here: http://admin.fedoraproject.org/updates/publican-1.6.3-0.fc13

publican-1.6.3-0.fc13 has been pushed to the Fedora 13 stable repository.  If problems still persist, please make note of it in this bug report.

publican-1.6.3-0.fc12 has been pushed to the Fedora 12 stable repository.  If problems still persist, please make note of it in this bug report.