[kde-doc-english] checkXML vs meinproc4

[Jack]

On 2014.09.06 18:16, Jack wrote:
> 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.

I finally took a more careful look at the definition of  
<inlinemediaobject> and noticed it could be directly in <para>.  This  
means I can change

<para> text </para>
   <screenshot>
   <mediaobject>
   <imageobject>
   <imagedata fileref="csvImporter_1.png" format="PNG" />
   </imageobject>
   </mediaobject>
   </screenshot>

to

<para> text
   <inlinemediaobject>
   <imageobject>
   <imagedata fileref="csvImporter_1.png" format="PNG" />
   </imageobject>
   </inlinemediaobject>
</para>

and get the result I want.  Is there any reason not to make this change?

Jack