Review Maintenance ontology example

[johanwk]

The ontology at https://github.com/iofoundry/ontology/tree/master/maintenance has been converted in to ELOT format in a semi-automatic way. After some corrections, fbe6443 is very close to the original.

The ROBOT diff command reports only differences related to annotations and the ontology id.

[VladimirAlexiev]

Excellent example!

• [x] remove tags from HTML export of headers (I think it's #+OPTIONS: tags:-) : ** Disjointness clause :nodeclare: causes
• [x] remove empty headings eg Source blocks for prefixes
• [x] TOC doesn't show until you scroll a bit down from the shown position. This is a feature of "readthedoc" not a bug: the TOC expands automatically, eg when you scroll Classes into view, it shows its subsections. But it's weird to have just one heading initially. So I think you need to put this in #+TITLE: instead of a singleton root heading
• [x] Do you really intend to show the :OMN: block with comments and tangle inclusions? Here's a small bit, and you can see it all in the shot above

  ## Prefixes
  <<omn-prefixes()>>

• [x] "There is a problem in that the identifier for the Maintenance ontology itself is the same as the prefix. This has been changed here". I think this practice is fine and I use it often. Then you can use an empty local name, eg ont: a owl:Ontology.... <term> rdfs:isDefinedBy ont:
• [x] Annotation props are sorted alphabetically by URL (example for class iof-maint:FailureEffect). But that's not the best way, eg naturalLanguageDefinition should come before example. I understand that's just an artefact of the semi-automated conversion you did. But is there a need for a function to reorder annotation props in a "logical" way? Related to https://github.com/johanwk/elot/issues/38?
• [x] Replace full URLs with prefixed annotation props: https://spec.industrialontologies.org/ontology/core/meta/AnnotationVocabulary/Released -> iof-av:Released

[johanwk]

* [ ]  Do you really intend to show the `:OMN:` block with comments and tangle inclusions? Here's a small bit, and you can see it all in the shot above

No, absolutely not! Could there be something strange going on on your side? The OMN block has header arguments :exports none, which should stop exporting. Similarly with the headline "Source blocks for prefixes", where there's a :noexport: tag. I believe the org-mode default is to respect these, but obviously that's not what happened with your HTML export.

[VladimirAlexiev]

Ok, I see it now:

:PROPERTIES:
:ID: Maintenance
:ELOT-context-type: ontology
:ELOT-context-localname: Maintenance
:ELOT-default-prefix: iof-maint
:header-args:omn: :tangle ./Maintenance.omn :noweb yes
:header-args:emacs-lisp: :tangle no :exports results
:header-args: :padline yes
:END:
:OMN:
#+begin_src omn :exports none

You specify the header args in two spots (:header-args:omn: and #+begin_src), maybe that confuses it somehow? My org-version is "9.6.19".

@mhodki do you see this problem?

[johanwk]

[ ] Replace full URLs with prefixed annotation props: [ ] "There is a problem in that the identifier for the Maintenance ontology itself is the same as the prefix. ... you can use an empty local name, eg ont: a owl:Ontology.... rdfs:isDefinedBy ont:

This has been fixed in the body of the document.

I now realise that the code has been made to reject with Fail! any attempts to use bare prefixes! Since it's right as you say, that an ontology identifier may indeed consist in just ont:, I need to change this. New issue #46.

[johanwk]

[ ] Annotation props are sorted alphabetically by URL (example for class iof-maint:FailureEffect). But that's not the best way, eg naturalLanguageDefinition should come before example. I understand that's just an artefact of the semi-automated conversion you did. But is there a need for a function to reorder annotation props in a "logical" way?

On this point, I don't see how an optimal ordering could be done automatically. The user can of course reorder the headlines as wanted.

(iof-av:naturalLanguageDefinition is in fact a subproperty of skos:definition, so it's skos:definition that would need to be moved to a better position in the list.)

[johanwk]

I crossed out "remove empty headings", "hide OMN block", since I'm almost certain that the `:noexport: tag mechanism works in most cases.

[johanwk]

remove tags from HTML export of headers (I think it's #+OPTIONS: tags:-) :

I've added the following settings into the document. Maybe these should be the default settings! But I think it's something to discuss.

# hide TODO status in headings
#+OPTIONS: todo:nil
# hide completion "cookies" [4/4]
#+OPTIONS: stat:nil
# hide tags
#+OPTIONS: tags:nil

[johanwk]

[ ] TOC doesn't show until you scroll a bit down ... I think you need to put this in #+TITLE: instead of a singleton root heading

I don't quite understand what you mean should go in the title.

Maybe this will explain: It's actually not possible/preferable to avoid a heading that is above the "Classes", "Object Properties", and so forth headings. This is because some :PROPERTIES: need to be inherited down to those sections-per-OWL-type. And, it's done on purpose because I expect that users will have more content in an ELOT document than just the ontology definition. Either for documentation purposes (as we do with IDO), or even to define more than one ontology in the same document. Or for work with templates, where I have OTTR in mind -- a separate top-level headline would be used for writing an OTTR library to support the ontology.

Again, I think this is a topic for discussion. If we decide it's best to say "one ELOT document, one ontology only", then the properties that are currently inside the top-level heading can be made global to the document, and the top-level heading can be removed. This has the advantage of promoting the "Classes" heading, etc., to top-level headings. (But all that being said, one could potentially have one main ontology, and then override properties for a heading under which another ontology is defined.)

[johanwk]

An update allows puris without localnames, and the Maintenance ontology now has the right identifier. (Please pull the update.)

[johanwk]

I'm closing this, as all major points have been addressed.