Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
LilyPond-aware LaTeXTools for music scholarship typesetting in Sublime Text 2 & 3.
Python JavaScript Shell

This branch is 37 commits ahead, 92 commits behind SublimeText:master

Failed to load latest commit information.
evince Support backward search for file names with non-ascii chars
messages README fixes
skim Toggle sync PDF support for Mac
.gitignore Ignore irrelevant files
.no-sublime-package Readd .no-sublime-package file for Package Control 2
Beamer boxes.sublime-snippet Add back snippets for beamer boxes and frames
Beamer frame.sublime-snippet Add back snippets for beamer boxes and frames
Beamer.sublime-completions Added snippets for creating a figure and for a table, as well as comp…
Default (Linux).sublime-keymap Merge branch 'Westacular-autocomplete'
Default (Linux).sublime-keymap.OLD NEW-STYLE KEYBINDINGS.
Default (OSX).sublime-keymap Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
Default (OSX).sublime-keymap.OLD Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
Default (Windows).sublime-keymap Merge branch 'Westacular-autocomplete'
Default (Windows).sublime-keymap.OLD NEW-STYLE KEYBINDINGS.
LaTeX math.sublime-completions Improve amsmath equation completions
LaTeX.sublime-build Fix quotation marks in build engine command. Also fix SyncTeX as a re…
LaTeX.sublime-build.OLD Initial transition to invoking make_pdf via build system, with config
LaTeX.sublime-commands Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
LaTeX.sublime-completions Improve amsmath equation completions
LaTeXTools Preferences.sublime-settings Update wording for Preferences file to accommodate ST3
LyTeX.JSON-tmLanguage Rationalize scope names. Enable LaTeXTools expansions to work in LyTe…
LyTeX.tmLanguage Rationalize scope names. Enable LaTeXTools expansions to work in LyTe…
LyTeXTools.sublime-completions Rationalize scope names. Enable LaTeXTools expansions to work in LyTe…
Main.sublime-menu Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
README.markdown Rebase on dev branch.
Symbol List - Labels.tmPreferences Initial support for 'Goto Anything'
Symbol List - Sections.tmPreferences fixing the regexp that captures \sections
Text boldface.sublime-snippet Improve bf/emph/ul snippets if ivoked with key combo and no selection
Text emphasize.sublime-snippet Improve bf/emph/ul snippets if ivoked with key combo and no selection
Text monospace.sublime-snippet add support for \texttt{} snippet
Text underline.sublime-snippet Improve bf/emph/ul snippets if ivoked with key combo and no selection
Wrap in LyTeXTools delimiters.sublime-snippet Rationalize scope names. Enable LaTeXTools expansions to work in LyTe…
Wrap in command.sublime-snippet Rationalize scope names. Enable LaTeXTools expansions to work in LyTe…
Wrap in environment.sublime-snippet Improve bf/emph/ul snippets if ivoked with key combo and no selection
begin_lilypond.sublime-snippet Fixed snippet typo.
delete_temp_files.py Verify that delete_temp_files works.
figure.sublime-snippet Added snippets for creating a figure and for a table, as well as comp…
getTeXRoot.py Use codecs.open to read text in get_tex_root and makePDF
jumpFromPDF.py Fix UTF-8 decoding issues.
jumpToPDF.py Filename encoding fix.
jump_aux.py Demand that source files be encoded in UTF-8 (bug fix).
latexCommand.py Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
latexEnvCloser.py Better detection of ST2 and ST3
latexEnvironment.py Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
latex_cite_completions.py Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
latex_ref_cite_completions.py Fix long/float param passing issue in ST2 (ref/cite)
latex_ref_completions.py Replace 'LaTeXTools' with 'LyTeXTools' in error messages and package …
latexcmd.sh Fix trap in Bash script.
lilypondfile.sublime-snippet Rationalize scope names. Enable LaTeXTools expansions to work in LyTe…
lytexcmd.sh Fix trap in Bash script (2).
makePDF.py Rebase on dev branch.
messages.json README fixes
parseTeXlog.py Merge log parsing issue reporting from 'master' into 'st3'
polltexmk.sh Refactor completion detection.
sublsync Merged with latest upstream commit.
table.sublime-snippet Fixed table snippet, label is tab: for tables, not fig:
texMacro.py Initial commit
texSections.py Better detection of ST2 and ST3
toggle_auto.py Better detection of ST2 and ST3
toggle_focus.py Better detection of ST2 and ST3
toggle_fwdsync.py Better detection of ST2 and ST3
toggle_show.py Separate prefs and toggles for auto ref and auto cite
viewPDF.py Merge branch 'refs/heads/master' into lytextools-tmux-pdflatex-st3 ("…

README.markdown

LyTeXTools: LilyPond-aware LaTeXTools for Sublime Text 2 & 3

by Yannis Rammos

This package adds lilypond-book support to Marciano Siniscalchi’s LaTeXTools for Sublime Text 2 and Sublime Text 3.

A component of GNU LilyPond, the formidable music typesetter, lilypond-book enables LaTeX writers to include LilyPond code snippets within LaTeX documents, thereby freely mixing text with musical notation. It is a command-line preprocessor that “extracts snippets of music from your document, runs LilyPond on them, and outputs the document with pictures substituted for the music.”

Overall, LyTeXTools extends LaTeXTools in the following ways:

  • It accepts .lytex (LaTeX with inline LilyPond) in addition to .tex (plain LaTeX) source files.
  • It instructs lilypond-book to preprocess the current document, if needed, and to produce a .tex file prior to invoking latexmk.
  • It extends the SyncTeX functionality of LaTeXTools, with seamless “forward” and “inverse” search capabilities regardless of the source file extension (.tex or .lytex). Unfortunately, as lilypond-book provides no native support for SyncTeX, this functionality would be best described as a hack and relies on a bash script for OS X (see below). Users are warmly invited to contribute a port of this short and straightforward script to Windows.

LaTeXTools and LyTeXTools behave identically when invoked with plain .tex files.

Installing LyTeXTools (OSX-only)

To avoid confusion, and given its lack of support for Windows at present, LyTeXTools has not been submitted to Will Bond’s Package Control. You may install the package manually by cloning (or copying the unzipped contents of) this repository into your ./Packages folder:

git clone https://github.com/yrammos/LyTeXTools.git
  • Please note that the stable version of LyTeXTools is in the lytextools branch, not the master branch! Run git checkout lilypond2latexmk after cloning to ensure that you are on that branch.

New users unfamiliar with Marciano Siniscalchi’s LaTeXTools are advised to read his detailed and lucid documentation first. The following notes only address areas where the two packages diverge.

It is best to uninstall the original LaTeXTools package before installing LyTeXTools, or you may confront build engine conflicts.

Setting up LyTeXTools

The following settings override those of the original LaTeXTools. All other LaTeXTools settings still apply to LyTeXTools.

Jumping from/to PDF (SyncTeX)

“Forward” and “inverse” search with .lytex files are non-trivial because SyncTeX only provides a mapping between the PDF and the LilyPond-generated .tex, whereas the original source file is the .lytex. LyTeXTools undertakes the missing link, namely a bidirectional mapping between .tex and .lytex line numbers.

Inverse search from the PDF (Skim.app) to the .lytex or .tex source is provided by the sublsync script, a central component of this package. Its purpose is to store the SyncTeX-generated coordinates (source file name, line number) into a file whence LyTeXTools can then retrieve them.

By default, LyTeXTools expects this file to be ~/.sublatex.txt. This location may be overriden via a synctex_output key-value pair in a LyTeXTools.sublime-settings JSON file, for example:

{
    "synctex_output":   "~/path/file.extension"
}

Please ensure you have adequate write privileges in that path.

But enough with theory and preliminaries. To actually set up your SyncTeX-enabled PDF viewer (which I presume is Skim.app):

  1. Go to Skim > Preferences > Sync.
  2. Under "Preset" select "Custom."
  3. Deselect the "Check for file changes" box.
  4. In the Command field enter <full_path_to_LyTeXTools_Package>/sublsync.
  5. In the Arguments field enter ~/.sublatex.txt "%file" %line "/usr/local/bin/".
    Replace:
    a. Optionally, the ~/.sublatex.txt default with whatever setting you have overriden it with (per instructions above).
    b. "/usr/local/bin/" with the full path to the directory containing subl binary, which launches Sublime Text 2 from the command line. Remember to enclose the path in quotation marks if it includes spaces!

Path considerations

The process will likely fail unless a valid path to the lilypond-book binary is declared within the LaTeX.sublime-build file, for example:

"osx":  {
            ...
            "path" : "$PATH:/usr/texbin:/usr/local/bin:/Applications/LilyPond.app/Contents/Resources/bin/"
            ...
        }

Using LyTeXTools

Compiling LilyPond within your LaTeX project

LyTeXTools decides whether to invoke lilypond-book solely on the basis of the filename extension: .tex files are assumed to contain no LilyPond-content and are passed directly to latexmk, whereas .lytex files are preprocessed by lilypond-book prior to compilation by latexmk. Invoking lilypond-book on files with no LilyPond code has no side-effects, so you may want to use the .lytex extension on all your project files regardless of content and no longer worry about the issue.

LyTeXTools and multi-file typesetting projects

It is strongly recommended that you use the .lytex extension with the root file of your project, even if it does not contain any LilyPond code in itself: Doing so will instruct LyTeXTools to trigger lilypond-book on the entire project (as a lilypond-book “make” session of sorts), and therefore to preprocess any other .lytex files that you may have included in your project with \input statements, rendering a manual run of lilypond-book on each individual .lytex project file unnecessary.

Of course you will need to explicitly include this extension in the % !TEX root flags at the top of all your .tex. and .lytex project files:

% !TEX root = my_root_file_name.lytex

Likewise, \input statements should explicitly specify the .lytex extension, unless you really intend to include a LilyPond-free .tex file, in which case the extension is optional:

\input{Chapter1.lytex}

Inserting LilyPond code in your LaTeX project

LyTeXTools is transparent and works just like its original counterpart, LaTeXTools. Simply ensure that your LilyPond code blocks are wrapped with the LyTeXTools-specific % \openlytex and % \closelytex delimiters, as in the following example:

\documentclass[a4paper]{article}

\begin{document}

Documents for \verb+lilypond-book+ may freely mix music and text!
For example,

% \openlytex
\begin{lilypond}
\relative c' {
  c2 g'2 \times 2/3 { f8 e d } c'2
}
\end{lilypond}
% \closelytex

Larger examples can be put into a separate file, and introduced with
\verb+\lilypondfile+, as follows:

% \openlytex
\lilypondfile{example.ly}
% \closelytex

\end{document}

Failure to use these delimiters will break the Jump to/from PDF (SyncTeX) functionality! Please use the templates described in the following section to have the delimiters automatically inserted as you type.

Technical note: Why the delimiters are necessary

In order to accurately map .tex line numbers to .lytex line numbers and vice-versa, LyTeXTools must be able to unambiguously identify LilyPond scopes, both within the source (.lytex) file and within the LilyPond-generated .tex file.

LilyPond scopes in the .lytex file are trivial to identify:

\begin{lilypond}[...]
    ...
\end{lilypond}

The situation appears less straightforward on the .tex side. So far, I have been able to identify only two pairs of delimiters that may wrap the generated LilyPond code:

\begin{quote}
    ...
\end{quote}

and a rather bland pair of curly brackets:

{
    ...
}

It is obvious that neither pair can be unambiguously attributed to LilyPond. For this reason, I am replacing the error-prone heuristics of earlier LyTeXTools versions with the unambiguous delimiters % \openlytex and % \closelytex.

Code highlighting

LyTeXTools includes a "LilyPond Book" syntax definition. Any LilyPond code embedded within your .lytex source will be correctly identified and, provided that the SubLilyPond package is also installed, highlighted. To prevent duplicate installations of SubLilyPond, I decided against repackaging it within LyTeXTools. The most straightforward way to install SubLilyPond is via Package Control.

Snippets and autocompletions

LyTeXTools provides a number of templates (or, in Sublime Text 2 parlance, snippets and autcompletions) to facilitate the inclusion of LilyPond content within your .lytex document.

Wrap in LyTeXTools delimiters

Accessible via the command palette ⌘-⇧-P. Wraps the selected text within % \openlytex and % \closelytex delimiters. I have not assigned a tab trigger to this snippet but you may do so yourself by tweaking the file Wrap in LyTeXTools delimiters.sublime-snippet.

beginlilypond⇥

Available as tab trigger and via the command pallette ⌘-⇧-P. Expands to:

% \openlytex
\begin{lilypond}[...]
    ...
\end{lilypond}
% \closelytex

Press ⇥ to quickly move between the two fillable fields.

lilypondfile⇥

Available as tab trigger and via the command pallette ⌘-⇧-P. Expands to:

% \openlytex
\lilypondfile[...]{...}
% \closelytex

Press ⇥ to quickly move between the two fillable fields.

lilypond⇥

Tab trigger expanding to:

% \openlytex
\lilypond[...]{...}
% \closelytex

Press ⇥ to quickly move between the two fillable fields.

openlytex⇥

Tab trigger expanding to % \openlytex.

closelytex⇥

Tab trigger expanding to % \closelytex.

Error reporting

All output of the lilypond-book (pre-processing) stage is flushed to ./lilypond-book.log within the directory that LyTeXTools were invoked from. Building is aborted if any errors are encountered during this stage. Otherwise, all pre-processed content is passed on to LaTeX, with errors thereby handled by the log parser provided with the original LaTeXTools.

Version history

18 June 2014

  • FIXED: A bug that prevented LyTeXTools from detecting that compilation has been completed.

12 Jan 2014

  • NEW: Sublime Text 3 is now supported.
  • NEW: All the latest LaTeXTools features.
  • FIXED: Minor bugs.

1 Sep 2013

  • FIXED: A regression that prevented polltexmk.sh (a core LyTeXTools script) from running, possibly resulting in spurious build errors and a premature termination of the build engine.

29 May 2013

  • IMPROVED: Scope names are now rationalized, facilitating future development.
  • FIXED: A regression that caused LaTeXTools snippets and autocompletions to be unavailable in LyTeX documents.
  • FIXED: Other small issues.

8 April 2013

  • NEW: Added syntax definition for .lytex documents. Embedded LilyPond code will now be highlighted (depends on the SubLilyPond package).
  • FIXED: Snippet typo.

14 March 2013

  • NEW: Added snippets and autocompletions for LilyPond content within .lytex documents.
  • FIXED: Rare SyncTeX-related bug.

10 March 2013

  • NEW: LilyPond scopes are now expected to be manually wrapped within the % \openlytex and % \closelytex delimiters.
  • NEW: LilyPond-book output is now logged for reference in case of errors.
  • NEW: Merged the latest commit of LaTeXTools (#07335).
  • IMPROVED: Cleaned up SyncTeX-related code.
  • FIXED: SyncTeX functionality is now more robust (please contact me in case you encounter issues).

31 August 2012

  • FIXED: "Open PDF" command (by default bound to Shift-Command-B) now works with .lytex files.

30 July 2012

  • NEW: First release.

Copyright © 2012-3 by Yannis Rammos. This work is made available under the terms of the Creative Commons Attribution-NonCommercial 3.0 Unported (CC BY-NC 3.0) license, http://creativecommons.org/licenses/by-sa/3.0/.

Something went wrong with that request. Please try again.