Overview

The text generation facility builds English glosses of varying form and detail for instances in the clib. For a given instance, it may be able to generate a word, a definite or indefinite noun phrase, an existential-there sentence, or an active or passive finite sentence.

This facility is implemented as a grammar distributed through the clib ontology. This allows classes in the ontology to override more general grammar rules to produce glosses more appropriate to more specific ontology classes. For example, for most Event instances, it is appropriate for the agent slot to appear as the subject of the active sentence and the object slot to appear as its direct object. For Create Events, the result slot is a more appropriate direct object and for Transfer Events, the donor slot is a more appropriate subject.

The grammar rules, then, appear as axioms on special text generation slots that appear on classes throughout the ontology. Most of these rules appear in the top-level classes Entity, Event, Role and Property-Value. Some subclasses of Event redefine the more general rules.

In addition to text generation slots for grammar rules, there are some "pre-terminal" text slots. These should appear on most classes in the ontology to specify words that should be used in generation. For example, most subclasses under Event specify the singular and plural forms of active and passive verb sequences appropriate to the Event. Slots in the ontology also store such lexical information, including prepositions, nouns and/or verbs appropriate to the slot in different contexts.

Text Generation Slots

Using or modifying the clib's text generation facility requires familiarity with the slots used in the generation grammar.

The first table below lists the slots most useful for a user of text generation. The slots are the ones most often used to produce text glosses for instances.

The second table shows the full suite of text generation slots, grouped according to where you're likely to find them being used in the ontology. The second table includes detail you'd need to modify the clib's distributed grammar.

A note on KM's make-phrase and make-sentence

Some of the text generation slots get filled with strings, ready-to-display. Some of them are filled by instances or sequences that need to be "stringified" for display. KM's make-phrase and make-sentence functions should be used for stringifying non-string fillers. It's safe to use them on strings, too.

The make-phrase function takes any KM object as its sole argument and turns it into a string. The make-sentence function does the exact same thing, but makes the first character of the resulting string upper case and puts a period at the end. Some of the top-level text generation slots call make-sentence for you. Two warnings if you call it yourself:

  1. make-sentence always converts the first character to upper case, even if the first character in the string does not correspond to the first "letter" in the "sentence" (for example, if you're including punctuation or html tags at the beginning of your string, make-sentence won't capitalize the first letter)
  2. make-sentence always puts a period at the end of the string, even if there is already sentence-ending punctuation at the end.

User-level text generation slots

slot description top-level domains return format example
text-gen general top-level gloss for instances; the syntactic structure depends on the class of the instance (see examples) Event, Entity, Property-Value, Role, Time-Instant string
KM> (the text-gen of (a Move-Into))
("The object gets moved into the container through the portal.")

KM> (the text-gen of (a Move-Into with (agent ((a Person)))))
("The person moves the object into the container through the portal.")

KM> (the text-gen of _Device15)
("the 1 inch long device made of metal")

KM> (the text-gen of (the length of _Device15))
("1 inch long")

KM> (the text-gen of _Container19)
("the container containing the device")

KM> (the text-gen of _Time-Instant21)
("Tuesday, December 16, 2003, 15:27:00 CST")
text-description a different top-level description of an instance; text-description is identical to some other text generation slot, but differs depending on the class; for Events, it is the text-nom-sentence; for Entities, Roles and Property-Values, it is the text-sentence Event, Entity, Role, Property-Value string
KM> (the text-description of (a Teach))
("The teaching of the information is by the teacher to the pupil.")

KM> (the text-description of (a Artifact))
("The artifact is result of the creation of an artifact.")

KM> (the text-description of (a Barrier))
("The barrier is used in the blocking.")
text-definition-sentence sentence describing an instance's class in terms of its superclasses Event, Entity, Role string
KM> (the text-definition-sentence of (a Lose))
("The loss of an entity is a transfer.")

KM> (the text-definition-sentence of (a Artifact))
("An artifact is an inanimate-object that is result of the creation of an artifact.")

KM> (the text-definition-sentence of (a Barrier))
("A barrier is a role that is played in the blocking.")
text-existential-there an "existential-there" sentence Event, Entity, Role, Property-Value string
KM> (the text-existential-there of (a Produce))
("There is the production of an entity.")

KM> (the text-existential-there of _Device15)
("There is a device.")

KM> (the text-existential-there of (a Barrier))
("There is a barrier.")

KM> (the text-existential-there of (the length of _Device15))
("There is a length of 1 inch.")
text-nom-sentence a finite sentence for Events in which the Event is represented as a nominalization with object in the subject position and arguments appear as complement of "be" Event only string
KM> (the text-nom-sentence of (a Produce))
("The production of the result is out of the tangible-entity.")

KM> (the text-nom-sentence of (a Teach))
("The teaching of the information is by the teacher to the pupil.")
text-passive-sentence a passive sentence for Events (used to force a passive construction even if a potential subject exists) Event only :seq
KM> (make-sentence (the text-passive-sentence of (a Produce)))
("The result gets produced out of the raw-material.")

KM> (make-sentence (the text-passive-sentence of (a Teach)))
("The information gets communicated to the pupil.")
text-sentence a finite sentence for Events, Entities, Roles, and Property-Values; since the default text-gen of Entities and Roles is a noun phrase, text-sentence can be used to force a finite sentence; text-sentence is equivalent to text-gen for Events and text-description for Entities and Roles Event, Entity, Role, Property-Value :seq
KM> (make-sentence (the text-gen of (a Move-Into)))
("The object gets moved into the container through the portal.")

KM> (the text-sentence of (a Artifact))
("The artifact is result of the creation of an artifact.")

KM> (the text-sentence of (a Barrier))
("The barrier is used in the blocking.")

KM> (the text-sentence of (the length of _Device15))
("the length of the device = 1 inch")
text-def-head definite noun phrase with no premodifiers or postmodifiers Event, Entity, Role :seq
KM> (make-phrase (the text-def-head of (a Come-Together)))
("the coming together")

KM> (make-phrase (the text-def-head of _Device15))
("the device")

KM> (make-phrase (the text-def-head of _Container19))
("the container")
text-indef-head indefinite noun phrase with no premodifiers or postmodifiers Event, Entity, Role :seq
KM> (make-phrase (the text-indef-head of (a Come-Together)))
("a coming together")

KM> (make-phrase (the text-indef-head of _Device15))
("a device")

KM> (make-phrase (the text-indef-head of _Container19))
("a container")
text-phrase definite noun phrase with premodifiers and postmodifiers Event, Entity, Role, Property-Value :seq
KM> (make-phrase (the text-phrase of (a Produce)))
("the production of the result out of the tangible-entity")

KM> (make-phrase (the text-phrase of _Device15))
("the 1 inch long device made of metal")

KM> (make-phrase (the text-phrase of _Container19))
("the container containing the device")

KM> (make-phrase (the text-phrase of (the length of _Device15)))
("1 inch long")
text-indef-phrase for Entities and Roles, an indefinite noun phrase with premodifiers but no postmodifiers; for Events, this actually gives a definite noun phrase with a nominalization as head and an indefinite object Event, Entity, Role :seq
KM> (make-phrase (the text-indef-phrase of (a Produce)))
("the production of an entity")

KM> (make-phrase (the text-indef-phrase of _Device15))
("a 1 inch long device")

KM> (make-phrase (the text-indef-phrase of _Container59))
("a container")

Programmer-level text generation slots

slot description main files used to construct format
Rule Slots
text-active-phrase the active verb sequence, conjoined and prefaced by "do/does" if multiple Event.km text-active-sentence :seq
text-active-sentence subject, active verb sequence, object, arguments Event.km text-sentence :seq
text-active-verbseq plural or singular verb sequence, depending on the number of the subject Event.km text-active-phrase :seq
text-arguments the verb arguments; fillers of the slots in text-argslots, prefaced with each slot's text-slot if available Event.km text-active-sentence; text-passive-sentence :seq
text-base-phrase base noun phrase including definite determiner, premodifiers and noun head; also includes postmod object for Event nominalizations Event.km; Entity.km; Role.km text-phrase; text-sentence (Entity.km, Role.km); text-nom-sentence (Event.km) :seq
text-def-determiner definite determiner for noun phrases; "the" for Events and Property-Values; NIL for named instances; NIL for anonymous Substances with no is-possessed-by; "the" or is-possessed-by for Entities and Roles Event.km; Entity.km; Role.km; Property-Value.km; Substance.km text-base-phrase; text-def-head :seq
text-def-head definite noun phrase with definite determiner but no premodifiers or postmodifiers Event.km; Entity.km; Role.km; Property-Value.km text-sentence (Entity.km, Role.km); text-nom-sentence and text-indef-phrase (Event.km); also often used for arguments of verbs and noun phrase postmodifiers :seq
text-definition-sentence sentence describing an instance's class in terms of its superclasses Event.km; Entity.km; Role.km string
text-description sentence describing an instance Event.km; Entity.km; Role.km; Property-Value.km string
text-dobj-phrase the text-def-head of the filler of the slot chosen for direct object of a verb (may also be the name of the slot itself if the filler is too generic) Event.km text-active-sentence; text-passive-sentence; text-base-phrase :seq
text-dobj the instance to be used for direct object of the verb (usually the filler of the object slot, sometimes the result Event.km text-dobj-phrase; text-indef-phrase Instance
text-existential-there existential-there sentence describing an instance Event.km; Entity.km; Role.km; Property-Value.km string
text-gen general purpose sentence describing an instance Event.km; Entity.km; Role.km; Property-Value.km; Time-Instant.km string
text-head noun head for noun phrases, including possibly postmodifying "called" tag Event.km; Entity.km; Role.km; Property-Value.km text-def-head; text-indef-head; text-base-phrase; text-indef-phrase; also text-phrase and text-sentence for Property-Values :seq
text-indef-determiner indefinite determiner for noun phrases; NIL for Substances; "a" or "an" for all others, depending on the first letter of the text-head; should override text-indef-determiner locally for exceptions Event.km; Entity.km; Role.km; Property-Value.km; Substance.km text-indef-head; text-indef-phrase string
text-indef-head indefinite noun phrase with indefinite determiner but no premodifiers or postmodifiers Event.km; Entity.km; Role.km; Property-Value.km text-sentence (Entity.km, Role.km); text-existential-there text-definition-sentence; text-indef-phrase :seq
text-indef-phrase indefinite noun phrase with indefinite determiner and premodifiers but no postmodifiers Event.km; Entity.km; Role.km text-existential-there; text-definition-sentence; text-indef-phrase (Event.km) :seq
text-nom-sentence finite sentence with Event nominalization in subject position Event.km text-description; text-passive-sentence :seq
text-number the number of the text-subj (active) or text-dobj (passive) Event.km text-description; text-passive-sentence Number
text-passive-phrase the passive verb sequence, conjoined and bracketed by "has/have ... done to it/them" if multiple Event.km text-passive-sentence :seq
text-passive-sentence object, passive verb sequence, arguments Event.km text-sentence :seq
text-passive-verbseq plural or singular verb sequence, depending on the number of the subject Event.km text-passive-phrase; text-passive-sentence :seq
text-phrase base noun phrase + postmodifiers Event.km; Entity.km; Role.km; Property-Value.km text-gen (Entity.km, Role.km, Property-Value.km) :seq
text-postmods fillers of the text-postmodslots with prepended text-slot markers; for Property-Values, the only postmods are postposed adjectives on cardinal values (e.g. "1 meter long") Event.km; Entity.km; Role.km; Property-Value.km text-definition-sentence; text-phrase; text-nom-sentence :seq
text-premods fillers of the text-premodslots, used for noun phrase premodifiers; for Property-Values, the text-premods slot is used for mathematical variables (e.g. "x = ") or property-of information (e.g. "the length of the stick = ") Event.km; Entity.km; Role.km; Property-Value.km text-base-phrase; text-indef-phrase; text-nom-sentence; text-sentence (for Property-Values) :seq
text-sentence a finite sentence for Events, Entities, Roles and Property-Values Event.km; Entity.km; Role.km; Property-Value.km text-gen (Event.km); text-description (Entity.km, Role.km, Property-Value.km) :seq
text-subj-phrase the text-def-head of the filler of the slot chosen for subject of a verb (may also be the name of the slot itself if the filler is too generic) Event.km text-active-sentence :seq
text-subj the instance to be used for subject of the verb (usually the filler of the agent slot, sometimes the instrument Event.km text-subj-phrase Instance
Preterminal Slots
text-active-verbseq-pl active plural form of the verb subclasses of Event text-active-verbseq string
text-active-verbseq-sg active singular form of the verb subclasses of Event text-active-verbseq string
text-argslots list of slots to be used in generating verb arguments subclasses of Event text-arguments :seq
text-gloss verb phrase for slots instances of Relation Viewpoints string
text-nominalization nominalization of the verb subclasses of Event text-head string
text-particle used to identify words that can appear between the verb and its arguments; useful for States and phrasal verbs subclasses of State, some Actions text-arguments string
text-passive-verbseq-pl passive plural form of the verb subclasses of Event text-passive-verbseq string
text-passive-verbseq-sg passive singular form of the verb subclasses of Event text-passive-verbseq string
text-postmodslots list of slots to be used in generating noun phrase postmodifiers subclasses of Event, Entity, Role text-postmods :seq
text-premodslots list of slots to be used in generating noun phrase premodifiers subclasses of Event, Entity, Role text-premods :seq
text-slot for each Relation, the name of a slot containing the Relation's marker (often a preposition) instances of Relation text-postmods, text-base-phrase, text-arguments text-[relation]