Commit 7c7178dd authored by SVN-Git Migration's avatar SVN-Git Migration

Imported Upstream version 2.18.1+ds1

parent 8b131940
This diff is collapsed.
INSTALL for Frescobaldi 2.0.
============================
INSTALL for Frescobaldi 2
=========================
You can run Frescobaldi without installing. Just unpack and then run:
python frescobaldi
python frescobaldi
The Frescobaldi package is based on distutils. No build process is needed as
Frescobaldi is fully written in the interpreted Python language. To install in
the default location:
sudo python setup.py install
sudo python setup.py install
To run Frescobaldi, then simply type
frescobaldi
frescobaldi
If you want to install into /usr instead of /usr/local:
python setup.py install --prefix=/usr
python setup.py install --prefix=/usr
If you have a Debian-based system such as Ubuntu, and you get the error
message "ImportError: No module named frescobaldi_app.main", try:
python setup.py install --install-layout=deb
python setup.py install --install-layout=deb
See the distutils documentation for more install options.
NOTE: Since 2.18, Frescobaldi depends on the python-ly module, which needs to
be installed separately (see below). Previously, this Python module
(named 'ly') was part of Frescobaldi. When installing Frescobaldi, be
sure that old remnants of previous Frescobaldi installations are removed,
otherwise Frescobaldi will use the old 'ly' module instead, resulting in
various error messages.
Dependencies:
=============
Dependencies
============
Frescobaldi 2.0 is written in Python version 2.7 (3.x support is planned)
Frescobaldi 2 is written in Python (Python 2.7 and Python 3.2+ are supported)
and depends on Qt4.7 and PyQt4.8, and uses the python-poppler-qt4 binding to
Poppler for the built-in PDF preview.
For MIDI the PortMidi library is used, either via importing 'pypm',
'pyportmidi._pyportmidi, or, if that is not available, loading the pygame.pypm
'pyportmidi._pyportmidi', or, if that is not available, loading the pygame.pypm
module from pygame; or, as a last resort, embedding the PortMidi C-library via
ctypes. MIDI is optional.
Required:
Python 2.7
Python (2.7 or >= 3.2):
http://www.python.org/
Qt4 (>= 4.7):
http://qt.nokia.com/
PyQt4 (>= 4.8.3):
http://www.riverbankcomputing.co.uk/software/pyqt/
python-ly (>= 0.9):
https://pypi.python.org/pypi/python-ly
Poppler:
http://poppler.freedesktop.org/
python-poppler-qt4:
https://github.com/wbsoft/python-poppler-qt4
Optional:
Optional but recommended:
PortMidi:
http://portmedia.sourceforge.net/portmidi/
Of course you'll need to install one or more versions of LilyPond!
Suggested:
LilyPond:
http://www.lilypond.org/
Python 3.2 (or higher) is recommended above Python 2.7, but Python 2.7 will
continue to be supported during the full Frescobaldi 2 lifecycle.
Of course, PyQt4, python-poppler-qt4, python-ly, and pypm or pyportmidi need
to be installed for the same Python version as Frescobaldi itself.
"Freeze" installer:
===================
LilyPond is not a dependency of Frescobaldi, but of course you'll need to
install one or more versions of LilyPond to make sensible use of Frescobaldi!
"Freeze" installer
==================
The freeze.py script can create a self-contained Windows-installer, bundling all
of Python, PyQt4, popplerqt4 and pypm (from pygame) when used on MS Windows.
To use the script you need cx_Freeze and Inno Setup.
Mac OS X application bundle:
============================
Mac OS X application bundle
===========================
The macosx/mac-app.py script can build an application bundle on Mac OS X.
To see the usage notes, run:
python macosx/mac-app.py -h
python macosx/mac-app.py -h
The application bundle will be created inside a 'dist' folder in the current
working directory.
......@@ -94,8 +109,12 @@ The script assumes a specific system configuration (for details run the script
with the '-h' option), but can be easily adapted to other configurations.
For Linux distribution packagers:
=================================
For Linux distribution packagers
================================
See the secion Dependencies for the dependencies that need to be installed.
Be sure that all python packages belong to the same Python version Frescobaldi
uses.
Frescobaldi contains some files by default which are also available in other
packages often used in Linux distributions. It is possible to remove those
......@@ -107,19 +126,9 @@ Icons:
You can remove the frescobaldi_app/icons/Tango directory, and make Frescobaldi
depend on the tango-icon-theme package instead.
Hyphentation dictionaries:
Hyphenation dictionaries:
You can remove the hyph_*.dic files from frescobaldi_app/hyphdicts, and make
Frescobaldi depend on a package that installs hyphenation dictionaries in
/usr/share/hyphen/ (or another dictionary listed by default in frescobaldi_app/
hyphendialog.py).
The ly module:
==============
Frescobaldi provides a Python module (ly) that can be installed separately,
without requiring the rest of Frescobaldi. This can be done using the setup.py
script in the python-ly directory. This folder also contains the command line
tool "ly" that makes the functionality of the ly module accessible via the
command line.
......@@ -3,7 +3,6 @@ include frescobaldi.desktop
include frescobaldi.1
include frescobaldi.png
include *.py
include frescobaldi-wininst.bmp
recursive-include frescobaldi_app README*
recursive-include frescobaldi_app *.png *.svg *.ico index.theme
recursive-include frescobaldi_app *.ly *.ily Makefile
......@@ -12,4 +11,5 @@ recursive-include frescobaldi_app *.dic
recursive-include frescobaldi_app *.js
recursive-include frescobaldi_app *.md
recursive-include macosx *.svg *.icns *.py *.strings *.sh *.png *.json *.diff
recursive-include windows *.bmp *.py
global-exclude *~
......@@ -6,7 +6,7 @@ Qt4 for its user interface, via the PyQt4 bindings.
All code and application data is in the frescobaldi_app/ directory. The
frescobaldi script just imports frescobaldi_app.main. You can simply run
./frescobaldi from the commandline after unpacking Frescobaldi.
./frescobaldi from the command line after unpacking Frescobaldi.
You can also install the 'frescobaldi_app' package in the system- or user-wide
python directories and the frescobaldi script in your PATH. The distutils-based
......@@ -27,12 +27,14 @@ without arguments, or by using Dreampie or IPython) and then enter:
from frescobaldi_app.debug import *
This ensures the application starts up and uses the correct SIP api (2) for
This ensures the application starts up and uses the correct SIP API (2) for
QString and QVariant. This will also install some handlers that print
debugging information on certain events. And it imports the most used modules.
Currently Python 2.6 and 2.7 are supported, but the code should be designed such
that Frescobaldi works as well with Python 3.
Currently Python 2.7 and Python 3.2 and newer are supported. Supporting both
Python 2 and Python 3 requires certain care, so please test your changes with
both, especially if your code involves string encoding/decoding and file
operations.
How Frescobaldi is organized
......@@ -48,7 +50,7 @@ add features to Documents, MainWindows etc. Instead of clobbering those basic
classes with an ever-growing number of unrelated groups of methods, a different
approach is chosen: the plugin module.
This keeps all classes small and only have methods that direcly apply to
This keeps all classes small and only have methods that directly apply to
themselves and not to other parts of Frescobaldi (separation of concerns).
So e.g. the resultfiles, highlighter or documentinfo modules contain classes
......@@ -75,7 +77,6 @@ view: View (QPlainTextEdit)
menu: Here the menubar is constructed (by importing all the relevant
modules and adding the actions they define)
plugin: A simple way to extend objects without them knowing it
ly: LilyPond and the LY file format, tokenizer for LY and related
metainfo: Stores (optionally) meta information about the document, such
as last cursor position, whether to enable auto indent, etc
panel: The base class of all dock widgets
......@@ -136,6 +137,22 @@ package. The different groups separated by a blank line:
from . import widget # imports from current package
Avoid platform specific code, but when it is really needed, you can test
for Windows:
if sys.platform.startswith('win'):
...
or:
if os.name == "nt":
...
Testing for Mac OS X can be done using:
if sys.platform.startswith('darwin'):
...
Adding Functionality
====================
......@@ -153,7 +170,7 @@ without needing to have logic for accessing the preferences, constructing a
particular GUI, etc. It could, like app and many other modules, be used almost
unchanged in any other application.
New features that add menu actions can be imported in meny.py, while building
New features that add menu actions can be imported in menu.py, while building
the menu. Features that should run in a global background thread can have their
toplevel file (<feature>/__init__.py) imported from main.py or mainwindow.py,
loading as few as possible on first import.
......@@ -186,8 +203,8 @@ Guidelines for writing GUI texts
* Write short, directly and non-technical
* For help pages: each paragraph is one translatable string
* Avoid HTML in texts (but <code>\include</code> is ok)
* In help pages you can construct html using some helper functions
* Avoid HTML in texts (but <code>\include</code> is OK)
* In help pages you can construct HTML using some helper functions
* Avoid hard line breaks (<br>) in any texts: use short paragraphs instead
* Use named format fields: not "page {0} of {1}" but "page {num} of {total}"
* Don't change existing strings just for cosmetics, it breaks translations
......@@ -198,8 +215,8 @@ Testing and developing under Windows
Linux is the recommended developing platform, but it might be necessary to test
specific functionality or behaviour under Windows. It can be difficult to get
all the dependencies right, especially the right combi of poppler, pyqt4 and
sip.
all the dependencies right, especially the right combination of poppler, pyqt4
and sip.
There is an easy way to get setup under Windows and be able to do quite a lot
of testing and development, you don't even need to install Python at all.
......
README for Frescobaldi 2
========================
Homepage: http://www.frescobaldi.org/
Homepage: http://www.frescobaldi.org/
Main author: Wilbert Berendsen
Frescobaldi is a LilyPond sheet music text editor. It aims to be powerful, yet
......@@ -20,10 +20,11 @@ Features:
- Built-in LilyPond documentation browser and built-in help
- Configurable document outline view to navigate large LilyPond scores easily
- Smart layout-control functions like coloring specific objects in the PDF
- MusicXML import
- Modern user iterface with configurable colors, fonts and keyboard shortcuts
- Import ABC, Midi and MusicXML using the LilyPond-provided tools
- Experimental export to MusicXML
- Modern user interface with configurable colors, fonts and keyboard shortcuts
- Translated into: Dutch, English, French, German, Italian, Czech, Russian,
Spanish, Galician, Turkish, Polish, Brazillian and Ukrainian.
Spanish, Galician, Turkish, Polish, Brazilian and Ukrainian.
Music functions:
......@@ -42,8 +43,8 @@ composer of keyboard music in the late Renaissance and early Baroque period.
Here is an idea of the basic Frescobaldi workflow:
- Start Frescobaldi
- Open a .ly file or create one using File->New from template or Tools->Setup
new Score... and fill in some music
- Open a .ly file or create one using *File->New* from template or
*Tools->Setup new Score...* and fill in some music
- Press Ctrl+M to run LilyPond
- If the LilyPond output shows errors, press Ctrl+E to jump to the first error
- If you see other mistakes in the music, click the notes to move the text
......
......@@ -75,9 +75,6 @@ get it's own branch "v2"
Other ideas/wishes
==================
- continuous autocompile (run LilyPond whenever deemed suitable)
stub: engrave/autocompile.py
- support for Git/Hg/Svn diff/revert/commit
- play from cursor: plays music to MIDI output
......@@ -85,10 +82,14 @@ Other ideas/wishes
- editor:
* context menu (with help, open filename, etc)
* if matching brace out of view, popup a small display of it (idea:
Franciso Vila)
Francisco Vila)
* vi-mode (stub: vimode/)
- define and extend api for script snippets
- define and extend API for script snippets
- make Frescobaldi API (using pydoc) browsable via the helpbrowser.
- \displayMusic tool to show music in Scheme format (by calling LilyPond's
\displayMusic function on a music expression).
- make Frescobaldi api (using pydoc) browsable via the helpbrowser.
#! python
"""
This script generates HTML pages from the built-in Frescobaldi manual,
for publication on the Frescobaldi web site.
Simply run this from the toplevel frescobaldi directory:
python export-help.py
It creates a help/ directory (by default) and puts the HTML and images there.
"""
from __future__ import unicode_literals
import os
import re
import glob
import time
import shutil
### set output directory here:
output_dir = os.path.abspath('help')
### languages to export help pages for:
export_languages = 'C nl es fr it cs'.split()
### HTML templates for every page to be generated:
templates = {
'C': """\
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>{page_title} - Frescobaldi Project</title>
<link rel="stylesheet" type="text/css" href="/style/1/style.css" />
<link rel="shortcut icon" type="image/png" href="/favicon.png" />
<meta http-equiv="Content-Type" content="application/xhtml+xml;charset=utf-8" />
<meta name="author" content="Wilbert Berendsen" />
<meta name="description" content="Frescobaldi is a LilyPond sheet music editor" />
<meta name="keywords" content="lilypond, music notation, ide" />
</head>
<body>
<div id="header">
<h1>{page_title}</h1>
</div>
<div id="sidebar">
<a accesskey="h" href="/"><u>H</u>ome</a>
<a accesskey="s" href="screenshots"><u>S</u>creenshots</a>
<a accesskey="d" href="download"><u>D</u>ownload</a>
<a accesskey="u" href="uguide" class="selected"><u>U</u>ser Guide</a>
<a accesskey="v" href="development">De<u>v</u>elopment</a>
<a accesskey="l" href="links"><u>L</u>inks</a>
</div>
<div id="maincontents">
<p>(<a href="uguide-1">Frescobaldi 1.x User Guide</a>)</p>
{page_contents}
<address>
{page_address}
</address>
</div>
</body>
</html>
""",
"nl": """\
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="nl" xml:lang="nl">
<head>
<title>{page_title} - Frescobaldi Project</title>
<link rel="stylesheet" type="text/css" href="/style/1/style.css" />
<link rel="shortcut icon" type="image/png" href="/favicon.png" />
<meta http-equiv="Content-Type" content="application/xhtml+xml;charset=utf-8" />
<meta name="author" content="Wilbert Berendsen" />
<meta name="description" content="Frescobaldi is een LilyPond muziek-editor" />
<meta name="keywords" content="lilypond, music notation, ide" />
</head>
<body>
<div id="header">
<h1>{page_title}</h1>
</div>
<div id="sidebar">
<a accesskey="h" href="/"><u>H</u>ome</a>
<a accesskey="s" href="screenshots"><u>S</u>chermafbeeldingen</a>
<a accesskey="d" href="download"><u>D</u>ownloaden</a>
<a accesskey="u" href="uguide" class="selected">Gebr<u>u</u>ikershandleiding</a>
<a accesskey="o" href="development"><u>O</u>ntwikkeling</a>
<a accesskey="l" href="links"><u>L</u>inks</a>
</div>
<div id="maincontents">
<p>(<a href="uguide-1">Frescobaldi 1.x User Guide</a>)</p>
{page_contents}
<address>
{page_address}
</address>
</div>
</body>
</html>
""",
}
import sip
sip.setapi("QString", 2)
sip.setapi("QVariant", 2)
# make directory
if not os.path.isdir(output_dir):
os.makedirs(output_dir)
# copy images
images = []
images_dir = os.path.join(output_dir, 'images')
images_prefix = 'uguide_'
if not os.path.isdir(images_dir):
os.makedirs(images_dir)
for img in glob.glob('frescobaldi_app/help/*.png'):
name = os.path.basename(img)
images.append(name)
shutil.copy(img, os.path.join(images_dir, images_prefix + name))
# regexp to adjust links to images in html
images_re = re.compile(
r'''([Ss][Rr][Cc]\s*=\s*'''
r'''['"])((?:''' + '|'.join(map(re.escape, images)) + r''')['"])''')
# avoid reading settings
os.environ["XDG_CONFIG_HOME"] = ""
# make frescobaldi_app accessible
import frescobaldi_app.toplevel
import po
import help.helpimpl
import help.contents
import language_names
po.install(None)
# create a MainWindow because of the keyboard shortcuts!
import mainwindow
w = mainwindow.MainWindow()
def set_language(lang):
"""Sets the language. If "C", all text is untranslated."""
po.install(None if lang == "C" else po.find(lang))
def make_filename(name, lang):
"""Adds the language name to the filename (which must have an extension)."""
if lang not in ("C", None):
name = name.replace('.', '.' + lang + '.')
return name
def make_page(lang):
"""Makes the HTML user guide for the given language."""
html = []
seen = set()
def add(page, children=None, level=1):
seen.add(page)
html.append(
'<h{1} id="help_{0}"><a name="help_{0}"></a>{2}</h{1}>\n'
.format(page.name, min(5, level+1), page.title()))
html.append(help.helpimpl.markexternal(page.body()))
if page.seealso():
html.append('<p>')
html.append(_("See also:") + " ")
html.append(', '.join(p.link() for p in page.seealso()))
html.append('</p>\n')
for p in children or page.children():
add(p, None, level+1)
set_language(lang)
page = help.contents.contents
# toc at start
children = list(page.children())
children.insert(0, children.pop())
add(page, children)
left = [page for page in help.helpimpl.all_pages.values()
if page not in seen and page.name not in ('nohelp', 'page')]
# add pages not in the toc structure
if left:
html.append('\n\n<hr />\n\n')
for page in left:
add(page, None, 2)
html = ''.join(html)
# make image links work
html = images_re.sub(
lambda m: m.group(1) + 'images/' + images_prefix + m.group(2), html)
# make help links work
html = html.replace('<a href="help:', '<a href="#help_')
others = []
for l in export_languages:
if l is not lang:
others.append('<a href="{0}">{1}</a>'.format(
make_filename('uguide.html', l),
"English" if l == "C" else language_names.languageName(l, l),
))
footer = ', '.join(others)
footer += ' | '
footer += _("Last Modified: {date}").format(date=time.strftime('%d %b %Y'))
html = templates.get(lang, templates['C']).format(
page_title = _("Frescobaldi Manual"),
page_contents = html,
page_address = footer)
filename = os.path.join(output_dir, make_filename('uguide.html', lang))
print 'Exporting to:', filename
with open(filename, 'w') as f:
f.write(html.encode('utf-8'))
for lang in export_languages:
make_page(lang)
#!/usr/bin/python
#!/usr/bin/env python
import sys
from frescobaldi_app import toplevel
......
......@@ -18,6 +18,9 @@ LilyPond files to open, may also be textedit URLs
.B \-v, \-\-version
Show version information
.TP
.B \-V, \-\-version\-debug
Show version information of all supporting modules
.TP
.B \-h, \-\-help
Show help about options and exit
.TP
......
......@@ -30,10 +30,10 @@ from PyQt4.QtGui import (
QVBoxLayout, QWidget)
import app
import info
import appinfo
import icons
import helpers
imp