On 26/11/2009 16:58, Ariel Constenla-Haile wrote: > Hello Jürgen, * > > On Thursday 26 November 2009, 12:36, Juergen Schmidt wrote: >> mmh, it seems that we have a classical problem where you have >> implemented a macro based on a not documented implementation detail. But >> the implementation gets cleaned up for 3.2.
yes, i removed the XTextField interface at the writer's SwXTextPortion implementation because: - it is documented nowhere - it is only implemented in writer, not in svx/editengine - there is the "TextField" property which gives access to the field of the portion - the SwXTextPortion does not implement any interface of any other portion type (XFootnote...) except this XTextField - the original implementer of SwXTextPortion claimed that this interface was probably included in error - none of our regression tests broke >> The problem is that the correct way is also not well documented :-( indeed; i have just looked at the relevant parts of the dev. guide, and it is not documented how to access the field of a TextPortion of type "TextField". >> In this case it would be correct to check the TextPortionType and in >> case of a text field ask for the property "TextField". It should be >> possible to ask for the property always and do the necessary checks... yes, this is the proper way, and should work on all OOo versions. >> I am not sure if we can or should mark this as a show stopper because it >> was an implementation detail. And the clean up of the code makes sense >> and we don't really want to change it back. considering the lack of documentation, now i actually believe that this is indeed an issue that should be fixed: if the proper way of doing something is not documented, we cannot really complain that someone found a non-proper way that happens to work. (which is why i'm not replying here with an RTFM rant like i originally intended :) ) but in any case, undoing this change would only be temporary: in the next major OOo release (4.0), this interface will definitely not be supported. that should give people plenty of time to adapt their macros and stuff. >> Maybe the responsible developer can shed some light on this and give us >> some more reasons for the change. >> >> We have definitely to fix the documentation to reflect the correct way. indeed. i can update the dev guide: http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Text/Iterating_over_Text btw, is it possible to automatically generate lists of properties in the dev guide from the IDL file? >> To avoid such problems in the future it is probably a good idea to ask >> here on this list first before you use an API that is not documented. >> Often enough the documentation is simply missing or incomplete. >> >> We should be careful with the available introspection tools. They >> provide great help and are necessary but the user of these tools should >> at least check the documentation too. This way we can improve the >> documentation as well. > > this issue has the same "background" as the one with the TextCursor > properties > http://www.openoffice.org/issues/show_bug.cgi?id=100798 > > For the TextPortion issue, on a DEV300_m65 the documentation seems corrected > (though I didn't check every property) > http://svn.services.openoffice.org/opengrok/xref/DEV300_m65/offapi/com/sun/star/text/TextPortion.idl#130 yes, i did that. (but unfortunately not at the same time as the XTextField removal...) > IMHO common properties should be moved to the TextRange service (both a > TextCursor and a TextPortion are TextRanges). not necessarily: i think there are TextRanges which are neither TextPortion nor TextCursor. regards, michael -- Which is worse: Ignorance or Apathy? Who knows? Who cares? --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
