Packages/modules (was: Extension management, first sketch)

[Urs Liska]

Am Montag, den 20.01.2020, 14:14 +0100 schrieb David Kastrup:
> Urs Liska <address@hidden> writes:
> 
> > Am Montag, den 20.01.2020, 10:27 +0100 schrieb Urs Liska:
> > > * A core extension library shipping with LilyPond will be
> > > initiated. 
> > >   Extensions that are considered core functionality (prime
> > > candidates:
> > >   edition-engraver, stylesheets) will eventually be moved here
> > > from
> > >   openLilyLib, additionally special functionality (e.g.
> > > gregorian.ly,
> > >   arabic.ly) may over time be moved there to expose the
> > > difference
> > >   between core functionality and use-case specific modules more 
> > >   clearly. These tools will then be called through `\loadModule`
> > >   instead of `\include`, which will be easy to handle with
> > >   convert-ly rules. Probably it would be a good idea to
> > > eventually 
> > >   expose *all* non-standard notation through explicit packages
> > >   and have that nicely describe in the LM. This too will not be
> > >   called openLilyLib.
> > 
> > Thinking about it I would go one step further:
> > 
> > Currently we have a /ly folder in the installation which contains
> > core
> > files like music-functions-init.ly on the one hand, and on the
> > other
> > hand optional files that users can \include for specific
> > functionality,
> > such as the ones I have given as examples above.
> > 
> > I think now that *all* the files that are not included
> > unconditionally
> > but only upon user request should be treated as packages. This will
> > make the code structure clearer, since there is a clear distinction
> > between the files LilyPond needs/uses for its startup (then *all*
> > files
> > in /ly) and optional files at the user's disposition.
> 
> Seconded.
> 
> Regarding \loadModule :  LaTeX has \documentclass for defining a
> document layout.  LilyPond does not have files dedicated to that
> purpose
> yet so that's something for later.

Yes, I think we can ignore that for now.
Everything a documentclass does I do with an initial include of the
infrastructure, and I think everybody else would do so as well. 

Conceptually I can see what a document class might be in notation, but
I don't see for what a separate construct would be necessary.

> 
> With regard to packages, LaTeX has \usepackage from user documents
> and
> the sort-of equivalent \RequirePackage from package code (not sure
> what
> the rationale for the difference is, there may be something related
> to
> when loading is allowed) and a counterpiece \ProvidePackage.

My impression is that - like with \newcommand, \renewcommand and
\providecommand they want to give control over the handling of
conflicts from already loaded packages.

> 
> Emacs has
>     require is a built-in function in ‘C source code’.
> 
>     (require FEATURE &optional FILENAME NOERROR)
> 
>       Probably introduced at or before Emacs version 15.
> 
>     If feature FEATURE is not loaded, load it from FILENAME.
>     If FEATURE is not a member of the list ‘features’, then the
> feature is
>     not loaded; so load the file FILENAME.
> 
>     If FILENAME is omitted, the printname of FEATURE is used as the
> file
>     name, and ‘load’ will try to load this name appended with the
> suffix
>     ‘.elc’, ‘.el’, or the system-dependent suffix for dynamic module
>     files, in that order.  The name without appended suffix will not
> be
>     used.  See ‘get-load-suffixes’ for the complete list of suffixes.
> 
>     The directories in ‘load-path’ are searched when trying to find
> the
>     file name.
> 
>     If the optional third argument NOERROR is non-nil, then return
> nil if
>     the file is not found instead of signaling an error.  Normally
> the
>     return value is FEATURE.
> 
>     The normal messages at start and end of loading FILENAME are
>     suppressed.
> 
>     [back]
> 
> and a matching
> 
>     provide is a built-in function in ‘C source code’.
> 
>     (provide FEATURE &optional SUBFEATURES)
> 
>       Probably introduced at or before Emacs version 15.
> 
>     Announce that FEATURE is a feature of the current Emacs.
>     The optional argument SUBFEATURES should be a list of symbols
> listing
>     particular subfeatures supported in this version of FEATURE.
> 

OK. The *current* behaviour of oll-core is:

* loaded packages and modules (let's for now keep the existing names)
  are accounted for in an alist.
* if the requested package/module is already loaded:
  * if options are passed, try setting them (overriding defaults
    and/or values set by an earlier loading)
    => This behaviour has to be discussed
  * of no options are passed simply continue
  * (exit)
* look up the file (according to some logic (separate discussion)
* if the file is found load the package/module
* otherwise issue a warning, suggesting follow-up errors might come

> And of course Guile has modules.  Do we already have a thought about
> how
> to relate to the module system?  

Yes, that's right! \loadModule is definitely a bad name.

In LilyPond there's a fundamental difference between \include and 
#(use-modules, which is not the case in oll-core. There "modules" are
essentially the same as packages, just used to organize packages in a
hierarchical fashion:

* scholarLY includes modules:
  * annotate
  * choice
  * staff-cancellation
  * ...
* snippets can be addressed like
  \loadModule oll-misc.layout.horizontal-spacing

Actually it would make transition smoother if we choose completely new
names for the functions.

So:
* I suggest not to discern between "use/load" and "require",
  just have one command that behaves like require.
* (caveat: handling of config options when given to a
  secondary call)
* Is the "\load" prefix the best choice?
  * \loadPackage
  * \usepackage
  * \use
  * \package
  ?
* Do we need a word for the (current) "module" at all?
  What about
  \use scholarly.annotate
  or
  \use \with { subs = annotate.choice } scholarly
  ?


> With regard to namespaces, there may be
> something to be said for requiring explicit export in the long run?
> 

Although I know this is important I don't feel comfortable having an
opinion about this type of issue.

Urs