< Back to IRCAM Forum

Docstring conventions in OM

OpenMusic
#1

I noticed, while looking through metaclasses.lisp, that the docstrings use a particular hashtag-based markup syntax, like so:

"The class of the OM patch metaobjects. #enddoc#
#seealso# (OMPersistantObject OMmaquette OMTemporalPatch OMPatchAbs) #seealso#
#boxes# A list of the boxes which define the patch. #boxes#
#code# A symbol to reference the code definition of the patch. #code#
#connec# Used to save connections beetween boxes in the patch definition. #connec#
#compiled?# Nil if the patch was modified and not compiled.#compiled?#
#pictu-list# This slot has a list of pictures's names pointed to pictures resources in the patch file.#pictu-list#
#lisp-exp-p# Patches can be defined by a lambda expression in place of graphicly,
in this case this slot keeps the lambda expression.#lisp-exp-p#
#show-connections?# Flag to show or hide connections.#show-connections?#"

Interesting, isn’t it? This kind of commentary is used by documentation preparation tools for formatting and hyperlinkage. But which tool understands the syntax shown here?

#doc

Towards a revivified OpenMusic manual
#2

Hi johnathan,

I believe these are standard (old) conventions not used directly in OM. However there is an om system for generating om documentation starting from the defclass* derived from these classes . You will find this in the /kernel/doc/documentation.lisp. For the latter, i will ask. I believe it is a remnant of old MCL convention.

Best
K

#3

Hi Jonathan

Just to confirm, that the hash tags are from an old code, and were supposed as you guessed, to auto produce some html code. I just asked about this one of the original authors of OpenMusic (Pr. C. Agon).

Best
K

#4

Thanks for looking into it, Karim. It’s safe to say, then, that the "#...#" tag convention is no longer operant?

I think that being able to put hyperlinks and other formatting into docstrings is basically beneficial. It’s something of a shame that the Common Lisp community hasn’t come to a consensus on a format, like Python has, e.g., with reStructuredText.

-J.

#5

By the way, is it possible for me to download the HTML for the whole manual (OpenMusic Documentation)?