[kde-doc-english] checkXML vs meinproc4

[Yuri Chornoivan]

написане Sun, 07 Sep 2014 18:06:44 +0300, Jack <ostroffjh at sbcglobal.net>:

> 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

Hi,

Such syntax creates HUGE translation messages which are not easy to handle  
and maintain.

Example (from line 141):

http://websvn.kde.org/trunk/l10n-kde4/templates/docmessages/extragear-office/kmymoney_details-impexp-csv.pot?revision=1399090&view=markup

Best regards,
Yuri