[developers] doc-strings in TDL for DELPH-IN

[Michael Wayne Goodman]

Hi Francis, thanks for keeping the conversation alive.

We're in agreement about the triple-quoted docstrings, and that a docstring
in a type addendum should be concatenated to any docstrings from previous
type definitions/addenda.

The remaining issue is placement, and what you advocate (basically Option 3
on the wiki) brings up a disconnect between the conventional way of
describing types (supertypes before features) and what's formally allowed
by (our current implementations of) TDL (rearrangeable terms). Also, type
addenda do not require supertypes at all. I'll try to avoid getting into
this quagmire again lest it stall the conversation, and instead offer two
simpler choices (ignoring other alternatives), either of which would allow
you to do what you want:

(1) we change our TDL-parsers to ensure that top-level supertypes, if any,
appear before other terms

(2) we allow a docstring to appear before any top-level term (Option 2 on
the wiki) or before the final . character, but only one per
(type/addendum/instance) definition

Above, (1) is the heavier solution that may break backward compatibility
with some grammars, while (2) would allow you to put docstrings where you
don't necessarily want them (but you can always follow your own
convention). I'm happy to support either.

On Fri, Aug 3, 2018 at 8:59 PM Francis Bond <bond at ieee.org> wrote:

> G'day,
>
> I am starting a new thread as the other one was getting quite long:
> thanks Michael for starting the original discussion.
>
> We need doc-strings working to move forward with the new linguistic
> type documentation.   It is a great pity that Stephan,Woodley, Michael
> Glenn and Ann were not there on that day, but we reached a broad
> consensus at Paris that triple double quotes ' """  ' was a good
> delimiter, with them basically allowed after the types.  We have (if I
> understand correctly) code for PET from Rebecca, and code for the LKB
> (from Dan, although it may need to be extended to the instances).
>
> Woodley currently has a working implementation with just ' " ' (but
> only after := , not for example, :+) which allows for escaped quotes '
> \" ' which currently the LKB does not allow.
>
> Could we move forward with the """ option, nicely documented by Michael
> here:
>
> http://moin.delph-in.net/TdlRfc
>
>  DocString    := /"""([^"\\]|\\.|"[^"]|""[^"])*"""/ Spacing
>
> I would go for one doc-string per type and doc strings in addendums
> concatenating with the origins.
>
> Could we try to reach consensus as soon as possible?   I do not want
> it to drift away again, as it has so many times in the past, ...
>
>
> --
> Francis Bond <http://www3.ntu.edu.sg/home/fcbond/>
> Division of Linguistics and Multilingual Studies
> Nanyang Technological University
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.delph-in.net/archives/developers/attachments/20180804/fe163af5/attachment.html>