[kde-doc-english] checkXML vs meinproc4

[Luigi Toscano]

Jack ha scritto:
> On 2014.09.04 14:27, Luigi Toscano wrote:
>> Jack ha scritto:
> [snip]
>>> Up until now, all screenshots in the manual have been wrapped in
>>> <screenshot>, <mediaobject>, <imageobject>, and <imagedata> tags.  For a
>>> new chapter, I was trying to avoid the lines above and below the image, so
>>> I used inlinemediaobject instead of mediaobject.  Meinproc4 accepted this,
>>> and the output was just what I wanted: apparently identical to using
>>> mediaobject but without the lines.  checkXML complains this is not valid. 
>>> How much should I be concerned about this?  Is there another way to
>>> eliminate the lines?
>>
>> inlinemediaobject is used even in the example template in the
>> kdelibs/kdoctools sources (I assume it's kdelibs4, otherwise look into
>> frameworks/kdoctools); could you please paste the relevant docbook section
>> (including the tags which encloses the inlinemediaobject) and the exact error?
> 
> Given this code
> 
>   <screenshot>
>   <inlinemediaobject>
>   <imageobject>
>   <imagedata fileref="csvImporter_1.png" format="PNG" />
>   </imageobject>
>   </inlinemediaobject>
>   </screenshot>
> 
> checkXML says
> 
> details-impexp-csv.docbook:101: element screenshot: validity error : Element
> screenshot content does not follow the DTD, expecting (screeninfo? , (graphic
> | graphicco | mediaobject | mediaobjectco)), got (inlinemediaobject )
>   </screenshot>
>                ^
> 
> Given the definition of screenshot, this does make sense, but using
> mediaobject instead of inlinemediaobject produces a line above and below the
> image, which I don't want.  Meinproc4 actually does what I want, but as part
> of a full make on the application, it is apparently called with --check, as it
> generates the error.  I find the lines distracting, and think they imply a
> break that isn't there.  Is there any way to suppress them?

So, few points:
- the definition of the DocBook DTD does not allow inlinemediaobject inside
screenshot tag. meinproc4 --check is not wrong and it's not going to be
changed: the document is not valid as it is. It's like a compiler error.

- at my level of docbook knowledge, I'm not sure it's a problem of the
specification or of the rendering, but I bet the rendering. And I'm not sure
what is the best way to achieve the effect you want.
Do you mean that the additional lines are added on docs.kde.org, or On the
rendered documentation in khelpcenter? Is the reason for removing them an
rendering one (i.e. it looks "better")?

Ciao
-- 
Luigi