[kde-doc-english] checkXML vs meinproc4

[Jack]

On 2014.09.06 17:32, Luigi Toscano wrote:
> 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.
I understand and agree with this.

> - 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")?
I agree it is a rendering issue.  I see the lines both on docs.kde.org  
and in khelpcenter.  As an example, look at  
http://docs.kde.org/stable/en/extragear-office/kmymoney/firsttime.3.html.   
There is a line above and below every screenshot.  In some cases, I  
don't think it makes any difference, but in many cases, I feel it  
creates an unnecessary and undesired discontinuity in reading.  Yes,  
it's a personal opinion.  In many cases, I would probably leave them,  
but there are some cases where I find them very distracting.  I don't  
necessarily need a way to remove them from the rendering of  
<mediaobject>  I want to find a way to get the same rendering without  
the lines.  I don't care if I must use some attribute for some tag, or  
even if I must use a different set of tags.

Jack