Skip to content

Home

Jump to bottom Edit New page
Urs Liska edited this page Jul 5, 2014 · 8 revisions

One day this will become the intro page for the online reference of openlilylib. For now we use this page to display/shape the new directory structure.

I think that the current way we organize the directory structure in the library won't scale well. We already have too many top-level directories, and particularly it's often not clear at all where new snippets should be placed. So I think we should reconsider our structure. Specifically we should consider the perspective of the includable library: What would be a natural path to include a snippet in a document (or style sheet), not only how to find a snippet in the Github interface.

Discussion on the lilypond-user mailing list has turned out a few results: We will have a flat include structure and rely on metadata to provide tools to navigate and document the library.

The overall structure of the repository will be:

/includes
/library
  /oll
    - includable-files.ily
    /music-fonts
    /stylesheets
      - new structure to be discussed
    /templates
      - new structure to be discussed
/usage-examples
  - documentation-files.ly

/library should be added to LilyPond's include path so the subdirectories below can be \included from end-user LilyPond files, using the first subdirectory as a namespace.
/usage-examples contains documentation examples, exactly one .ly file corresponding to the .ily files below /library/oll.
/includes will contain files that are needed by any snippets in the library but shouldn't be exposed to end-user files.
It will be possible to add additional sub-repositories inside the /library folder, e.g. lalily

The includable files should consistently be renamed to use dashed-naming-patterns with the .ily extension.

One important issue before starting the actual reorganization is to reconsider the metadata structure. We agreed upon using the metadata to provide ways to navigate and search the library. This will have to be realized using a script that automatically generates documentation from the content of the directory structure. It is not decided yet whether this will be presented in this Wiki or on openlilylib.org. For this we should be clear about mandatory fields and a stricter set of allowed tags. Probably it's a good idea to assign a primary tag (= category) to each snippet and an arbitrary number of secondary tags (like alternative index entries).

The documentation generating script will create a Table Of Content with hierarchies derived from the tags. Additionally it will create a detail page for each item (snippet), making use of a) extended metadata (e.g. a full text description, information about version requirements etc.) and b) the example .ly file.

Another desired addition is a file that should be included from any examples file and that redefines the booktitlemarkup to display a consistent header which is populated by the metadata.

The stylesheets section will have to be created from scratch (and will be quite powerful if we manage to provide some actual content). The idea (mainly developed by Kieren MacMillan) is to provide a hierarchical directory structure with categories like style ("fancy", concrete-publisher, etc.) paper format, instrumentation with one .ily file at each leaf, so one can e.g. \include "stylesheets/henle/concert/piano.ily. The stylesheet will then include the appropriate partial style sheets and possibly add custom configurations to it. But for the end-user this would be transparent.

The templates section is a similar topic that should be discussed thoroughly (but not that urgently).

So the first thing we definitely need is a usable set of category tags and mandatory metadata fields.

PS:
Current directory structure:

  • custom-music-fonts
    • LilyJAZZ (not-working yet?)
    • smufl (at version 1.0!)
  • debugging-layout
    This is somewhat outdated and maybe conflicting with the Frescobaldi version (?)
    • some of the "layout control options"
    • original-breaks
      (belongs to editorial-tools IMO)
  • editorial-tools
    • auto-transpose
    • edition-engraver
    • git-commands
    • line-break-marks
    • merge-rests-engraver
  • (fried-library-to-be-sorted)
  • general-tools
    • includeHelper
    • lilypond-version-predicates
    • readComment
    • scheme-wrapper
  • input-shorthands
    • articulations-not-aligned-with-notes
    • easy-custom-dynamics
    • easy-octaves
    • fuzzy-scale
    • ignore-collisions
    • optional-chord
    • sizeContext
    • vertical-spacing
    • (late-evaluation-of-variables.ly)
  • meta
    This should not be part of the includable library
  • notation-snippets
    • adjust-horizontal-spacing
    • align-lyrics-on-vowels
    • aligning-first-lyric-syllables
    • alternating-time-signatures
    • blackmensural-notation
    • fill-line-evenly
    • guitar-string-bending
    • hairpin-with-text
    • interchangeable-metres
    • interval-brackets
    • lyric-syllable-magnetic-snap
    • manual-partcombine-for-vocal-parts
    • metricmod-function
    • overriding-stencils
    • scale-stencils
    • shaping-bezier-curves
  • scheme-lib
    (Is this intended to be included in end-user documents or only from inside snippets?)
  • simple-examples
    • using-tie-configuration-property.ly
  • specific-solutions
    • bracket-repeats
    • ismn
    • xelatex-markup-list
  • stylesheets
    Very little content so far
  • templates
    • SATB-choir-on-2-or-4-staves
    • adjustable-centered-stanzas
    • lalily
    • predefined-instruments
Add a custom footer

Table of Contents

Clone this wiki locally