OpenCyc.org HomepageA Style Guide for #$comments

E-Mail Comments to: opencyc-doc@cyc.com
Last Update: 03/28/2002
Copyright© 1996-2002 Cycorp. All rights reserved.

Return to Table of Contents

The predicate #$comment is used to attach a string of explanatory text to a Cyc® constant. Whenever a Cyc constant is created, a #$comment assertion should be written for it. This page gives some guidelines for the content and style of text in comments. Clarity is the most important stylistic criterion, because we want readers to understand the intended meaning and proper usage of our constants.

Other instances of #$DocumentationPredicate are available for providing comments of a more specific, more technical or more transient nature. These include #$cyclistNotes, #$examples-Positive and #$examples-Negative. While this document primarily focuses on the #$comment predicate, certain guidelines (e.g., prefixing constant names with "#$") will clearly apply to use of these other predicates as well.


A. Follow these GENERAL GUIDELINES when composing comments:

1. Mention at the outset the type of constant you're describing (e.g., collection, predicate, function). Guidelines for explaining specific types of constant are given below.

2. Explain the meaning of the constant in clear and economical prose, correctly punctuated and spelled. Use complete sentences, except perhaps for the very first one, which can be a dictionary-like phrase such as "A collection of events."

3. Be precise in your use of Cyc constant names within #$comment text:

(a) In #$comment text, Cyc constant names should be preceded by the "#$" prefix, so that links from your comment to those constants can be generated in the html browser. Misspelled names will not link. Note that Cyc's code can handle a leading or ending parenthesis, and a trailing comma, period, semicolon, colon, question mark, exclamation point, hyphen, or plurals formed with "s" and "es." It cannot, however, handle plurals formed by removing "y" and adding "ies"; for example, '#$Microtheories' (from #$Microtheory) would not be recognized.

(b) Don't confuse the names of Cyc constants (e.g., #$Animal) with their English homonyms (e.g., `animal'). The name of a Cyc collection (e.g., #$Person, #$Speaking) is not the same thing as an English noun. Don't say, for example, "#$Person is the collection of those #$Animals which...." Instead, say "#$Person is the collection of those animals which...;" or, alternatively, "#$Person is a specialization of #$Animal." Although an experienced Cyclist could recognize that `Flipper is a #$Dolphin' "means" that Flipper is an element of the Cyc collection #$Dolphin, rather than that he is the same type of thing as that collection, the sentence is potentially confusing. Such casual "insider" usages exist in the KB, but we try to avoid adding similar violations in new work.

4. To help explain the meaning of a constant, give some example instances of collections and some typical uses of a predicate or a function. It is permissible to use made-up constant names for examples, with the following proviso: If a made-up constant represents a concept that Cyc should eventually know about, write its name preceded by "#$" (e.g., #$SpaceStation). If it is only a random example, such as Dog001 or KarensLeftEar, omit the `#$' prefix.

5. Mention and perhaps illustrate any special restrictions on the meaning or use of the constant.

6. Use a Note at the end of the #$comment text for any extra clarifications or details relevant for a general user. A Note may be used to present exceptions, borderline examples, one or more "footnotes," or pointers to related constants that a reader might want to examine (especially if those are not displayed already in the #$isa, #$genls, #$genlPreds, or other prominent assertions about the constant being commented). Formally separate the Note from the main body of the text with a single carriage return, to begin a new paragraph, or by typing two carriage returns in a row, to insert a blank line.

7. Use a #$cyclistNotes assertion for technical matters of concern only to knowledge enterers.

8. ALWAYS PROOFREAD your comments in the html browser after entering them.

B. Specialized style suggestions:

Comments on Cyc COLLECTIONS:

1. Refer to a collection as a collection, rather than as a `group' or `class' or `category'. Refer to the elements of a collection -- the values on its #$isa relation -- as elements or instances, rather than as `members' or `parts'. The #$genls relation may be described by talking about subsets and supersets, although it should be noted that Cyc collections are more restrictive than mathematical sets (cf. #$Collection, #$Set-Mathematical). In general, avoid words that are open to misinterpretation, such as "member," "sample," "illustration," "class," "category," "type," "assemblage," "grouping," "process," "activity," "circumstance"; prefer words which permit less ambiguity, such as "element" and "set" and "event."

2. Begin by stating, for a collection #$COL, "#$COL is a [or `the'] collection of ...", or "#$COL is a subset of ...." A dictionary-like introductory fragment, such as "A [or `The'] collection of ...." is also acceptable. For example:

"#$Movement-Rotation is a subset of #$MovementEvent. Elements of #$Movement-Rotation are those moving events in which the #$objectMoving rotates about an internal or external axis. For example, the daily rotation of the Earth on its axis, or the rotation of a clock hand about its fastened end."

3. Give one or more examples of your collection. As examples, mention some elements or some subsets. It is best if those examples are actual instances in the KB (e.g., #$JohnsHopkinsUniversity as an example of #$University), but examples may also be identified using ordinary English. For example, "The collection #$Movement-Rotation includes rotations of the Earth on its axis." It is permissible to make up constant names for non-existent constants, if they are entities which should eventually be known to Cyc, e.g., #$YulBrynner; but avoid those that name an obviously poor constant, e.g., #$YulBrynnersScalp. (The latter implies that Cyc might need to have trillions of constants such as `DougLenatsLeftElbow'!)

Here is a sample of a comment, a cyclist note, and a negative example on an important, broad collection of events:

comment:

A specialization of #$GeneralizedTransfer. Each instance of #$MovementEvent is an event in which at least one object translates some distance, or in which at least one object moves from one rotational orientation to another rotational orientation. Each instance of #$MovementEvent is thus a rotation or translation of some object (an instance of #$SomethingExisting), where the movement occurs relative to a frame of reference which is not part of the rotating or translating object. Notable specializations of #$MovementEvent include #$Translocation, #$Rotation-NonPeriodic, and #$Movement-Periodic.

cyclistNotes:

#$MovementEvent is the most generic collection for physical movements. For representing specific events, one or more of the following subsets of #$MovementEvent may be more precise: #$Movement-TranslationEvent, #$Movement-Rotation, #$Movement-Periodic, #$Movement-NonPeriodic, #$Translation-Flow, #$Translation-Complete, #$Translation-SingleTrajectory, #$Translation-MultiTrajectory. Some questions to consider in selecting the best collection to represent a physical movement include: (1) is the movement translational or rotational motion? (2) is it periodic or nonperiodic? (3) does it involve a discrete motion (i.e., an object's moving completely from one place to another) or a continuous flow? (4) does it involve a change of location or no location change? (5) does it involve a single pathway or more than one? Note on what is NOT included in #$MovementEvent: Consider a person's raising her hand and waving, or a tree's bending as its branches sway in a strong wind, while the person and the tree remain in the same place. The movements of the person and the tree do NOT qualify as instances of #$MovementEvent, because the `doer' in any element of #$MovementEvent must rotate or translate as a whole. The hand movement and the movement of the branches do, however, qualify as objects moving in the proper sense. So, for example, an instance of #$WavingAHand-Gesture (done by a person) would have #$subEvents which ARE elements of #$MovementEvent, in which the person's hand is the #$objectMoving.

examples-Negative:

Some instances of #$AthleticActivity such as instances of #$SportsEvent or #$SportsCompetition do involve #$MovementEvents, however, they involve numerous complex combinations of #$MovementEvents with mumerous distinct #$objectMovings, #$toLocations, #$toOrientations and so on. These #$MovementEvents would be #$subEvents of some #$SportsEvent or #$SportsCompetition. Since, for example, there is no one focal #$toLocation or set of #$toLocations that some focal #$objectMoving or set of #$objectMovings goes to at the end of the event, it would not be appropriate to assert (#$genls #$AthleticActivity #$MovementEvent). However, particular instances of #$AthleticActivity such as 'JoesSuccessfulClimbUpEverest' does have a well defined #$toLocation and #$objectMoving which is focal to the meaning of the event. Therefore it is an #$AthleticActivity which would be an appropriate element of #$MovementEvent.

Comments on Cyc INDIVIDUALS [optional]:

1. This is the only general class of exceptions to the `always write a comment' rule. Information about individuals represented in the Cyc KB (e.g., #$JohnKennedy, #$UnitedStatesOfAmerica, #$MississippiRiver) may be captured exhaustively in the CycL assertions on the constant itself. Add an English comment only if there is an unusual need for further characterization of the individual.

2. The names of Cyc constants that represent individuals may be used in #$comment text like English proper nouns. Examples: "#$JohnKennedy was the 35th President of the #$UnitedStatesOfAmerica." Another example: "#$Cycorp is headed by Doug #$Lenat."

Comments on Cyc PREDICATES:

1. Begin the comment with a general description about what the predicate relates or what it is used for. For example, "The Cyc predicate #$employees relates a particular employer to one of its paid employees...."

2. In every case, the comment should contain a sentence of the following form: "(#$<;predicate-name> ARG1-METAVAR [ARG2-METAVAR ... ARGN-METAVAR]) means that ...." That sentence should be either the first sentence in the comment or should follow a first sentence of the type mentioned in (1) above. In general, it is helpful to use mnemonic meta-variables rather than simply X, Y, Z, etc. See also (4) below.

3. To describe the constraints on arguments to a predicate:

(a) One approach, which violates the guideline about not using Cyc constant names as English words, is to use the name of the argument-constraining constant as a modifier in the following way: "(#$geographicalSubRegions SUPER SUB) means that the #$GeographicalRegion SUPER contains all of the #$GeographicalRegion SUB." That was widely done in the past.

(b) A clearer style yields this version: "The binary predicate #$geographicalSubRegions relates a geographical region to the geographical regions it spatially contains. Both arguments to #$geographicalSubRegions must be elements of #$GeographicalRegion. (#$geographicalSubRegions SUPER SUB) means that the region SUPER contains all of the region SUB."

4. Use meta-variables in comments on predicates. In an explanatory sentence such as:

"(#$geographicalSubRegions SUPER SUB) means that the region SUPER contains all of the region SUB,"

SUPER and SUB are meta-variables, because in the comment text they are placeholders that could be replaced by the names of individuals as well as by variables (with appropriate quantification and/or restriction). Write meta-variables by omitting the prefix `?' used with actual variables in the Cyc system.

Also see (5) below regarding quoting rules in comment text.

5. If you quote a rule from the Cyc KB, then variables in the rule should be quoted as actual variables, just as they are in the KB; e.g., (#$implies (#$and (#$isa ?E1 #$Action) (#$subEvents ?E ?E1) (#$doneBy ?E ?P) (#$isa ?E #$SingleDoerAction)) (#$doneBy ?E1?P)).

In general, quote a rule in order to illustrate the use of a predicate in CycL. If you are using the rule to explain the meaning of a particular predicate, it's probably better to state the rule in English rather than to quote the formal rule. For example, paraphrase the above rule as follows, for clarity: "If a particular action is of the kind that can be done only by a single agent, then all of its sub-actions have the same agent as does the overall action."

6. Here is the full comment from #$employees, as an example:

This predicate relates employers to their paid employees. (#$employees EMPLOYER WORKER) means WORKER regularly performs work for EMPLOYER, and EMPLOYER pays WORKER for that work (often by paycheck). EMPLOYER directs the manner in which WORKER performs the work and may provide the workplace, tools, capital, and other assistance for the work. EMPLOYER is commonly an organization but may be a person. E.g., (#$employees PerryMason PaulDrake). Uses of this predicate require proper temporal qualification; e.g. (#$holdsIn ( #$YearFn 1999) (#$employees #$NBC-TVNetwork #$KatieCouric)).

Notice that meta-variables in the above are upper-case and lack the preceding `?' used with actual variables in CycL. Also note that names of individuals who are used as examples but who are not in fact in the Cyc KB lack a preceding `#$'.

Another example: the #$comment text for #$likesObject:

(#$likesObject AGT OBJ) means that when the sentient agent AGT is interacting in some way with OBJ, that agent feels some measure of #$Enjoyment --- that is, (#$feelsEmotion AGT #$Enjoyment). The kinds of interactions that produce #$Enjoyment depend largely on what kind of thing OBJ is. Thus, `Joe likes the Mona Lisa' implies that Joe feels #$Enjoyment when viewing the Mona Lisa. But `Joe likes pizza' implies that Joe feels #$Enjoyment when eating that kind of food. Note: There are some specialized predicates of #$likesObject that give more information about the kind of interaction between AGT and OBJ that results in #$Enjoyment; see, e.g., #$likesSensorially and #$likesAsFriend.

Comments on Cyc FUNCTIONS:

1. Mention the type of function being described. Usually it is either #$CollectionDenotingFunction or #$IndividualDenotingFunction, but you may want to mention a more specific group of functions to which the target function belongs, e.g., #$UnitOfMeasure.

2. Mention the argument type(s) of the function, as well as its result type (i.e., #$resultIsa and/or #$resultGenls).

3. Describe generally, or make clear by example(s), how the function is used.

Here is an example, the #$comment text for #$GroupFn:

An instance of #$CollectionDenotingFunction used for representing specializations of #$Group. (#$GroupFn OBJTYPE) denotes the collection of all groups whose members (see #$groupMembers) are instances of OBJTYPE. Note that an application of #$GroupFn denotes a _collection_ that has groups as instances, rather than an individual group. For example, (#$GroupFn #$BallisticMissile) denotes the collection of all groups of ballistic missiles, which includes Russia's ballistic missiles, China's ballistic missiles, the US's ballistic missiles, etc. Also, a particular group of 101 Dalmatians is an instance of (#$GroupFn #$Dog).

#$GroupFn, an instance of #$CollectionDenotingFunction, is used for representing specialized subsets of #$Group. (#$GroupFn OBJ-TYPE) denotes the collection of all groups whose members are instances of OBJ-TYPE. Note that an application of #$GroupFn refers to a COLLECTION which has groups as elements, rather than to an individual group. #$GroupFn takes any element of #$ObjectType as its argument, returning the subset of #$Group that contains groups having instances of that #$ObjectType as its #$groupMembers. For example, (#$GroupFn #$BallisticMissile) represents the collection of all groups of ballistic missiles, which includes Russia's ballistic missiles, China's ballistic missiles, the U.S.'s ballistic missiles, etc. Another example: A group of 101 particular Dalmatians is an instance of (#$GroupFn #$Dog). Collections of groups of events may also be denoted; e.g., Columbus's voyages to North America may be considered as a group (of events) which would be an element of (#$GroupFn #$Travel-TripEvent).

Comments on Ground Atomic Formulas (GAFs) and Rules:

Use the predicate #$salientAssertions if you want to indicate that a particular assertion is essential to the meaning of some Cyc constant. Example: (#$salientAssertions #$SingleDoerAction (#$implies (#$and (#$isa ?E1 #$Action)(#$subEvents ?E ?E1)(#$doneBy ?E ?P)(#$isa ?E #$SingleDoerAction))(#$doneBy ?E1 ?P))).

Note that, although it is possible and sometimes useful to write a #$comment text for a particular Cyc rule or GAF, that is not a common practice (nor should it be). To place a comment on a rule or GAF, make the formula itself the first argument to #$comment. Example: (#$comment (#$genls #$Person #$Animal) "This GAF really doesn't need a comment.").

Finally, here are some special requirements for html-based interfaces such as Cyc presently uses:

Some characters require special handling:


Go to Top