2018-05-20

4: Deciphering the Official Documents of LibreOffice or OpenOffice

<The previous article in this series | The table of contents of this series | The next article in this series>
We may and should admit that they are not well-written. A culprit is the lax terminology used there, which will be disentangled here.

Topics


About: UNO (Universal Network Objects)
About: LibreOffice
About: Apache OpenOffice

The table of contents of this article

Starting Context

Target Context

Orientation


This series is based on a terminology made more reasonable.

Main Body

Stage Direction
Here are Special-Student-7, Morris (a C++ programmer), and Abby (a C# programmer) in front of a computer.

0: It Is Not Your Fault That You Have Much Difficulty in Understanding the Official Document


Special-Student-7
 Not all the documents in the world are well-written.

A trap for a humble reader is to presume that the document that he or she is reading should have been well-written: he or she thinks "I must be the one to be blamed for not understanding this!".

In fact, the document has been just ill-written.

It is imperative to admit that the document has been ill-written, or he or she will waste his or her precious time.

Humbleness is a virtue; permissiveness is a virtue; but permitting bad documents to prey on humbleness is a sin.

In fact, the most typical cause of ill-written-ness is bad terminology, which is unfortunately the case for the official documents for LibreOffice or Apache OpenOffice.

Stage Direction
Morris raises an eyebrow as he is shocked by Special-Student-7's ignorance.

Morris
 There is no such thing as a "bad terminology". Don't you know that any terminology is arbitrary?

Special-Student-7
 Sir, I claim that it should not.

Stage Direction
Morris moves his head from side to side as he has gave up reasoning such an ignorant fool.

Special-Student-7
 A typical problem is that a term is used to represent multiple different concepts.

You know, if a term is used to represent multiple concepts, the reader usually cannot understand what each appearance of the term means.

Abby
 But the context clarifies the meaning, right?

Special-Student-7
 That is prevalently an unfulfilled promise.

You know, the context does not automatically clarify the meaning; the author has to meticulously make the context clarify the meaning.

But I have to say, most documents are not written with such meticulousness, and the official documents for LibreOffice or Apache OpenOffice is unfortunately not an exception.

Having multi-meanings terms and clarifying each meaning by the context is really a hard juggling act, which any conscientious author should know. In general, it is very unlikely that multi-meanings terms are clarified by meticulous handling, because if the author was really so meticulous, he or she would have chosen terms more meticulously.

1: What Are "Services" in the Official Documents?


Special-Student-7
 A problematic term used in the official reference document and the UNOIDL API document (here for LibreOffice and here for Apache OpenOffice) of LibreOffice or Apache OpenOffice is "service". It is problematic because it is used to represent multiple intrinsically-different concepts.

1st, "service" is used to represent a UNO service.

Morris
 An item in a UNO objects factory, in short.

Special-Student-7
 Yes.

2nd, "service" is used to represent a 'compound of some UNO interfaces and some UNO object property definitions'.

Abby
 . . . Well, isn't that just a kind of interface?

Special-Student-7
 Madam, actually, it is. There seems to be some historical circumstance in which "service" in the 2nd meaning was conceived, but I do not see why UNO interface should not cover "service" in the 2nd meaning.

Abby
 Do you mean that it doesn't need to exist?

Special-Student-7
 Yes, I do so.

Morris
 But it exists, so, I need to use it.

Special-Student-7
 Well, you do not need to programmatically use it except in a case, as far as I know.

Morris
 What do you mean by "programmatically"?

Special-Student-7
 It may be somehow useful documentationally.

I mean, "service" in the UNOIDL API document is basically in the 2nd meaning, but it is possible (although not guaranteed) that there is the UNO service of the same name. So, if you find a "service" in the UNOIDL API document, you may be able to instantiate a UNO component that has implemented the UNO interfaces listed in the document.

Morris
 Why don't I need to use it programmatically?

Special-Student-7
 What matter when you use a UNO object are the UNO interfaces implemented by the UNO object; it does not matter via what "service" in the 2nd meaning a UNO interface is there.

Morris
 Ah, certainly, it doesn't matter.

Abby
 But what happen to those "UNO object property definitions"?

Special-Student-7
 Any UNO object property is really a matter of the implementation of the '::com::sun::star::beans::XPropertySet' UNO interface by the UNO component.

Abby
 So?

Special-Student-7
 Even if the UNO component does not implement any "service" in the 2nd meaning, if the UNO component supports a property name in the implementation of the '::com::sun::star::beans::XPropertySet' UNO interface, the property is there.

Abby
 So, any "service" in the 2nd meaning is not necessary in order for the UNO component to implement the properties?

Special-Student-7
 It is not necessary, and when you handle any UNO object property, you can do so via the '::com::sun::star::beans::XPropertySet' UNO interface, without any use of any "service" in the 2nd meaning.

Abby
 Then, what are those definitions for?

Special-Student-7
 They have only documentational meanings: the properties are documented in the UNOIDL API document.

Abby
 So, "service" in the 2nd meaning can be ignored, programmatically?

Special-Student-7
 The only 1 case in which you have to programmatically use "services" in the 2nd meaning is when you create your own UNO component as an artifact of one of certain kinds.

Abby
 I don't understand.

Special-Student-7
 The LibreOffice or Apache OpenOffice main body recognizes your UNO component as an artifact of the kind by the mark that the UNO component supports the specific "service" in the 2nd meaning the kind requires.

Abby
 How can my UNO component "support" the specific "service"?

Special-Student-7
 I do not go into such details here, but it is just a matter of that the UNO component just declares so by citing the "service" name in the list of supported "services".

Abby
 I see.

Special-Student-7
 In fact, "service" in the 2nd meaning is not even mapped into Java, C#, or Python.

Abby
 Is that OK?

Special-Student-7
 It is OK, because you have no opportunity to programmatically use any "service" in the 2nd meaning except as just citing the name.

Abby
 Hmm.

Special-Student-7
 3rd, "service" is used to represent a 'UNO service'-specific UNO service instances factory.

Abby
 You know what? It isn't any service at all, but a service instances factory!

Special-Student-7
 You are right.

Abby
 . . . Isn't "service" in the 3rd meaning called "constructor" in the official reference document?

Special-Student-7
 As far as I understand, the "constructor" is a method in a 'UNO service'-specific UNO service instances factory, not any 'UNO service'-specific UNO service instances factory itself.

Abby
 Hmm . . .

Special-Student-7
 Anyway, those 3 concepts are of 3 intrincically different natures, which are jumbled up as just "service" in the official documents.

Morris
 How come such an ugly situation?

Special-Student-7
 Well, an essential part of understanding is to distinguish different things as different things and an essential role of terminology is to demarcate different things as different things, but they could not do well in those respects.

"service" in the 2nd meaning is an interface that may be (but may not be) implemented by a UNO service, but both such interfaces and UNO services are just called "services" without distinction.

Morris
 Like both curry and shit are called "shit" without distinction.

Special-Student-7
 "service" in the 3rd meaning is a factory you may choose to (but do not necessarily have to) create for a UNO service, but also such factories are just called "services" without distinction.

Morris
 Let us call also beef stew "shit", as it resembles shit.

2: What Are "Old-Style Service" and "New-Style Service" in the Official Reference Document?


Abby
 I don't understand the distinction between "old-style service" and "new-style service".

Special-Student-7
 Ah, also I am not sure, actually.

Abby
 . . . Is that it? You are not sure, and let's just forget about it?

Special-Student-7
 Actually, yes, we can forget about it: the distinction does not really matter at all.

Abby
 . . .

Special-Student-7
 "old-style service" may mean a UNO service that implements multiple user-oriented UNO interfaces or may mean just "service" in the 2nd meaning, probably, sometimes the former and the other times the latter.

Abby
 Multiple meanings again!

Morris
 What do you mean by "user-oriented"?

Special-Student-7
 "user-oriented" means that the UNO interface is supposed to be directly used by users.

Morris
 Who is supposing such a thing? I am the one who decide whether I use it directly or not!

Special-Student-7
 You are right, and that is the reason why I say that the distinction does not matter: such an assumption is just uncalled for.

"new-style service" should mean a UNO service that implements only 1 user-oriented UNO interface, but also it usually implements multiple UNO interfaces because it implements non-user-oriented UNO interfaces like 'com.sun.star.lang.XTypeProvider', 'com.sun.star.lang.XServiceInfo' and 'com.sun.star.lang.XInitialization', and technically speaking, there is no meaningful distinction between "old-style service" and "new-style service" because both of them implement multiple UNO interfaces.

The distinction is just with respect to someone's assumption, "Users will use only this UNO interface!".

Abby
 However, the official document is saying that only "new-style services" can have "constructors".

Special-Student-7
 Actually, that claim is not true.

Abby
 Huh? Is it just "not true"?

Special-Student-7
 The truth is that any "old-style service" can have "constructors", but the return types of all its constructors have to be the same UNO interface.

Abby
 So, it's just a matter of my not being able to designate the return type per constructor?

Special-Student-7
 Yes, it is.

Abby
 How slipshod . . .

Special-Student-7
 The official document seems to be saying that any "new-style service" has the obvious return type, but what do you choose as the return type for an "old-style service"?

Morris
 That is none of their business; I just choose one.

Abby
 And the official document calmly states that "old-style services" aren't mapped to Java, without any further explanation . . .

Special-Student-7
 That is when "old-style service" suddenly means "service" in the 2nd meaning.

Morris
 How come such a mix-up?

Special-Student-7
 "new-style service" does not require any "service" in the 2nd meaning, which is a compound of multiple UNO interfaces, so, "service" in the 2nd meaning is understood to be for "old-style service", and "service" in the 2nd meaning and "old-style service" are strongly connected in their heads, and somehow jumbled up in their heads, I guess.

3: Are They Really Datum Types?


Special-Student-7
 Although there is a table that claims to be a table of UNO datum types, some of the items cited there are not any datum type.

For example, there is no such thing as a datum of 'any' type.

Abby
 Isn't there?

Special-Student-7
 There is not. 'any' is a variable type, not any datum type.

Abby
 What's the difference?

Stage Direction
Special-Student-7 sighs tiredly.

Special-Student-7
 One of my pet peeves is that many people do not use very essential terms appropriately, like 'datum', 'variable', 'expression', and 'value'.

You know, any variable is a box, while any datum is something that can be put into or pointed by a box. You can discern a box and an apple in the box, can't you?

Abby
 I can discern as much as I won't rather eat the box.

Special-Student-7
 'any' is a type of box that can contain a 'long' datum, a 'string' datum, etc., but there is no such thing as an 'any' datum.

Morris
 But there is the '::com::sun::star::uno::Any' class in C++ UNO, whose instance seems to be an 'Any' datum.

Special-Student-7
 You should distinguish the UNO world from its C++ mapping; 'any' is purely a variant variable type in the UNO world, but as C++ has no variant variable type, C++ UNO has the class in order to compensate the lack; in Java UNO, the 'Object' variable type is basically used for 'any'.

Abby
 Isn't 'Object' a datum type?

Special-Student-7
 When I do like 'Object l_object = new String ("Test");', the datum pointed by the 'Object' type variable is a 'String' datum rather than an "Object" datum. Certainly, the 'String' datum is a kind of 'Object' datum object-oriented-programming-wise, but what I mean is that it is different from 'Object l_object = new Object ();'. . . . As the 'Object' variable type is not really a variant variable type in Java, the Java example does not exactly match the UNO world, but I hope you will understand what I mean.

Abby
 I understand: there is no such thing as 'any l_any = any ();' while 'any l_any = 1;' is possible, right?

Special-Student-7
 Yes, kind of.

And there is no such thing as a 'void' datum.

'void' is a sign that signifies that a function does not return any datum or a state that an 'any' variable does not contain or point to any datum.

Abby
 So?

Special-Student-7
 Any datum type is the type of a datum (as the name indicates), and where there is no datum, there can be no datum type.

Abby
 Do you mean that 'null' in C# is not any datum type?

Special-Student-7
 'null' in C# or Java is not any datum type, as there is no datum there.

4: Beware That There Are Some Nonsensical or Incongruous Statements in the Official Reference Document


Special-Student-7
 As the official reference document claims that we cannot cast a UNO object to a UNO interface implemented by the UNO object because the compiler does not know that the UNO component implements the UNO interface, the claim is really nonsensical: in Java, we cast an object to an interface BECAUSE the compiler does not know that the object implements the interface (as the compiler does not know the fact, the programmer has to assure the compiler of the fact).

Abby
 Did the author know Java?

Special-Student-7
 I hope not.

Abby
 You "hope not"?

Special-Student-7
 That is because I do not want to think ill of the author: if he or she did, I will have to conclude that he or she must have intentionally made a perfunctory statement, without any due respect to the readers.

Abby
 Well . . .

Special-Student-7
 I have noticed also a nonsensical claim concerning Java 'final', which does not mean any constantness of the datum pointed by the 'final' variable.

Abby
 . . . Did the author know Java?

Special-Student-7
 I hope not.

Abby
 I have found that the official reference document warns me to use 'Variant' variables, not 'Object' variables, in order to accommodate UNO objects in Basic, but 'Object' variables are mostly used in sample code pieces . . .. What's happening?

Special-Student-7
 I guess that that is a case of "Don't do as I do; do as I tell you to do", which is not nice.

Abby
 Similarly, the new set of UNO interfaces that are recommended to be used according to the introduction of the new concept of "component context" are not used in most sample code pieces in the recommending official reference document!

Special-Student-7
 Well, I can only warn that there are some such cases.

5: Beware That Some Statements in the Official Reference Document Are Obsolete


Special-Student-7
 In fact, the official reference document is an unrevised old document for now-discontinued OpenOffice.org. Most noticeably, some tools (for example, 'idlcpp', 'xml2cmp', 'regcmp', 'autodoc', and 'rdbmaker') and files (for example, 'Setup.xcu') introduced there do not even exist any more.

Morris
 What should I do without those tools and files?

Special-Student-7
 I just do not use those tools (they are not particularly indispensable); we use 'base.xcd' instead of 'Setup.xcu'.

Morris
 All right.

Special-Student-7
 The official reference document claims that we have to use a 32-bit version JDK, but that requirement is obsolete.

Morris
 All right.

6: So, How Can We Use the UNOIDL API Document?


Special-Student-7
 We need to know what UNO interfaces the UNO object we are going to handle implements. If we know that, we can look up those UNO interfaces in the UNOIDL API document (here for LibreOffice and here for Apache OpenOffice) and know what methods each of those UNO interfaces has.

Morris
 Then, just tell me how I can know that.

Abby
 Yes! For example, I get a UNO proxy to a UNO object as the 'UNO interface'-typed return of a method; I certainly know that the UNO object implements the UNO interface; but how can I know what other UNO interfaces the UNO object implements, which is what I have to know, from the UNOIDL API document?

Special-Student-7
 Actually, generally speaking, you cannot.

Morris and Abby
 Huh?

Special-Student-7
 In fact, that is natural because the UNOIDL API document is about the UNO space but the UNO space does not contain any UNO component. So there is no information about any UNO component there.

Abby
 . . . That's natural, certainly, but its being natural doesn't help me at all.

Special-Student-7
 Well, there are some cases in which you can guess, although cannot know for sure, the UNO interfaces implemented by the UNO component.

Abby
 "some cases" and "guess" . . .

Special-Student-7
 In that case cited by madam, you can look up all the "services" that contain the UNO interface, in the UNOIDL API document, and one of them may be implemented by the UNO component.

Abby
 "look up all", "one of them", and "may" . . .

Special-Student-7
 "Service" in the UNOIDL API is "service" in the 2nd meaning, but sometimes, the name of a "service" is identical with the name of a UNO service.

Abby
 "sometimes" . . .

Special-Student-7
 So, when you get a UNO proxy to a UNO object from a UNO services manager by the UNO service name, probably, the UNO object implements the UNO interfaces listed in the "service".

Abby
 "probably" . . .

Special-Student-7
 . . . They are what you can guess from the UNOIDL API document.

Abby
 That's not a very encouraging prospect . . .

7: We Can Programatically Know What UNO Interfaces a UNO Object Implements If the UNO Component Allows


Special-Student-7
 However, we can programmatically know what UNO interfaces a UNO object implements if the UNO component allows.

Abby
 Why didn't you say so?

Special-Student-7
 Well, I am explaining things step by step, madam.

Morris
 What do you mean by "if the UNO component allows"?

Special-Student-7
 The UNO component has to have implemented a UNO interface, 'com.sun.star.lang.XTypeProvider'.

Morris
 And what is the percentage of UNO components that have implemented the UNO interface, among all the UNO components in LibreOffice?

Special-Student-7
 I do not know exactly, but I guess that most of all the UNO components in LibreOffice have implemented the UNO interface.

Morris
 That's good. So, how can I programmatically know what UNO interfaces a UNO object Implements?

Special-Student-7
 Well, we will learn that in a future article, as we have not delved into any actual programming or even built the development environment, yet.

8: What Are "Components" in the Official Documents?


Abby
 I have noticed that the author's pet word is "component"; here "component" there "component", and I don't understand what each "component" means.

Special-Student-7
 Well, the term, "component", is abused too much to let me list meanings that the term may represent. . . . Certainly, those usages of the term may not be wrong (almost anything can be called a "component" in the broad meaning of the term), but if each appearance of the term does not let the reader reasonably infer what is represented by the appearance, such a usage cannot be said to have fulfilled the purpose of the appearance.

Morris
 So, what can I do about it?

Special-Student-7
 . . . You may be able to infer what each appearance of the term means, if you read the document after you have sufficiently understood the contents of the document.

Morris
 I'm reading the document because I haven't sufficiently understood the contents of it!

Special-Student-7
 That is a typical case of 'A multiple-meaning term is quite hard to be clarified by contexts.'. The author thinks that the document should be understandable, reading it himself or herself, but it is understandable for him or her, just because he or she already understands it. That is the reason why I say that you should not expect to be able to clarify multiple-meaning terms by contexts.

References
  • Apache OpenOffice Wiki. (2014/01/02). Apache OpenOffice Developer's Guide. Retrieved from https://wiki.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide
  • N/A. (N/A). LibreOffice: Main Page. Retrieved from https://api.libreoffice.org/docs/idl/ref/index.html
  • The Apache Software Foundation. (2013). Module star. Retrieved from https://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
 <The previous article in this series | The table of contents of this series | The next article in this series>
Posted by at
Labels: