Re: Packages/modules

[Urs Liska]

Am Mittwoch, den 22.01.2020, 11:06 +0100 schrieb David Kastrup:
> Urs Liska <address@hidden> writes:
> 
> > Am Dienstag, den 21.01.2020, 11:19 +0100 schrieb Urs Liska:
> > > > Ok.  One thing to think about is that we want package files to
> > > > be
> > > > contributed by "ordinary" users.  But something like
> > > > 
> > > > \exportSymbols transposeSequence,instrumentGroup,scratchMyBack
> > > > 
> > > > would be perfectly feasible syntactical sugar.
> > > > 
> > > 
> > > I'll be more verbose than probably necessary, just to make sure
> > > we're
> > > talking about the same thing.
> > > 
> > > ...
> > > 
> > > If I got you right then from my experience with openLilyLib and
> > > creating project environments (which basically are the same as
> > > packages), I would say:
> > > 
> > >  * I'm all for hiding names in packages by default and having to
> > >    explicitly expose/export the package's interface
> > >  
> > 
> > One more implication: If variables and functions have to be
> > explicitly
> > exported it will be easier for external tools (like Frescobaldi) to
> > add
> > proper support for extensions.
> > 
> > I assume that at one point Frescobaldi will
> > 
> >  * know about available (core and external) extensions
> >  * provide ways to "use" an extension (as part of the Score wizard
> > and
> >    locally)
> >  * at that point know about the options that can be passed to that
> >    package
> >  * provide autocompletion and highlighting for available symbols
> >    exported from extensions
> >  * provide actions to generate the code for getting and setting
> > package
> >    options
> > 
> > So when planning the syntax of that export it would be good to take
> > the
> > needs/interest of IDEs into account that will not work with the
> > result
> > as LilyPond does but that parse the package files themselves.
> 
> Maybe we should have single-command exports after all

You mean that a package has to export every function or variable
separately? I think that would be good wrt self-documentation.

Would it be possible to export some meta information too? e.g. the type
of a variable, the signature (including if it is a music-function etc.)
of a function? That would be good.
The options do something like that already in their current
implementation. The \registerOption is used as a guard against trying
\setOption with an unregistered option, but the concept can directly be
used for package documentation.

>  and have a
> (non-optional ?) documentation string to be used as mouse-over?  I
> think
> a unified approach to documentation might go a long way towards basic
> usability.

A non-optional docstring sounds nice. This itself doesn't guarantee
that the docstrings are actually *helpful*, but if e.g. Frescobaldi
provides direct access to them pressure would certainly mount to
improve them one by one.

Wilbert plans (I don't recall if he said so in a presentation or just
while chatting) to use his current rewriting of Frescobaldi's LilyPond
parser to provide such "introspection", through a mouse-over effect or
by extending the interface of the autocompletion dropdown. This will
*certainly* make it more straightforward to get used to LilyPond's
internals.

Urs

>