New: Install pre-built PDF + single/split HMTL docs. Separate devel docs. Added build script.

author: Tim E. Real <termtech@rogers.com> 2013-02-22 06:46:23 +0000
committer: Tim E. Real <termtech@rogers.com> 2013-02-22 06:46:23 +0000
commit: 48b9d2ea9961f935bacabc75a2fbd5cc141010ae (patch)
tree: 37512a1feed9d02145e0e52f0c96e5fe42a83f62
parent: 2d1fc0416a2d8611659a4f630fbc5719f35b694d (diff)
28 files changed, 986 insertions, 1533 deletions
diff --git a/muse2/CMakeLists.txt b/muse2/CMakeLists.txt
index 9317346f..71e56f04 100644
--- a/muse2/CMakeLists.txt
+++ b/muse2/CMakeLists.txt
@@ -24,7 +24,6 @@
 include(FindPkgConfig)
 include(CheckIncludeFile)
 include(cmake/Summary.cmake)
-include(cmake/TargetDoc.cmake)
 
 project(muse)
 CMAKE_MINIMUM_REQUIRED(VERSION 2.4.1)
@@ -179,12 +178,6 @@ include(${QT_USE_FILE})
 ##
 
 ##
-## find doxygen program
-##
-
-FIND_PROGRAM(DOXY doxygen)
-
-##
 ## find ladspa.h
 ##
 
@@ -459,7 +452,7 @@ set(CMAKE_CXX_FLAGS_DEBUG   "-g -DQT_DEBUG -fPIC ${CMAKE_CXX_FLAGS_DEBUG}")
 
 # NOTE: share/ directory needs to be at the end so that the translations
 #       are scanned before coming to share/locale
-subdirs(al awl grepmidi man plugins muse synti packaging utils demos share)
+subdirs(doc al awl grepmidi man plugins muse synti packaging utils demos share)
 
 ## Install doc files
 file (GLOB doc_files
@@ -495,10 +488,6 @@ add_custom_target(uninstall
 
 message("\n")
 
-if (${DOXY} STREQUAL "DOXY-NOTFOUND")
-      message("** ERROR: The program 'doxygen' is required, but was not found.")
-endif (${DOXY} STREQUAL "DOXY-NOTFOUND")
-  
 if (NOT ALSA_FOUND)
       message("** ERROR: alsa >= 0.9.0 is required, but development files were not found.")
 endif (NOT ALSA_FOUND)           
diff --git a/muse2/ChangeLog b/muse2/ChangeLog
index c1696aaa..04a81592 100644
--- a/muse2/ChangeLog
+++ b/muse2/ChangeLog
@@ -1,3 +1,12 @@
+22.02.2013:
+         * New: Install pre-built PDF + single/split HMTL docs. Separate devel docs. Added build script. (Tim)
+           Build script is /doc/build_docs.sh You'll want to use it or a variant to get the HTML .aux files.
+           Fixed table in my Appendix in tex file so it works with HTML.
+         - For now, I've changed F1 help to open PDF, if not found fallback to HTML.
+           I've #define MUSE_USE_PDF_HELP_FILE in help.cpp. Undefine for HTML only.
+           May at least need to keep track of viewer process (don't open copies), also try context-sensitive help.
+           Help opener always been LANG ready (looks for _xx) but this new build script is not 'automatic'.
+         - TODO: For some reason the generated HTML developer docs contain nonsense. (Unknown formatters?)
 21.02.2013:
          - Fixed: Multiple label warnings in the LaTeX doc. Reference and formatting fixes. (Orcan)
          - Improved: Table of contents and hyperrefs in te LaTeX doc. (Orcan)
diff --git a/muse2/README b/muse2/README
index a39a19b0..925e3381 100644
--- a/muse2/README
+++ b/muse2/README
@@ -20,9 +20,6 @@ details.
       Requirements:
   =============================
       
-      - doxygen
-          www.doxygen.org
-          
       - CMake >= 2.4 
           http:/www.cmake.org/HTML/Download.html
 
@@ -47,7 +44,12 @@ details.
          e2fsprogs package http://e2fsprogs.sourceforge.net/
          Some distros may include it in another package such as 'libuuid', or offer a choice.
 
+      - LADSPA (development file ladspa.h)
+         www.ladspa.org
+         
+  =============================
       Optional:
+  =============================
 
       - fluidsynth >= 1.0.3 (formerly known as iiwusynth) (development files) 
           http://sourceforge.net/apps/trac/fluidsynth/
@@ -66,10 +68,6 @@ details.
           Recently LADISH has been emulating it instead:         
           http://ladish.org/
       
-      - ConTeXt (for building documentation, by default the build
-               script tries to build documentation, can be
-               disabled by setting ENABLE_DOCUMENTATION to OFF)
-      
       - Python		The python scripting language
           http://www.python.org
           Python support is required for some experimental features.
diff --git a/muse2/doc/CMakeLists.txt b/muse2/doc/CMakeLists.txt
new file mode 100644
index 00000000..de90563e
--- /dev/null
+++ b/muse2/doc/CMakeLists.txt
@@ -0,0 +1,75 @@
+#=============================================================================
+#  MusE
+#  Linux Music Editor
+#  $Id:$
+#
+#  Copyright (C) 1999-2013 by Werner Schweer and others
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the
+#  Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+#=============================================================================
+
+install( FILES pdf/documentation.pdf pdf/developer_docs.pdf
+      DESTINATION ${MusE_DOC_DIR}/muse_pdf
+      )
+
+file (GLOB single_documentation_html_files
+      html/single/documentation/*.css
+      html/single/documentation/*.html
+      # html/single/documentation/*.jpg
+      html/single/documentation/*.png
+      # html/single/documentation/toc_.txt
+      )
+
+file (GLOB single_developer_docs_html_files
+      html/single/developer_docs/*.css
+      html/single/developer_docs/*.html
+      # html/single/developer_docs/*.jpg
+      html/single/developer_docs/*.png
+      # html/single/developer_docs/toc_.txt
+      )
+
+file (GLOB split_documentation_html_files
+      html/split/documentation/*.css
+      html/split/documentation/*.html
+      # html/split/documentation/*.jpg
+      html/split/documentation/*.png
+      # html/split/documentation/toc_.txt
+      )
+
+file (GLOB split_developer_docs_html_files
+      html/split/developer_docs/*.css
+      html/split/developer_docs/*.html
+      # html/split/developer_docs/*.jpg
+      html/split/developer_docs/*.png
+      # html/split/developer_docs/toc_.txt
+      )
+
+install( FILES ${single_documentation_html_files}
+      DESTINATION ${MusE_DOC_DIR}/muse_html/single/documentation
+      )
+
+install( FILES ${single_developer_docs_html_files}
+      DESTINATION ${MusE_DOC_DIR}/muse_html/single/developer_docs
+      )
+
+install( FILES ${split_documentation_html_files}
+      DESTINATION ${MusE_DOC_DIR}/muse_html/split/documentation
+      )
+
+install( FILES ${split_developer_docs_html_files}
+      DESTINATION ${MusE_DOC_DIR}/muse_html/split/developer_docs
+      )
+      
+\ No newline at end of file
diff --git a/muse2/doc/build_docs.sh b/muse2/doc/build_docs.sh
new file mode 100755
index 00000000..fe9fe231
--- /dev/null
+++ b/muse2/doc/build_docs.sh
@@ -0,0 +1,129 @@
+#!/bin/bash
+#=============================================================================
+#  MusE
+#  Linux Music Editor
+#  Copyright (C) 1999-2013 by Werner Schweer and others
+#
+#  build_docs.sh Copyright (C) 2013 Tim E. Real <terminator356 at users dot sourceforge dot net>
+#
+#  This program is free software; you can redistribute it and/or modify
+#  it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the
+#  Free Software Foundation, Inc.,
+#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+#=============================================================================
+
+#=============================================================
+#
+# Run this script to re-create the PDF and HTML documentation.
+# Usage: build_docs.sh [--help] [--no_post_clean]
+#
+#=============================================================
+
+if [ "$1" == "--help" ]; then
+        echo "Usage: build_docs.sh [--no_post_clean (don't clean up after build)]"
+        exit 1
+fi
+
+#
+# Pre clean
+#
+rm -rf pdf/*.*
+rm -rf html/single/documentation/*.*
+rm -rf html/single/developer_docs/*.*
+rm -rf html/split/documentation/*.*
+rm -rf html/split/developer_docs/*.*
+rm -rf tmp
+
+mkdir -p tmp/pdf/documentation
+mkdir -p tmp/pdf/developer_docs
+
+mkdir -p tmp/html/single/documentation
+mkdir -p tmp/html/single/developer_docs
+mkdir -p tmp/html/split/documentation
+mkdir -p tmp/html/split/developer_docs
+
+#
+# Run the PDF conversions first to get the *.aux files required for proper HTML links displaying
+# Run each conversion at least three times to resolve all references
+#
+# pdflatex -output-directory=pdf documentation.tex
+# pdflatex -output-directory=pdf documentation.tex
+# pdflatex -output-directory=pdf documentation.tex
+# 
+# pdflatex -output-directory=pdf developer_docs.tex
+# pdflatex -output-directory=pdf developer_docs.tex
+# pdflatex -output-directory=pdf developer_docs.tex
+
+pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/documentation documentation.tex
+pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/documentation documentation.tex
+pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/documentation documentation.tex
+
+pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/developer_docs developer_docs.tex
+pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/developer_docs developer_docs.tex
+pdflatex -interaction=batchmode -halt-on-error -file-line-error -output-directory=tmp/pdf/developer_docs developer_docs.tex
+
+#
+# Now run the HTML conversions
+#
+# latex2html -nonavigation -noaddress -noinfo -split 0 -external_file pdf/documentation -dir html/single/documentation documentation.tex
+# latex2html -nonavigation -noaddress -noinfo -split 0 -external_file pdf/developer_docs -dir html/single/developer_docs developer_docs.tex
+# latex2html -noaddress -noinfo -split 4 -external_file pdf/documentation -dir html/split/documentation documentation.tex
+# latex2html -noaddress -noinfo -split 4 -external_file pdf/developer_docs -dir html/split/developer_docs developer_docs.tex
+
+latex2html -nonavigation -noaddress -noinfo -split 0 -external_file tmp/pdf/documentation/documentation -mkdir -dir tmp/html/single/documentation documentation.tex
+latex2html -nonavigation -noaddress -noinfo -split 0 -external_file tmp/pdf/developer_docs/developer_docs -mkdir -dir tmp/html/single/developer_docs developer_docs.tex
+
+latex2html -noaddress -noinfo -split 4 -external_file tmp/pdf/documentation/documentation -mkdir -dir tmp/html/split/documentation documentation.tex
+latex2html -noaddress -noinfo -split 4 -external_file tmp/pdf/developer_docs/developer_docs -mkdir -dir tmp/html/split/developer_docs developer_docs.tex
+
+#
+# Move the files
+#
+mv -f tmp/pdf/documentation/*.pdf pdf
+mv -f tmp/pdf/developer_docs/*.pdf pdf
+
+mv -f tmp/html/single/documentation/*.css   html/single/documentation
+mv -f tmp/html/single/documentation/*.html  html/single/documentation
+# mv -f tmp/html/single/documentation/*.jpg   html/single/documentation
+mv -f tmp/html/single/documentation/*.png   html/single/documentation
+# mv -f tmp/html/single/documentation/toc_.txt html/single/documentation
+
+mv -f tmp/html/single/developer_docs/*.css   html/single/developer_docs
+mv -f tmp/html/single/developer_docs/*.html  html/single/developer_docs
+# mv -f tmp/html/single/developer_docs/*.jpg   html/single/developer_docs
+mv -f tmp/html/single/developer_docs/*.png   html/single/developer_docs
+# mv -f tmp/html/single/developer_docs/toc_.txt html/single/developer_docs
+
+mv -f tmp/html/split/documentation/*.css    html/split/documentation
+mv -f tmp/html/split/documentation/*.html   html/split/documentation
+# mv -f tmp/html/split/documentation/*.jpg    html/split/documentation
+mv -f tmp/html/split/documentation/*.png    html/split/documentation
+# mv -f tmp/html/split/documentation/toc_.txt html/split/documentation
+
+mv -f tmp/html/split/developer_docs/*.css    html/split/developer_docs
+mv -f tmp/html/split/developer_docs/*.html   html/split/developer_docs
+# mv -f tmp/html/split/developer_docs/*.jpg    html/split/developer_docs
+mv -f tmp/html/split/developer_docs/*.png    html/split/developer_docs
+# mv -f tmp/html/split/developer_docs/toc_.txt html/split/developer_docs
+
+#
+# Post clean
+#
+if [ "$1" != "--no_post_clean" ]; then
+# rm -f pdf/*.aux pdf/*.log pdf/*.out pdf/*.toc
+# rm -f html/single/documentation/*.aux html/single/documentation/*.log html/single/documentation/*.out html/single/documentation/*.pl html/single/documentation/*.tex html/single/documentation/WARNINGS
+# rm -f html/single/developer_docs/*.aux html/single/developer_docs/*.log html/single/developer_docs/*.out html/single/developer_docs/*.pl html/single/developer_docs/*.tex html/single/developer_docs/WARNINGS
+# rm -f html/split/documentation/*.aux html/split/documentation/*.log html/split/documentation/*.out html/split/documentation/*.pl html/split/documentation/*.tex html/split/documentation/WARNINGS
+# rm -f html/split/developer_docs/*.aux html/split/developer_docs/*.log html/split/developer_docs/*.out html/split/developer_docs/*.pl html/split/developer_docs/*.tex html/split/developer_docs/WARNINGS
+rm -rf tmp
+fi
diff --git a/muse2/doc/developer_docs.tex b/muse2/doc/developer_docs.tex
new file mode 100644
index 00000000..bc3cdc86
--- /dev/null
+++ b/muse2/doc/developer_docs.tex
@@ -0,0 +1,702 @@
+%% (c) 2012 florian jung
+%% (c) 2012 Robert Jonsson
+%% we should consider putting this under a proper license. GPL, or
+%% some GPL-like documentation license??
+
+%% rules for editing documentation: (READ THIS FIRST)
+%% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+%%
+%% please try to let newly written lines be shorter than 72 characters.
+%% minor exceptions are okay, but please not more than 80 chars.
+%% comments shall start after character #80 of the line (that is,
+%% they shall be "on the right margin")
+%%
+%% DON'T MIX up changes and reformatting in one commit. when changing
+%% stuff, please don't touch the lines before and after your change
+%% (that is, do not re-wrap them), even if it will look a bit patchy.
+%% this is for being able to easily use diff.
+%% when you want to reformat this file, then do it. but don't change
+%% anything, as this would be hard to find in a diff. and clearly
+%% state in the commit log that you "only" rearranged things.
+%%
+%% please adhere to the "User's manual" / "Internals" / "Design"
+%% partitioning (genereally, don't change the chapters until there
+%% is a really good reason for doing so (adding a chapter like
+%% "feature requests" as flo did in r1497 IS one).
+%% Below that, feel free to change the logical arrangement
+%% (making paragraphs to subsections and similar) if you deem it
+%% neccessary.
+%%
+%% Whenever referring to code symbols, constants or source/header
+%% files, please use \sym{someClass::someSymbol}, \usym{UPPERCASE_THING}
+%% or \f{file.cpp}.
+%% Only specify file paths or namespaces where it would be ambiguous
+%% otherwise. Specify 'someClass::' until it would disturb the reader
+%% and it is obvious. you have to replace '_' by {\_} (with the {}!).
+%% These macros do automatic hyphenation on Camel-Case, under_-score
+%% and scope::-operator boundaries. If you need to insert additional
+%% hyphenation points, use {\-}.
+%% Example: \sym{someClass::someAb{\-}nor{\-}mal{\-}lyLongName} will
+%%          hyphenate: some-Class::-some-Ab-nor-mal-ly-Long-Name
+%%
+%% Whenever referring to URLs, please wrap them in \url{blah}. Key
+%% combinations shall look like \key{CTRL+C}. Menu items shall look
+%% like \menu{Menu > Submenu > Menu Item}.
+%%
+%% Where possible, reference other parts of this documents with
+%% \label and \ref. Avoid duplicate information under "Internals" by
+%% referring to the appropriate section in "User's manual".
+%%
+%% Please do no time-stamping of sections. if you need time-stamps,
+%% use "svn blame documentation.tex"
+%%
+%% If you contribute something, feel free to add yourself to \author.
+%%
+%% If you don't speak LaTeX fluently, a few tips:
+%% * \section, \subsection, \subsubsection, \paragraph, \subparagraph
+%%   let you create sections etc. just copy-and-paste if unsure.
+%% * you must prefix special characters like the underscore with \
+%%   (backslash)
+%% * \emph{some text} emphasizes the text, printing it italic.
+%% * \texttt{some text} displays the text in a typewriter font
+%% * \label{someName} creates a label at this position. this doesn't
+%%   show up in the pdf. with \ref{someName}, you can reference to this
+%%   label. (LaTeX will insert the section number instead of \ref)
+%%   For this to work, you might need to recompile the .tex twice.
+%%
+%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%
+%% Dependencies:
+%% To produce pdf output from this document the following packages are
+%% needed (atleast under Ubuntu derivatives)
+%% latex???-base
+%% texlive-latex-recommended
+%% texlive-latex-extra
+%%
+%% To produce a pdf version of this manual type:
+%% pdflatex documentation.tex <enter>
+%% A file documentation.pdf should be generated.
+%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+
+\documentclass[a4paper]{report}
+\usepackage[a4paper,  left=2.5cm, right=2.5cm, top=2.5cm, bottom=2.5cm]{geometry}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{lmodern}
+\usepackage[english]{babel}
+\usepackage{graphicx}
+\usepackage{hyphenat}
+\usepackage{wrapfig}
+\usepackage{fancyhdr}
+\usepackage{hyperref}
+\usepackage{xcolor}
+\hypersetup{
+  linkcolor=blue,
+  urlcolor=blue,
+  colorlinks=true,         % hyperlinks will be blue
+  linkbordercolor=blue,     % hyperlink borders will be blue
+  %pdfborderstyle={/S/U/W 1} % border style will be underline of width 1pt
+}
+\pagestyle{fancy}
+        \lhead{\scriptsize{\slshape\leftmark}}
+        \chead{}
+        \rhead{\thepage}
+        \lfoot{}
+        \cfoot{}
+        \rfoot{}
+        \renewcommand{\headrulewidth}{0.4pt}
+\usepackage{ifthen}
+
+%% Borrowed from Lyx output. "Because html converters don't know
+%%  tabularnewline". Is required? Maybe replace with \\ ?
+\providecommand{\tabularnewline}{\\}
+
+% Hyphenate symbols before each uppercase letter, after each underscore
+% (without a "-") and after each ':' (without a "-")
+% TODO for any latex crack: also do automatic hyphenation, that is,
+% instead of some-Automation-Expression, do some-Au-to-ma-tion-Ex-press-ion
+\makeatletter
+\newcommand{\camelhyph}[1]{\@fterfirst\c@amelhyph#1\relax }
+\newcommand{\underscorehyph}[1]{\@fterfirst\u@nderscorehyph#1\relax }
+\def\@fterfirst #1#2{#2#1}
+\def\c@amelhyph #1{%
+\ifthenelse{\equal{#1}\relax}{}{%  Do nothing if the end has been reached
+  \ifnum`#1=95 \_\hspace{0pt}\else      %     Check whether #1 is "_", then print _[thin space]
+    \ifnum`#1=58 :\hspace{0pt}\else
+      \ifnum`#1>64
+        \ifnum`#1<91 \-#1\else#1\fi%     Check whether #1 is an uppercase letter,
+      \else#1\fi
+    \fi
+  \fi
+                            %     if so, print \-#1, otherwise #1
+  \expandafter\c@amelhyph%    %     insert \c@amelhyph again.
+}}
+\def\u@nderscorehyph #1{%
+\ifthenelse{\equal{#1}\relax}{}{%  Do nothing if the end has been reached
+  \ifnum`#1=95 \_\hspace{0pt}\else      %     Check whether #1 is "_", then print _\-
+    \ifnum`#1=58 :\hspace{0pt}\else#1\fi\fi
+  \expandafter\u@nderscorehyph%    %     insert \u@nderscorehyph again.
+}}
+\makeatother
+
+
+
+\author{Florian Jung, Robert Jonsson, Tim Donnelly}
+\title{MusE Documentation}
+
+% Orcan: not needed since the hyperref package takes care of all
+%\newcommand{\url}[1]{\texttt{#1}}
+\newcommand{\key}[1]{\textbf{#1}}
+\newcommand{\shell}[1]{\texttt{\textbf{#1}}}
+\newcommand{\menu}[1]{\textbf{#1}}
+\newcommand{\sym}[1]{\texttt{\camelhyph{#1}}}
+\newcommand{\listing}[1]{\texttt{\camelhyph{#1}}}
+\newcommand{\usym}[1]{\texttt{\underscorehyph{#1}}}
+\newcommand{\file}[1]{\texttt{\camelhyph{#1}}}
+\newcommand{\screenshotwidth}[0]{0.8\textwidth}
+
+\begin{document}
+\tableofcontents
+\chapter{Internals -- how it works}
+This chapter explains how MusE is built internally, and is meant
+to be an aid for developers wanting to quickly start up with MusE.
+For details on \emph{why} stuff is done please refer to the following
+chapter.
+
+\section{User interface programming}
+We use the QT Toolkit for GUI- and other programming. The \emph{QT-Assistant}
+is an important tool for getting help. Almost everything can be looked
+up there.
+
+GUIs can be either be hardcoded (see \file{arranger.cpp} for an example)
+or can be created using \emph{QT-Designer} (see the dialogs under
+\file{widgets/function_dialogs/} for mostly cleanly-written examples).
+Don't forget to add your \file{cpp}, \file{h} and \file{ui} files to the
+corresponding sections in the \file{CMakeLists.txt}!
+
+Additionally, MusE offers some custom widgets, like menu title items etc.
+Following, there will be a small, unordered list about custom widgets:
+\begin{itemize}
+\item \sym{MusEGui::MenuTitleItem}: Provides a title-bar in a \sym{QMenu}. \\
+      Usage: \listing{someMenu->addAction(new\ MusEGui::MenuTitleItem(tr("fnord"),\ someMenu));} \\
+      Defined in \file{widgets/menutitleitem.h}.
+\item \sym{MusEGui::PopupMenu}: Provides a \sym{QMenu}-like menu which
+      can stay open after the user checks a checkable action.\\
+      Usage: just create a \listing{new\ PopupMenu(\ true|false\ )} instead of
+             a \listing{new\ QMenu()}. (\listing{true} means 'stay open')\\
+      Defined in \file{widgets/popupmenu.h}.
+\end{itemize}
+
+
+\section{Configuration} \label{portconfig_sucks}
+Configuration is a bit pesky in MusE in its current state. If you get
+confused by reading this chapter, that's a sign of a sane mind.
+
+There are three kinds of configuration items:
+\begin{itemize}
+\item (1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings
+\item (2) Per-Song configuration, like whether to show or hide certain track types in the arranger
+\item (3) Something in between, like MIDI port settings etc. They obviously actually are
+      global configuration issues (or ought to be), but also obviously must be stored
+      in the song file for portability. (This problem could possibly be solved by
+      the feature proposal in \ref{symbolic_ports}.
+\end{itemize}
+
+\paragraph{Reading configuration}
+\sym{void\ MusECore::readConfiguration(Xml\&,\ bool,\ bool)} in
+\file{conf.cpp} is the central point
+of reading configuration. It is called when MusE is started first
+(by \sym{bool\ MusECore::readConfiguration()}), and also when a
+song is loaded. \\ %TODO: call paths!
+It can be instructed whether to read MIDI ports (3), global configuration
+and MIDI ports (1+3). Per-Song configuration is always read (2).
+
+When adding new configuration items and thus altering \sym{readConfiguration()},
+you must take care to place your item into the correct section. The code is
+divided into the following sections:
+\begin{itemize}
+\item Global and/or per-song configuration (3)
+\item Global configuration (1)
+\item Code for skipping obsolete entries
+\end{itemize}
+
+The sections are divided by comments (they contain \texttt{----}, so just
+search for them). Please do not just remove code for reading obsolete entries,
+but always add an appropriate entry to the 'skipping' section in order to
+prevent error messages when reading old configs.
+
+\paragraph{Writing configuration}
+Global configuration is written using the
+\sym{MusEGui::MusE::writeGlobalConfiguration()} functions, while
+per-song-config is written by \sym{MusEGui::MusE::writeConfiguration()}
+(notice the missing \sym{Global}; both implemented in \file{conf.cpp}).
+
+\sym{writeConfiguration} is actually just a subset of the code in
+\sym{writeGlobalConfiguration}. \textbf{Duplicate code!}                  % TODO fix that in the sourcecode.
+
+\paragraph{Song state}
+Additionally to per-song configuration, there is the song's state.
+This contains "the song", that is all tracks, parts and note events,
+together with information about the currently opened windows, their
+position, size, settings and so on. Adding new items here is actually
+pretty painless: Configuration is read and written using
+\sym{MusECore::Song::read} and \sym{::write}, both implemented in
+\file{songfile.cpp}. There are no caveats.
+
+\paragraph{How to add new items}
+When adding global configuration items, then add them into the second
+block ("global configuration") in \sym{readConfiguration} and into
+\sym{writeGlobalConfiguration}.
+
+When adding just-per-song items, better don't bother to touch the
+"configuration" code and just add it to the song's state (there might
+be rare exceptions).
+
+When adding global configuration items, make sure you add them into the
+correct section of \sym{readConfiguration}, and into \sym{writeGlobalConfiguration}.
+
+
+%TODO: how to write config,
+%TODO: song/global stuff
+%TODO: config lesen und schreiben fuer plugingroups
+
+
+\section{User controls and automation}
+\subsection{Handling user input}
+\subsubsection{Plugins and synthesizers}
+\paragraph{Overview}
+When the user launches a plugin's GUI, either a MusE-window with
+the relevant controls is shown, or the native GUI is launched. MusE
+will communicate with this native GUI through OSC (Open Sound Control).
+The relevant classes are \sym{PluginGui}, \sym{PluginIBase}
+(in \file{plugin.h}) and \sym{OscIF} (in \sym{osc.h}).
+
+If the user changes a GUI element, first the corresponding control is
+disabled, making MusE not steadily update it through automation
+while the user operates it. Then MusE will update the plugin's parameter
+value, and also record the new value. When appropriate, the controller
+is enabled again.
+
+\paragraph{Processing the input, recording}
+Upon operating a slider, \sym{PluginIBase::setParam} is called,
+which usually writes the control change into the ringbuffer
+\sym{PluginI::{\_}controlFifo}. (\sym{PluginI::apply()},
+\sym{DssiSynthIF::getData()} will read this ringbuffer and
+do the processing accordingly). Furthermore, \sym{AudioTrack::recordAutomation}
+is called, which either directly modifies the controller lists or writes
+the change into a "to be recorded"-list (\sym{AudioTrack::{\_}recEvents})
+(depending on whether the song is stopped or played).
+
+The \sym{AudioTrack::{\_}recEvents} list consists of \sym{CtrlRecVal}
+items (see \file{ctrl.h}), which hold the following data:
+\begin{itemize}
+\item the frame where the change occurred
+\item the value
+\item the type, which can be \usym{ARVT{\_}START}, \usym{ARVT{\_}VAL} or \usym{ARVT{\_}STOP}.
+      \usym{ARVT{\_}VAL} are written by every \usym{AudioTrack::recordAutomation}
+      call, \usym{ARVT{\_}START} and \usym{ARVT{\_}STOP} are generated by
+      \sym{AudioTrack::startAutoRecord} and \sym{stopAutoRecord}, respectively.
+\item and the id of the controller which is affected
+\end{itemize}
+It is processed when the song is stopped. The call path for this is:
+\sym{Song::stopRolling} calls \sym{Song::processAutomationEvents}
+calls \sym{AudioTrack::processAutomationEvents}.
+This function removes the old events from the track's controller list
+and replaces them with the new events from \sym{{\_}recEvents}. In
+\usym{AUTO{\_}WRITE} mode, just all controller events within the recorded
+range are erased; in \usym{AUTO{\_}TOUCH} mode, the \usym{ARVT{\_}START}
+and \usym{ARVT{\_}STOP} types of the \sym{CtrlRecVal} events are used
+to determine the range(s) which should be wiped.
+
+\paragraph{How it's stored}
+Automation data is kept                                                  % this is copied from
+in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList},        % "design decisions" -> "automation"
+that is, a list of \sym{CtrlList}s, that is, a list of lists of
+controller-objects which hold the control points of the automation graph.
+The \sym{CtrlList} also stores whether the list is meant discrete
+(a new control point results in a value-jump) or continuous (a new control
+point results in the value slowly sloping to the new value).
+Furthermore, it stores a \sym{{\_}curVal} (accessed by \sym{curVal()}),
+which holds the currently active value, which can be different from the
+actually stored value because of user interaction. This value is also
+used when there is no stored automation data.
+
+\sym{AudioTrack::addController} and \sym{removeController} are used        % TODO: swapControllerIDX??
+to add/remove whole controller types; the most important functions which
+access \sym{{\_}controller} are:
+\begin{itemize}
+\item \sym{processAutomationEvents}, \sym{recordAutomation},
+      \sym{startAutoRecord}, \sym{stopAutoRecord}: see above.
+\item \sym{seekPrevACEvent}, \sym{seekNextACEvent}, \sym{eraseACEvent},
+      \sym{eraseRangeACEvents}, \sym{addACEvent}, \sym{changeACEvent},
+      which do the obvious
+\item \sym{pluginCtrlVal}, \sym{setPluginCtrlVal}: the first
+      returns the current value according to the \sym{{\_}controller}
+      list, the second only sets the \sym{curVal}, but does not
+      insert any events.
+\end{itemize}
+
+Whenever a \sym{CtrlList} has been manipulated,
+\sym{MusEGlobal::song->controllerChange(Track{*})} shall be called,
+which emits the \sym{MusEGlobal::song->controllerChanged(Track{*})}
+signal in order to inform any parts of MusE about the change (currently,
+only the arranger's part canvas utilizes this).
+
+\paragraph{Enabling and disabling controllers}
+Disabling the controller is both dependent from the current automation
+mode and from whether the GUI is native or not.
+In \usym{AUTO{\_}WRITE} mode, once a slider is touched (for MusE-GUIs) or
+once a OSC control change is received (for native GUIs), the control
+is disabled until the song is stopped or seeked.
+
+In \usym{AUTO{\_}TOUCH} (and currently (r1492) \usym{AUTO{\_}READ}, but
+that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the
+corresponding control is disabled. Once the slider is released, the
+control is re-enabled again. Checkboxes remain in "disabled" mode,
+however they only affect the recorded automation until the last toggle
+of the checkbox. (Example: start the song, toggle the checkbox, toggle
+it again, wait 10 seconds, stop the song. This will NOT overwrite the
+last 10 seconds of automation data, but everything between the first
+and the last toggle.). For native GUIs, this is a bit tricky, because
+we don't have direct access to the GUI widgets. That is, we have no
+way to find out whether the user doesn't touch a control at all, or
+whether he has it held down, but just doesn't operate it. The current
+behaviour for native GUIs is to behave like in \usym{AUTO{\_}WRITE} mode.
+
+The responsible functions are: \sym{PluginI::oscControl} and
+\sym{DssiSynthIF::oscControl} for handling native GUIs,
+\sym{PluginI::ctrlPressed} and \sym{ctrlReleased} for MusE
+default GUIs and \sym{PluginI::guiParamPressed},
+\sym{guiParamReleased}, \sym{guiSliderPressed} and
+\sym{guiSliderReleased} for MusE GUIs read from a UI file;
+\sym{guiSlider{*}} obviously handle sliders, while \sym{guiParam{*}}
+handle everything else which is not a slider. They call
+\sym{PluginI::enableController} to enable/disable it.
+
+Furthermore, on every song stop or seek, \sym{PluginI::enableAllControllers}
+is called, which re-enables all controllers again. The call paths for
+this are:
+\begin{itemize}
+\item For stop: \sym{Song::stopRolling} calls
+                \sym{Song::processAutomationEvents} calls
+                \sym{Song::clearRecAu{\-}to{\-}ma{\-}tion} calls
+                \sym{Track::clearRecAutomation} calls
+                \sym{PluginI::enableAllControllers}
+\item For seek: \sym{Audio::seek} sends a message ("\sym{G}") to
+                \sym{Song::seqSignal} which calls
+                \sym{Song::clearRecAutomation} which calls
+                \sym{PluginI::enableAllControllers}
+\end{itemize}
+
+
+
+
+\chapter{Design decisions}
+\section{Automation}
+As of revision 1490, automation is handled in two ways: User-generated
+(live) automation data (generated by the user moving sliders while playing)
+is fed into \sym{PluginI::{\_}controlFifo}. Automation data is kept
+in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList},
+that is, a list of \sym{CtrlList}s, that is, a list of lists of
+controller-objects which hold the control points of the automation graph.
+The \sym{CtrlList} also stores whether the list is meant discrete
+(a new control point results in a value-jump) or continous (a new control
+point results in the value slowly sloping to the new value).
+
+While \sym{PluginI::{\_}controlFifo} can be queried very quickly and
+thus is processed with a very high resolution (only limited by the
+minimum control period setting), the automation value are expensive to
+query, and are only processed once in an audio \emph{driver} period.
+This might lead to noticeable jumps in value.
+
+This could possibly be solved in two ways:
+\paragraph{Maintaining a slave control list}
+This approach would maintain a fully redundant slave control list,
+similar to \sym{PluginI::{\_}controlFifo}. This list must be updated
+every time any automation-related thing is changed, and shall contain
+every controller change as a tuple of controller number and value.
+This could be processed in the same loop as \sym{PluginI::{\_}controlFifo},
+making it comfortable to implement; furthermore, it allows to cleanly
+offer automation-settings at other places in future (such as storing
+automation data in parts or similar).
+
+\paragraph{Holding iterators}
+We also could hold a list of iterators of the single \sym{CtrlList}s.
+This would also cause low CPU usage, because usually, the iterators only
+need to be incremented once. However, it is pretty complex to implement,
+because the iterators may become totally wrong (because of a seek in the
+song), and we must iterate through a whole list of iterators.
+
+\paragraph{Just use the current data access functions}
+By just using the current functions for accessing automation data,
+we might get a quick-and-dirty solution, which however wastes way too
+much CPU ressources. This is because on \emph{every single frame}, we
+need to do a binary search on multiple controller lists.
+
+
+\chapter{Feature requests}
+\section{Per-Part automation and more on automation}                       % by flo
+Automation shall be undo-able. Automation shall reside in parts which
+are exchangeable, clonable etc (like the MIDI- and Wave-Parts).
+Global per-synth/per-audiotrack automation shall also be available, but
+this can also be implemented as special case of part automation (one
+long part).
+
+\section{Pre-Rendering tracks}
+\subsection{The feature}
+All tracks shall be able to be "pre-renderable". Pre-rendering shall
+be "layered". Pre-rendering shall act like a transparent audio cache:
+Audio data is (redundantly) stored, wasting memory in order to save CPU.
+
+That is: Each track owns one or more wave-recordings of the length of
+the song. If the user calls "pre-render" on a track, then this track
+is played quasi-solo (see below), and the raw audio data is recorded
+and stored in the "layer 0" wave recording. If the user has any effects
+set up to be applied, then each effect is applied on a different layer
+(creating layer 1, layer 2 etc).
+
+This means, that also MIDI and drum tracks can have effects (which
+usually only operate on audio, but we HAVE audio data because of this
+prerendering).
+
+Furthermore, MusE by default does not send MIDI events to the synthesizers
+but instead just plays back the last layer of the prerecording (for
+MIDI tracks), or does not pipe the audio data through the whole plugin
+chain (causing cpu usage), but instead just plays back the last layer.
+The hearable result shall be the same.
+
+Once the user changes any parameter (automation data or plugins for
+wave tracks, MIDI events or effect plugin stuff for MIDI tracks),
+then MusE shall generate the sound for this particular track in the
+"old" way (send MIDI data to synthes, or pipe audio data through plugins).
+(So that the user will not even notice that MusE actually pre-renderered
+stuff.) Either MusE automatically records this while playback (if possible)
+or prompts the user to accordingly set up his cabling and then record
+it. Or (temporarily) disables prerecording for this track, falling back
+to the plain old way of generating sound.
+
+\emph{Quasi-solo} means: For wave tracks, just solo the track. For MIDI
+tracks, mute all tracks which are not on the same synth (channel?),
+and mute all \emph{note} events which are not on the quasi-soloed track.
+This causes MusE to still play any controller events from different
+tracks, because they might have effects on the quasi-soloed track. (You
+can have notes on channel 1 on one track and controller stuff on channel
+1 on another track; then you would need quasi-solo to get proper results.)
+
+\subsection{Use cases}
+\paragraph{Saving CPU}
+On slow systems, this is neccessary for songs with lots of, or demanding
+(or both) soft synthes / plugins. Even if the synth or plugin is so
+demanding that your system is not able to produce sound in real-time,
+then with this feature you'll be able to use the synth (this will make
+editing pretty laggish, because for a change you need to re-render at
+least a part before you can listen to it, but better than being unable
+to use the synth at all!)
+
+\paragraph{Exporting as audio project}
+Using pre-rendering on all tracks, you easily can export your project
+as multi-track audio file (for use with Ardour or similar DAWs).
+Just take the last layer of each track, and write the raw audio data
+into the file, and you're done. (Maybe we are even able to write down
+the raw-raw layer0 audio data plus information about used plugins and
+settings etc..?)
+
+\paragraph{Mobile audio workstations}
+You might want to work a bit on your audio projects on your notebook
+while you're not at home, not having access to your hardware synthesizers.
+Using this feature, you could have pre-recorded the stuff in your studio
+before, and now can at least fiddle around with the non-hw-synth-dependent
+parts of your song, while still having your \emph{full} song with you.
+
+\paragraph{Applying effects on MIDI tracks}
+If you have many physical audio inputs, you might already be able to
+apply effect chains on MIDI tracks, by wiring the synthes' audio
+outputs to your soundcard's inputs, and applying the effects on
+dedicated input tracks you have to create. This requires you to have
+expensive hardware, and is pretty complicated, because you need one
+additional track per MIDI synth.
+
+This feature allows you to apply effects on single MIDI tracks, and not
+only on full MIDI synthes, and doesn't require you to be have that
+many physical audio inputs (you need to manually replug your synthes,
+however).
+
+\subsection{Possible scenarios}
+\paragraph{Setting it up}
+Create a wave track, MusE will allow you to set or unset prerendering
+for every plugin in the plugin rack (recording the actual track is
+useless because it would be a plain copy).
+Create a MIDI track, MusE will ask you on which physical audio input
+your synth is connected. Setting up multiple synthes on one physical
+audio in is allowed, see below.
+
+\paragraph{Pre-rendering stuff}
+When the user presses the "pre-render" button, all tracks which have
+been changed since their last pre-rendering will be re-rendered.
+If you have multiple hardware synthes set up as they were connected
+to one physical audio input port, MusE will prompt you to first plug
+the proper cable in.
+
+\paragraph{Making changes}
+Change a note in a MIDI part, move or delete a part or change automation
+parameters. MusE will temporarily disable the pre-rendered information
+and instead generate the sound via sending out MIDI events, piping stuff
+through effect chains or similar. If you play back the whole song, or
+if you manually trigger a re-rendering of a track via the context menu,
+MusE will play back the stuff, record it again and re-enable the
+pre-rendered information.
+
+
+\subsection{Extensions}
+\paragraph{Automatic discovery of physical audio connections}
+The user plugs all (or only some) synthes' audio outs into the available
+audio inputs, then runs automatic discovery. This will send MIDI events
+to each synthesizer, and look on which audio in there's activity. Then
+it will assume that the synthesizer is connected to that particular
+audio in. Audio ins which show activity before any MIDI events were
+sent are not considered, as they're probably connected to microphones
+or other noise-generating non-synthes.
+
+\paragraph{Audio export}
+As described in the Use cases, MusE can allow you to export your song
+in some multitrack audio format.
+
+\paragraph{Cheap/Faked changes}
+For expensive or unavailable synthes, changing the Volume midi controller,
+the Pan controller or similar "easy" controllers will not trigger a
+complete re-rendering, but instead "fake" the change, by changing
+the volume data directly on the recorded wave. This might require some
+learning and might even get pretty complicated.
+
+\paragraph{Intelligent re-recording}
+For tiny changes, MusE shall only re-render the relevant part. If you
+change some MIDI notes, then begin re-recording shortly before the
+changes, and end re-recording as soon as the recorded stuff doesn't
+differ to much from the stuff coming from the synth. Then properly
+blend the old recording with the updated part.
+
+
+
+\section{Slotted editors}
+Currently, MusE has the pianoroll editor, drum editor, score editor,
+then the controller editor which is inside the pianoroll/drum editor.
+All these editors have a very similar concept: the "time axis" is
+vertical and (almost) linear, they handle parts, and events are
+manipulated similarly.
+
+A unified editor shall be created which allows you to combine different
+kinds of editors in one window, properly aligned against each other.
+These "different kinds of editors" shall be handled as "slots"; one
+unified editor window consists of:
+\begin{itemize}
+\item A menu bar, containing stuff suitable for the complete window,
+      which might include window name, MDI-ness etc.
+\item A toolbar which contains controls suitable for every single slot.
+\item A container with one or more slots; the slots can be scrolled in
+      y-direction if there are multipe slots.
+\item A time-scrollbar with zoom
+\end{itemize}
+
+Each slot contains the following:
+\begin{itemize}
+\item A menu button, button box or control panel for setting up this
+      particular slot. This could contain "note head colors", "show
+      a transposing instrument" etc for score edit slots, "event
+      rectangle color", "grid size" and "snap to grid" for pianoroll/
+      drum editors.
+\item The actual canvas
+\item A y-direction scroll bar, possibly with zoom control (for
+      pianoroll editor)
+\end{itemize}
+
+The main window does not show its scroll bar if there is only one slot,
+because the slot's scrollbar is sufficient then.
+
+Slots can be added, destroyed, moved around, maybe even merged (if the
+slot types allow it); basically, you can compare them with the staves
+in the score editor.
+
+The slots shall align against each other, that is, if a score editor
+slot displays a key change with lots of accidentials, then all other
+slots shall either also display the key change (if they're score slots)
+or display a gap. Events which happen at the same time shall be at the
+same x-coordinate, regardless which slot they are.
+
+\section{Controller master values}
+All controllers (MIDI-controllers and also automation controllers)
+shall have one set of "master values" which allow you to set a gain and
+a bias. Instead of the actual set value, $\textrm{value} * \textrm{bias}
++ textrm{bias}$ shall be sent to the MIDI device / the plugin. For
+controllers like "pan", the unbiased values shall be transformed, that
+is, a pan of 64, with $\textrm{bias}=2$ and $\textrm{gain}=0.5$, shall
+be transformed to 66 (because 64 is actually 0, while 0 is actually -64).
+These values shall be set in the arranger and whereever the actual
+controller/automation values can be edited.
+
+\section{Enabled-indicator while recording}
+The MusE-plugin-GUIs shall display a small LED displaying whether a
+controller is currently enabled or disabled. By clicking this LED, the
+enabled state shall be switched.
+
+Furthermore, there shall be a dedicated window which only lets you switch
+enabled/disabled states. This will be useful when using external GUIs
+or the MIDI-controller-to-automation feature, to re-enable a controller
+when in \usym{AUTO{\_}TOUCH} mode.
+
+
+
+\section{Linear automation editing}
+While holding some modifier key (like shift), operating the MusE-native-
+GUI sliders shall only generate control points when clicking and when
+releasing the slider. This will result in linear graphs for continous
+controllers, and in large steps for discrete controllers (which is in
+particular useful for stuff like "which low/high-pass filter type to use").
+
+Maybe make this behaviour default for discrete controllers?
+
+\section{Symbolic names for MIDI ports} \label{symbolic_ports}
+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7").
+The mapping between these symbolic names and the hardware port (like
+"ALSA midi out port") is stored in the global configuration.
+
+Song files only specify the symbolic names as the ports associated with
+their tracks. No information about physical devices/port names, but only
+symbolic names are stored in the song file.
+
+This resolves the issues mentioned in \ref{portconfig_sucks}, and also
+allows the user to share his pieces with other people: They would only
+have to set up that symbolic-to-hardware mapping once (collisions are
+unlikely, because an equal symbolic name should usually mean the same
+device) and are happy, instead of having to re-map \emph{every} port
+for \emph{every} song.
+
+\end{document}
+
+% TODO: song type etc? kill it!
+%       song len box: same
+
+% TODO: unified automation and midi ctrls:
+%       both shall be editable through the same editors
+%       four modes: 1. discrete
+%                   2. continous (plus a global and per-port setting for the max rate)
+%                   3. switch (not necessarily ON/OFF; signals with color plus text annotation)
+%                   4. raw (no graph, instead a box with the value sent out (for "all voices off")
+%       they shall be copy-and-pastable, at least between compatible modes
+%       they shall be slotted, like pianoroll
+%       maybe also "overlapping", like arranger (?)
+%       midi recording tries to make out straight lines (like non-ended automation streams)
+%
+
+
+% new song (in general: load as template) plus "overwrite port config"
+% should re-create the default jack devices and autoconnect them.
+
+% what's audio aux for?
+
+% bug in arranger/pcanvas/automation: if a controlpoint is directly on
+% a line of another ctrl graph, you can't click it
+
diff --git a/muse2/doc/documentation.tex b/muse2/doc/documentation.tex
index 37dbafc5..a6fe929b 100644
--- a/muse2/doc/documentation.tex
+++ b/muse2/doc/documentation.tex
@@ -111,10 +111,6 @@
         \renewcommand{\headrulewidth}{0.4pt}
 \usepackage{ifthen}
 
-%% Borrowed from Lyx output. "Because html converters don't know 
-%%  tabularnewline". Is required? Maybe replace with \\ ?
-\providecommand{\tabularnewline}{\\}
-
 % Hyphenate symbols before each uppercase letter, after each underscore
 % (without a "-") and after each ':' (without a "-")
 % TODO for any latex crack: also do automatic hyphenation, that is,
@@ -1058,29 +1054,29 @@ output, MusE uses the first input or output and ignores the rest.
 For stereo tracks:
 
 \begin{tabular}{|c|c|c|c|c|}
-\hline 
+\hline
 plugin inputs & outputs & copies & track in route channels &
-track out route channels\tabularnewline
-\hline 
-\hline 
-0 & 0 & 1 & 0 & 0\tabularnewline
-\hline 
-0 & 1 & 2 & 0 & 2\tabularnewline
-\hline 
-0 & >=2 & 1 & 0 & 2\tabularnewline
-\hline 
-1 & 0 & 2 & 2 & 0\tabularnewline
-\hline 
-1 & 1 & 2 & 2 & 2\tabularnewline
-\hline 
-1 & >=2 & 1 & 1 (L only) & 2\tabularnewline
-\hline 
->=2 & 0 & 1 & 2 & 0\tabularnewline
-\hline 
->=2 & 1 & 2 & 2 & 2\tabularnewline
-\hline 
->=2 & >=2 & 1 & 2 & 2\tabularnewline
-\hline 
+track out route channels\\
+\hline
+\hline
+0 & 0 & 1 & 0 & 0\\
+\hline
+0 & 1 & 2 & 0 & 2\\
+\hline
+0 & >=2 & 1 & 0 & 2\\
+\hline
+1 & 0 & 2 & 2 & 0\\
+\hline
+1 & 1 & 2 & 2 & 2\\
+\hline
+1 & >=2 & 1 & 1 (L only) & 2\\
+\hline
+>=2 & 0 & 1 & 2 & 0\\
+\hline
+>=2 & 1 & 2 & 2 & 2\\
+\hline
+>=2 & >=2 & 1 & 2 & 2\\
+\hline
 \end{tabular}
 
 Notice that on a stereo track with a plugin having one audio input and
@@ -1125,544 +1121,5 @@ For example, for a plugin having one audio input and one audio output,
 feeding a plugin having one audio input and two audio outputs,  
 the extra copy of the first plugin is redundant and not required,
 but currently it is created anyway.
-  
-
-\chapter{Internals -- how it works}
-This chapter explains how MusE is built internally, and is meant
-to be an aid for developers wanting to quickly start up with MusE.
-For details on \emph{why} stuff is done please refer to the following
-chapter. 
-
-\section{User interface programming}
-We use the QT Toolkit for GUI- and other programming. The \emph{QT-Assistant}
-is an important tool for getting help. Almost everything can be looked
-up there.
-
-GUIs can be either be hardcoded (see \file{arranger.cpp} for an example)
-or can be created using \emph{QT-Designer} (see the dialogs under
-\file{widgets/function_dialogs/} for mostly cleanly-written examples).
-Don't forget to add your \file{cpp}, \file{h} and \file{ui} files to the
-corresponding sections in the \file{CMakeLists.txt}!
-
-Additionally, MusE offers some custom widgets, like menu title items etc.
-Following, there will be a small, unordered list about custom widgets:
-\begin{itemize}
-\item \sym{MusEGui::MenuTitleItem}: Provides a title-bar in a \sym{QMenu}. \\
-      Usage: \listing{someMenu->addAction(new\ MusEGui::MenuTitleItem(tr("fnord"),\ someMenu));} \\
-      Defined in \file{widgets/menutitleitem.h}.
-\item \sym{MusEGui::PopupMenu}: Provides a \sym{QMenu}-like menu which
-      can stay open after the user checks a checkable action.\\
-      Usage: just create a \listing{new\ PopupMenu(\ true|false\ )} instead of
-             a \listing{new\ QMenu()}. (\listing{true} means 'stay open')\\
-      Defined in \file{widgets/popupmenu.h}.
-\end{itemize}
-
-
-\section{Configuration} \label{portconfig_sucks}
-Configuration is a bit pesky in MusE in its current state. If you get
-confused by reading this chapter, that's a sign of a sane mind.
-
-There are three kinds of configuration items:
-\begin{itemize}
-\item (1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings
-\item (2) Per-Song configuration, like whether to show or hide certain track types in the arranger
-\item (3) Something in between, like MIDI port settings etc. They obviously actually are
-      global configuration issues (or ought to be), but also obviously must be stored
-      in the song file for portability. (This problem could possibly be solved by
-      the feature proposal in \ref{symbolic_ports}.
-\end{itemize}
-
-\paragraph{Reading configuration}
-\sym{void\ MusECore::readConfiguration(Xml\&,\ bool,\ bool)} in
-\file{conf.cpp} is the central point
-of reading configuration. It is called when MusE is started first
-(by \sym{bool\ MusECore::readConfiguration()}), and also when a
-song is loaded. \\ %TODO: call paths!
-It can be instructed whether to read MIDI ports (3), global configuration
-and MIDI ports (1+3). Per-Song configuration is always read (2).
-
-When adding new configuration items and thus altering \sym{readConfiguration()},
-you must take care to place your item into the correct section. The code is
-divided into the following sections:
-\begin{itemize}
-\item Global and/or per-song configuration (3)
-\item Global configuration (1)
-\item Code for skipping obsolete entries
-\end{itemize}
-
-The sections are divided by comments (they contain \texttt{----}, so just
-search for them). Please do not just remove code for reading obsolete entries, 
-but always add an appropriate entry to the 'skipping' section in order to
-prevent error messages when reading old configs.
-
-\paragraph{Writing configuration}
-Global configuration is written using the
-\sym{MusEGui::MusE::writeGlobalConfiguration()} functions, while
-per-song-config is written by \sym{MusEGui::MusE::writeConfiguration()}
-(notice the missing \sym{Global}; both implemented in \file{conf.cpp}).
-
-\sym{writeConfiguration} is actually just a subset of the code in
-\sym{writeGlobalConfiguration}. \textbf{Duplicate code!}                  % TODO fix that in the sourcecode.
-
-\paragraph{Song state}
-Additionally to per-song configuration, there is the song's state.
-This contains "the song", that is all tracks, parts and note events,
-together with information about the currently opened windows, their
-position, size, settings and so on. Adding new items here is actually
-pretty painless: Configuration is read and written using
-\sym{MusECore::Song::read} and \sym{::write}, both implemented in
-\file{songfile.cpp}. There are no caveats.
-
-\paragraph{How to add new items}
-When adding global configuration items, then add them into the second
-block ("global configuration") in \sym{readConfiguration} and into
-\sym{writeGlobalConfiguration}.
-
-When adding just-per-song items, better don't bother to touch the
-"configuration" code and just add it to the song's state (there might
-be rare exceptions).
-
-When adding global configuration items, make sure you add them into the
-correct section of \sym{readConfiguration}, and into \sym{writeGlobalConfiguration}.
-
-
-%TODO: how to write config,
-%TODO: song/global stuff
-%TODO: config lesen und schreiben fuer plugingroups
-
-
-\section{User controls and automation}
-\subsection{Handling user input}
-\subsubsection{Plugins and synthesizers}
-\paragraph{Overview}
-When the user launches a plugin's GUI, either a MusE-window with
-the relevant controls is shown, or the native GUI is launched. MusE
-will communicate with this native GUI through OSC (Open Sound Control).
-The relevant classes are \sym{PluginGui}, \sym{PluginIBase}
-(in \file{plugin.h}) and \sym{OscIF} (in \sym{osc.h}).
-
-If the user changes a GUI element, first the corresponding control is
-disabled, making MusE not steadily update it through automation
-while the user operates it. Then MusE will update the plugin's parameter
-value, and also record the new value. When appropriate, the controller
-is enabled again.
-
-\paragraph{Processing the input, recording}
-Upon operating a slider, \sym{PluginIBase::setParam} is called,
-which usually writes the control change into the ringbuffer
-\sym{PluginI::{\_}controlFifo}. (\sym{PluginI::apply()},
-\sym{DssiSynthIF::getData()} will read this ringbuffer and
-do the processing accordingly). Furthermore, \sym{AudioTrack::recordAutomation}
-is called, which either directly modifies the controller lists or writes
-the change into a "to be recorded"-list (\sym{AudioTrack::{\_}recEvents})
-(depending on whether the song is stopped or played).
-
-The \sym{AudioTrack::{\_}recEvents} list consists of \sym{CtrlRecVal}
-items (see \file{ctrl.h}), which hold the following data: 
-\begin{itemize}
-\item the frame where the change occurred 
-\item the value 
-\item the type, which can be \usym{ARVT{\_}START}, \usym{ARVT{\_}VAL} or \usym{ARVT{\_}STOP}.
-      \usym{ARVT{\_}VAL} are written by every \usym{AudioTrack::recordAutomation}
-      call, \usym{ARVT{\_}START} and \usym{ARVT{\_}STOP} are generated by
-      \sym{AudioTrack::startAutoRecord} and \sym{stopAutoRecord}, respectively.
-\item and the id of the controller which is affected
-\end{itemize}
-It is processed when the song is stopped. The call path for this is:
-\sym{Song::stopRolling} calls \sym{Song::processAutomationEvents}
-calls \sym{AudioTrack::processAutomationEvents}.
-This function removes the old events from the track's controller list
-and replaces them with the new events from \sym{{\_}recEvents}. In
-\usym{AUTO{\_}WRITE} mode, just all controller events within the recorded
-range are erased; in \usym{AUTO{\_}TOUCH} mode, the \usym{ARVT{\_}START}
-and \usym{ARVT{\_}STOP} types of the \sym{CtrlRecVal} events are used
-to determine the range(s) which should be wiped.
-
-\paragraph{How it's stored}
-Automation data is kept                                                  % this is copied from
-in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList},        % "design decisions" -> "automation"
-that is, a list of \sym{CtrlList}s, that is, a list of lists of
-controller-objects which hold the control points of the automation graph.
-The \sym{CtrlList} also stores whether the list is meant discrete
-(a new control point results in a value-jump) or continuous (a new control
-point results in the value slowly sloping to the new value).
-Furthermore, it stores a \sym{{\_}curVal} (accessed by \sym{curVal()}),
-which holds the currently active value, which can be different from the
-actually stored value because of user interaction. This value is also
-used when there is no stored automation data.
-
-\sym{AudioTrack::addController} and \sym{removeController} are used        % TODO: swapControllerIDX??
-to add/remove whole controller types; the most important functions which
-access \sym{{\_}controller} are:
-\begin{itemize}
-\item \sym{processAutomationEvents}, \sym{recordAutomation},
-      \sym{startAutoRecord}, \sym{stopAutoRecord}: see above.
-\item \sym{seekPrevACEvent}, \sym{seekNextACEvent}, \sym{eraseACEvent},
-      \sym{eraseRangeACEvents}, \sym{addACEvent}, \sym{changeACEvent},
-      which do the obvious
-\item \sym{pluginCtrlVal}, \sym{setPluginCtrlVal}: the first
-      returns the current value according to the \sym{{\_}controller}
-      list, the second only sets the \sym{curVal}, but does not
-      insert any events.
-\end{itemize}
-
-Whenever a \sym{CtrlList} has been manipulated,
-\sym{MusEGlobal::song->controllerChange(Track{*})} shall be called,
-which emits the \sym{MusEGlobal::song->controllerChanged(Track{*})}
-signal in order to inform any parts of MusE about the change (currently,
-only the arranger's part canvas utilizes this).
-
-\paragraph{Enabling and disabling controllers}
-Disabling the controller is both dependent from the current automation
-mode and from whether the GUI is native or not.
-In \usym{AUTO{\_}WRITE} mode, once a slider is touched (for MusE-GUIs) or
-once a OSC control change is received (for native GUIs), the control
-is disabled until the song is stopped or seeked.
-
-In \usym{AUTO{\_}TOUCH} (and currently (r1492) \usym{AUTO{\_}READ}, but
-that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the
-corresponding control is disabled. Once the slider is released, the
-control is re-enabled again. Checkboxes remain in "disabled" mode,
-however they only affect the recorded automation until the last toggle
-of the checkbox. (Example: start the song, toggle the checkbox, toggle
-it again, wait 10 seconds, stop the song. This will NOT overwrite the
-last 10 seconds of automation data, but everything between the first
-and the last toggle.). For native GUIs, this is a bit tricky, because
-we don't have direct access to the GUI widgets. That is, we have no
-way to find out whether the user doesn't touch a control at all, or
-whether he has it held down, but just doesn't operate it. The current
-behaviour for native GUIs is to behave like in \usym{AUTO{\_}WRITE} mode.
-
-The responsible functions are: \sym{PluginI::oscControl} and
-\sym{DssiSynthIF::oscControl} for handling native GUIs,
-\sym{PluginI::ctrlPressed} and \sym{ctrlReleased} for MusE
-default GUIs and \sym{PluginI::guiParamPressed},
-\sym{guiParamReleased}, \sym{guiSliderPressed} and
-\sym{guiSliderReleased} for MusE GUIs read from a UI file;
-\sym{guiSlider{*}} obviously handle sliders, while \sym{guiParam{*}}
-handle everything else which is not a slider. They call
-\sym{PluginI::enableController} to enable/disable it.
-
-Furthermore, on every song stop or seek, \sym{PluginI::enableAllControllers}
-is called, which re-enables all controllers again. The call paths for
-this are:
-\begin{itemize}
-\item For stop: \sym{Song::stopRolling} calls
-                \sym{Song::processAutomationEvents} calls
-                \sym{Song::clearRecAu{\-}to{\-}ma{\-}tion} calls
-                \sym{Track::clearRecAutomation} calls
-                \sym{PluginI::enableAllControllers}
-\item For seek: \sym{Audio::seek} sends a message ("\sym{G}") to
-                \sym{Song::seqSignal} which calls
-                \sym{Song::clearRecAutomation} which calls
-                \sym{PluginI::enableAllControllers}
-\end{itemize}
-
-
-
-
-\chapter{Design decisions}
-\section{Automation}
-As of revision 1490, automation is handled in two ways: User-generated
-(live) automation data (generated by the user moving sliders while playing)
-is fed into \sym{PluginI::{\_}controlFifo}. Automation data is kept
-in \sym{AudioTrack::{\_}controller}, which is a \sym{CtrlListList},
-that is, a list of \sym{CtrlList}s, that is, a list of lists of
-controller-objects which hold the control points of the automation graph.
-The \sym{CtrlList} also stores whether the list is meant discrete
-(a new control point results in a value-jump) or continous (a new control
-point results in the value slowly sloping to the new value).
-
-While \sym{PluginI::{\_}controlFifo} can be queried very quickly and
-thus is processed with a very high resolution (only limited by the
-minimum control period setting), the automation value are expensive to
-query, and are only processed once in an audio \emph{driver} period.
-This might lead to noticeable jumps in value.
-
-This could possibly be solved in two ways:
-\paragraph{Maintaining a slave control list}
-This approach would maintain a fully redundant slave control list,
-similar to \sym{PluginI::{\_}controlFifo}. This list must be updated
-every time any automation-related thing is changed, and shall contain
-every controller change as a tuple of controller number and value.
-This could be processed in the same loop as \sym{PluginI::{\_}controlFifo},
-making it comfortable to implement; furthermore, it allows to cleanly
-offer automation-settings at other places in future (such as storing
-automation data in parts or similar).
-
-\paragraph{Holding iterators}
-We also could hold a list of iterators of the single \sym{CtrlList}s.
-This would also cause low CPU usage, because usually, the iterators only
-need to be incremented once. However, it is pretty complex to implement,
-because the iterators may become totally wrong (because of a seek in the
-song), and we must iterate through a whole list of iterators.
-
-\paragraph{Just use the current data access functions}
-By just using the current functions for accessing automation data,
-we might get a quick-and-dirty solution, which however wastes way too
-much CPU ressources. This is because on \emph{every single frame}, we
-need to do a binary search on multiple controller lists.
-
-
-\chapter{Feature requests}
-\section{Per-Part automation and more on automation}                       % by flo
-Automation shall be undo-able. Automation shall reside in parts which
-are exchangeable, clonable etc (like the MIDI- and Wave-Parts).
-Global per-synth/per-audiotrack automation shall also be available, but
-this can also be implemented as special case of part automation (one
-long part).
-
-\section{Pre-Rendering tracks}
-\subsection{The feature}
-All tracks shall be able to be "pre-renderable". Pre-rendering shall
-be "layered". Pre-rendering shall act like a transparent audio cache:
-Audio data is (redundantly) stored, wasting memory in order to save CPU.
-
-That is: Each track owns one or more wave-recordings of the length of
-the song. If the user calls "pre-render" on a track, then this track
-is played quasi-solo (see below), and the raw audio data is recorded
-and stored in the "layer 0" wave recording. If the user has any effects
-set up to be applied, then each effect is applied on a different layer
-(creating layer 1, layer 2 etc).
-
-This means, that also MIDI and drum tracks can have effects (which
-usually only operate on audio, but we HAVE audio data because of this
-prerendering).
-
-Furthermore, MusE by default does not send MIDI events to the synthesizers
-but instead just plays back the last layer of the prerecording (for
-MIDI tracks), or does not pipe the audio data through the whole plugin
-chain (causing cpu usage), but instead just plays back the last layer.
-The hearable result shall be the same.
-
-Once the user changes any parameter (automation data or plugins for
-wave tracks, MIDI events or effect plugin stuff for MIDI tracks),
-then MusE shall generate the sound for this particular track in the
-"old" way (send MIDI data to synthes, or pipe audio data through plugins). 
-(So that the user will not even notice that MusE actually pre-renderered
-stuff.) Either MusE automatically records this while playback (if possible)
-or prompts the user to accordingly set up his cabling and then record
-it. Or (temporarily) disables prerecording for this track, falling back
-to the plain old way of generating sound.
-
-\emph{Quasi-solo} means: For wave tracks, just solo the track. For MIDI
-tracks, mute all tracks which are not on the same synth (channel?),
-and mute all \emph{note} events which are not on the quasi-soloed track.
-This causes MusE to still play any controller events from different
-tracks, because they might have effects on the quasi-soloed track. (You
-can have notes on channel 1 on one track and controller stuff on channel
-1 on another track; then you would need quasi-solo to get proper results.)
-
-\subsection{Use cases}
-\paragraph{Saving CPU}
-On slow systems, this is neccessary for songs with lots of, or demanding
-(or both) soft synthes / plugins. Even if the synth or plugin is so
-demanding that your system is not able to produce sound in real-time,
-then with this feature you'll be able to use the synth (this will make
-editing pretty laggish, because for a change you need to re-render at
-least a part before you can listen to it, but better than being unable
-to use the synth at all!)
-
-\paragraph{Exporting as audio project}
-Using pre-rendering on all tracks, you easily can export your project
-as multi-track audio file (for use with Ardour or similar DAWs).
-Just take the last layer of each track, and write the raw audio data
-into the file, and you're done. (Maybe we are even able to write down
-the raw-raw layer0 audio data plus information about used plugins and
-settings etc..?)
-
-\paragraph{Mobile audio workstations}
-You might want to work a bit on your audio projects on your notebook
-while you're not at home, not having access to your hardware synthesizers.
-Using this feature, you could have pre-recorded the stuff in your studio
-before, and now can at least fiddle around with the non-hw-synth-dependent
-parts of your song, while still having your \emph{full} song with you.
-
-\paragraph{Applying effects on MIDI tracks}
-If you have many physical audio inputs, you might already be able to
-apply effect chains on MIDI tracks, by wiring the synthes' audio
-outputs to your soundcard's inputs, and applying the effects on
-dedicated input tracks you have to create. This requires you to have
-expensive hardware, and is pretty complicated, because you need one
-additional track per MIDI synth.
-
-This feature allows you to apply effects on single MIDI tracks, and not
-only on full MIDI synthes, and doesn't require you to be have that
-many physical audio inputs (you need to manually replug your synthes,
-however).
-
-\subsection{Possible scenarios}
-\paragraph{Setting it up}
-Create a wave track, MusE will allow you to set or unset prerendering
-for every plugin in the plugin rack (recording the actual track is
-useless because it would be a plain copy).
-Create a MIDI track, MusE will ask you on which physical audio input
-your synth is connected. Setting up multiple synthes on one physical
-audio in is allowed, see below.
-
-\paragraph{Pre-rendering stuff}
-When the user presses the "pre-render" button, all tracks which have
-been changed since their last pre-rendering will be re-rendered.
-If you have multiple hardware synthes set up as they were connected
-to one physical audio input port, MusE will prompt you to first plug
-the proper cable in.
-
-\paragraph{Making changes}
-Change a note in a MIDI part, move or delete a part or change automation
-parameters. MusE will temporarily disable the pre-rendered information
-and instead generate the sound via sending out MIDI events, piping stuff
-through effect chains or similar. If you play back the whole song, or
-if you manually trigger a re-rendering of a track via the context menu,
-MusE will play back the stuff, record it again and re-enable the
-pre-rendered information.
-
-
-\subsection{Extensions}
-\paragraph{Automatic discovery of physical audio connections}
-The user plugs all (or only some) synthes' audio outs into the available
-audio inputs, then runs automatic discovery. This will send MIDI events
-to each synthesizer, and look on which audio in there's activity. Then
-it will assume that the synthesizer is connected to that particular
-audio in. Audio ins which show activity before any MIDI events were
-sent are not considered, as they're probably connected to microphones
-or other noise-generating non-synthes.
-
-\paragraph{Audio export}
-As described in the Use cases, MusE can allow you to export your song
-in some multitrack audio format.
-
-\paragraph{Cheap/Faked changes}
-For expensive or unavailable synthes, changing the Volume midi controller,
-the Pan controller or similar "easy" controllers will not trigger a
-complete re-rendering, but instead "fake" the change, by changing
-the volume data directly on the recorded wave. This might require some
-learning and might even get pretty complicated.
-
-\paragraph{Intelligent re-recording}
-For tiny changes, MusE shall only re-render the relevant part. If you
-change some MIDI notes, then begin re-recording shortly before the
-changes, and end re-recording as soon as the recorded stuff doesn't
-differ to much from the stuff coming from the synth. Then properly
-blend the old recording with the updated part.
-
-
-
-\section{Slotted editors}
-Currently, MusE has the pianoroll editor, drum editor, score editor,
-then the controller editor which is inside the pianoroll/drum editor.
-All these editors have a very similar concept: the "time axis" is 
-vertical and (almost) linear, they handle parts, and events are 
-manipulated similarly.
-
-A unified editor shall be created which allows you to combine different
-kinds of editors in one window, properly aligned against each other.
-These "different kinds of editors" shall be handled as "slots"; one
-unified editor window consists of:
-\begin{itemize}
-\item A menu bar, containing stuff suitable for the complete window,
-      which might include window name, MDI-ness etc.
-\item A toolbar which contains controls suitable for every single slot.
-\item A container with one or more slots; the slots can be scrolled in
-      y-direction if there are multipe slots.
-\item A time-scrollbar with zoom
-\end{itemize}
-
-Each slot contains the following: 
-\begin{itemize}
-\item A menu button, button box or control panel for setting up this
-      particular slot. This could contain "note head colors", "show
-      a transposing instrument" etc for score edit slots, "event
-      rectangle color", "grid size" and "snap to grid" for pianoroll/
-      drum editors.
-\item The actual canvas
-\item A y-direction scroll bar, possibly with zoom control (for
-      pianoroll editor)
-\end{itemize}
-
-The main window does not show its scroll bar if there is only one slot,
-because the slot's scrollbar is sufficient then.
-
-Slots can be added, destroyed, moved around, maybe even merged (if the
-slot types allow it); basically, you can compare them with the staves
-in the score editor.
-
-The slots shall align against each other, that is, if a score editor
-slot displays a key change with lots of accidentials, then all other
-slots shall either also display the key change (if they're score slots)
-or display a gap. Events which happen at the same time shall be at the
-same x-coordinate, regardless which slot they are.
-
-\section{Controller master values}
-All controllers (MIDI-controllers and also automation controllers)
-shall have one set of "master values" which allow you to set a gain and
-a bias. Instead of the actual set value, $\textrm{value} * \textrm{bias}
-+ textrm{bias}$ shall be sent to the MIDI device / the plugin. For
-controllers like "pan", the unbiased values shall be transformed, that
-is, a pan of 64, with $\textrm{bias}=2$ and $\textrm{gain}=0.5$, shall
-be transformed to 66 (because 64 is actually 0, while 0 is actually -64).
-These values shall be set in the arranger and whereever the actual
-controller/automation values can be edited.
-
-\section{Enabled-indicator while recording}
-The MusE-plugin-GUIs shall display a small LED displaying whether a
-controller is currently enabled or disabled. By clicking this LED, the
-enabled state shall be switched.
-
-Furthermore, there shall be a dedicated window which only lets you switch
-enabled/disabled states. This will be useful when using external GUIs
-or the MIDI-controller-to-automation feature, to re-enable a controller
-when in \usym{AUTO{\_}TOUCH} mode.
-
-
-
-\section{Linear automation editing}
-While holding some modifier key (like shift), operating the MusE-native-
-GUI sliders shall only generate control points when clicking and when
-releasing the slider. This will result in linear graphs for continous
-controllers, and in large steps for discrete controllers (which is in
-particular useful for stuff like "which low/high-pass filter type to use").
-
-Maybe make this behaviour default for discrete controllers?
-
-\section{Symbolic names for MIDI ports} \label{symbolic_ports}
-MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7").
-The mapping between these symbolic names and the hardware port (like
-"ALSA midi out port") is stored in the global configuration.
-
-Song files only specify the symbolic names as the ports associated with
-their tracks. No information about physical devices/port names, but only
-symbolic names are stored in the song file.
-
-This resolves the issues mentioned in \ref{portconfig_sucks}, and also
-allows the user to share his pieces with other people: They would only
-have to set up that symbolic-to-hardware mapping once (collisions are
-unlikely, because an equal symbolic name should usually mean the same
-device) and are happy, instead of having to re-map \emph{every} port
-for \emph{every} song.
-
 \end{document}
 
-% TODO: song type etc? kill it!
-%       song len box: same
-
-% TODO: unified automation and midi ctrls:
-%       both shall be editable through the same editors
-%       four modes: 1. discrete
-%                   2. continous (plus a global and per-port setting for the max rate)
-%                   3. switch (not necessarily ON/OFF; signals with color plus text annotation)
-%                   4. raw (no graph, instead a box with the value sent out (for "all voices off")
-%       they shall be copy-and-pastable, at least between compatible modes
-%       they shall be slotted, like pianoroll
-%       maybe also "overlapping", like arranger (?)
-%       midi recording tries to make out straight lines (like non-ended automation streams)
-%       
-
-
-% new song (in general: load as template) plus "overwrite port config"
-% should re-create the default jack devices and autoconnect them.
-
-% what's audio aux for?
-
-% bug in arranger/pcanvas/automation: if a controlpoint is directly on
-% a line of another ctrl graph, you can't click it
-
diff --git a/muse2/doc/pdf/developer_docs.pdf b/muse2/doc/pdf/developer_docs.pdf
new file mode 100644
index 00000000..65b7c1b7
--- /dev/null
+++ b/muse2/doc/pdf/developer_docs.pdf
diff --git a/muse2/doc/documentation.pdf b/muse2/doc/pdf/documentation.pdf
index e14767da..6caa08cf 100644
--- a/muse2/doc/documentation.pdf
+++ b/muse2/doc/pdf/documentation.pdf
diff --git a/muse2/muse/help.cpp b/muse2/muse/help.cpp
index 4bce3a16..e371a6cf 100644
--- a/muse2/muse/help.cpp
+++ b/muse2/muse/help.cpp
@@ -23,6 +23,7 @@
 
 #include <unistd.h>
 #include <stdlib.h>
+#include <stdio.h>
 
 #include <QDesktopServices>
 #include <QMessageBox>
@@ -34,6 +35,9 @@
 #include "icons.h"
 #include "aboutbox_impl.h"
 
+// Whether to open the pdf or the html
+#define MUSE_USE_PDF_HELP_FILE
+
 namespace MusEGui {
 
 //---------------------------------------------------------
@@ -43,16 +47,44 @@ namespace MusEGui {
 void MusE::startHelpBrowser()
       {
       QString lang(getenv("LANG"));
-      QString museHelp = DOCDIR + QString("/html/index_") + lang + QString(".html");
-      if (access(museHelp.toLatin1(), R_OK) != 0) {
-            museHelp = DOCDIR + QString("/html/index.html");
-            if (access(museHelp.toLatin1(), R_OK) != 0) {
-                  QString info(tr("no help found at: "));
-                  info += museHelp;
-                  QMessageBox::critical(this, tr("MusE: Open Help"), info);
-                  return;
-                  }
+      QString museHelp;
+      bool pdffound = false;
+      
+#ifdef MUSE_USE_PDF_HELP_FILE
+      museHelp = DOCDIR + QString("/muse_pdf/documentation_") + lang + QString(".pdf");
+      if (access(museHelp.toLatin1(), R_OK) != 0)
+      {
+            museHelp = DOCDIR + QString("/muse_pdf/documentation.pdf");
+            if (access(museHelp.toLatin1(), R_OK) != 0)
+            {
+                  //QString info(tr("no help found at: "));
+                  //info += museHelp;
+                  //info += tr("\nTrying HTML file instead...\n");
+                  //QMessageBox::critical(this, tr("MusE: Open Help"), info);
+                  fprintf(stderr, "MusE::startHelpBrowser() no help found at:%s\nTrying HTML file instead...",
+                          museHelp.toLatin1().constData());
             }
+            else
+              pdffound = true;
+      }
+      else
+        pdffound = true;
+#endif            
+
+      if(!pdffound)
+      {
+        museHelp = DOCDIR + QString("/muse_html/single/documentation/index_") + lang + QString(".html");
+        if (access(museHelp.toLatin1(), R_OK) != 0) {
+              museHelp = DOCDIR + QString("/muse_html/single/documentation/index.html");
+              if (access(museHelp.toLatin1(), R_OK) != 0) {
+                    QString info(tr("no help found at: "));
+                    info += museHelp;
+                    QMessageBox::critical(this, tr("MusE: Open Help"), info);
+                    return;
+                    }
+              }
+      }
+      
       launchBrowser(museHelp);
       }
 
diff --git a/muse2/muse/widgets/canvas.cpp b/muse2/muse/widgets/canvas.cpp
index 326992eb..b5df2494 100644
--- a/muse2/muse/widgets/canvas.cpp
+++ b/muse2/muse/widgets/canvas.cpp
@@ -3,7 +3,7 @@
 //  Linux Music Editor
 //    $Id: canvas.cpp,v 1.10.2.17 2009/05/03 04:14:01 terminator356 Exp $
 //  (C) Copyright 1999 Werner Schweer (ws@seh.de)
-//  Additions, modifications (C) Copyright 2011 Tim E. Real (terminator356 on users DOT sourceforge DOT net)
+//  Additions, modifications (C) Copyright 2011-2013 Tim E. Real (terminator356 on users DOT sourceforge DOT net)
 //
 //  This program is free software; you can redistribute it and/or
 //  modify it under the terms of the GNU General Public License
diff --git a/muse2/muse/widgets/canvas.h b/muse2/muse/widgets/canvas.h
index d6859a14..06fcd0a6 100644
--- a/muse2/muse/widgets/canvas.h
+++ b/muse2/muse/widgets/canvas.h
@@ -3,7 +3,7 @@
 //  Linux Music Editor
 //    $Id: canvas.h,v 1.3.2.8 2009/02/02 21:38:01 terminator356 Exp $
 //  (C) Copyright 1999 Werner Schweer (ws@seh.de)
-//  Additions, modifications (C) Copyright 2011 Tim E. Real (terminator356 on users DOT sourceforge DOT net)
+//  Additions, modifications (C) Copyright 2011-2013 Tim E. Real (terminator356 on users DOT sourceforge DOT net)
 //
 //  This program is free software; you can redistribute it and/or
 //  modify it under the terms of the GNU General Public License
diff --git a/muse2/share/CMakeLists.txt b/muse2/share/CMakeLists.txt
index 3d05e10c..26e011f6 100644
--- a/muse2/share/CMakeLists.txt
+++ b/muse2/share/CMakeLists.txt
@@ -25,7 +25,6 @@
 #       are scanned before coming to share/locale
 subdirs(
       drummaps
-      html
       instruments
       plugins
       pybridge
diff --git a/muse2/share/html/CMakeLists.txt b/muse2/share/html/CMakeLists.txt
deleted file mode 100644
index b9417ad1..00000000
--- a/muse2/share/html/CMakeLists.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-#=============================================================================
-#  MusE
-#  Linux Music Editor
-#  $Id:$
-#
-#  Copyright (C) 1999-2011 by Werner Schweer and others
-#
-#  This program is free software; you can redistribute it and/or modify
-#  it under the terms of the GNU General Public License
-#  as published by the Free Software Foundation; either version 2
-#  of the License, or (at your option) any later version.
-#
-#  This program is distributed in the hope that it will be useful,
-#  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#  GNU General Public License for more details.
-#
-#  You should have received a copy of the GNU General Public License
-#  along with this program; if not, write to the
-#  Free Software Foundation, Inc.,
-#  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-#=============================================================================
-
-file (GLOB html_files
-      *.css
-      *.html
-      *.jpg
-      toc_.txt
-      )
-
-install( FILES ${html_files}
-      DESTINATION ${MusE_DOC_DIR}/html
-      )
diff --git a/muse2/share/html/COPYING.html b/muse2/share/html/COPYING.html
deleted file mode 100644
index 8c84ced7..00000000
--- a/muse2/share/html/COPYING.html
+++ /dev/null
@@ -1,353 +0,0 @@
-<qt>
-<pre>
- Note that the GPL below is copyrighted by the Free Software
- Foundation, but the instance of code that it refers to (the
- MusE music editor) is copyrighted by me and others who 
- actually wrote it.
-
-			Werner Schweer
-
-----------------------------------------
-
-		    GNU GENERAL PUBLIC LICENSE
-		       Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
-                       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-			    Preamble
-
-  The licenses for most software are designed to take away your
-freedom to share and change it.  By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users.  This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
-  To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have.  You must make sure that they, too, receive or can get the
-source code.  And you must show them these terms so they know their
-rights.
-
-  We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
-  Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software.  If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
-  Finally, any free program is threatened constantly by software
-patents.  We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary.  To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-		    GNU GENERAL PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License.  The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language.  (Hereinafter, translation is included without limitation in
-the term "modification".)  Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope.  The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
-  1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
-  2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-    a) You must cause the modified files to carry prominent notices
-    stating that you changed the files and the date of any change.
-
-    b) You must cause any work that you distribute or publish, that in
-    whole or in part contains or is derived from the Program or any
-    part thereof, to be licensed as a whole at no charge to all third
-    parties under the terms of this License.
-
-    c) If the modified program normally reads commands interactively
-    when run, you must cause it, when started running for such
-    interactive use in the most ordinary way, to print or display an
-    announcement including an appropriate copyright notice and a
-    notice that there is no warranty (or else, saying that you provide
-    a warranty) and that users may redistribute the program under
-    these conditions, and telling the user how to view a copy of this
-    License.  (Exception: if the Program itself is interactive but
-    does not normally print such an announcement, your work based on
-    the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole.  If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works.  But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-  3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
-    a) Accompany it with the complete corresponding machine-readable
-    source code, which must be distributed under the terms of Sections
-    1 and 2 above on a medium customarily used for software interchange; or,
-
-    b) Accompany it with a written offer, valid for at least three
-    years, to give any third party, for a charge no more than your
-    cost of physically performing source distribution, a complete
-    machine-readable copy of the corresponding source code, to be
-    distributed under the terms of Sections 1 and 2 above on a medium
-    customarily used for software interchange; or,
-
-    c) Accompany it with the information you received as to the offer
-    to distribute corresponding source code.  (This alternative is
-    allowed only for noncommercial distribution and only if you
-    received the program in object code or executable form with such
-    an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it.  For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable.  However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-  4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-  5. You are not required to accept this License, since you have not
-signed it.  However, nothing else grants you permission to modify or
-distribute the Program or its derivative works.  These actions are
-prohibited by law if you do not accept this License.  Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
-  6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions.  You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
-  7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all.  For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices.  Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-  8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded.  In such case, this License incorporates
-the limitation as if written in the body of this License.
-
-  9. The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number.  If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation.  If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
-  10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission.  For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this.  Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
-			    NO WARRANTY
-
-  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
-  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
-		     END OF TERMS AND CONDITIONS
-
-	    How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) 19yy  <name of author>
-
-    This program is free software; you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation; either version 2 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program; if not, write to the Free Software
-    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-    Gnomovision version 69, Copyright (C) 19yy name of author
-    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary.  Here is a sample; alter the names:
-
-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-  `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
-  <signature of Ty Coon>, 1 April 1989
-  Ty Coon, President of Vice
-
-This General Public License does not permit incorporating your program into
-proprietary programs.  If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library.  If this is what you want to do, use the GNU Library General
-Public License instead of this License.
-</pre>
-</qt>
diff --git a/muse2/share/html/button_bar.jpg b/muse2/share/html/button_bar.jpg
deleted file mode 100644
index 204328c8..00000000
--- a/muse2/share/html/button_bar.jpg
+++ /dev/null
diff --git a/muse2/share/html/getting_started.html b/muse2/share/html/getting_started.html
deleted file mode 100644
index 0d6c4344..00000000
--- a/muse2/share/html/getting_started.html
+++ /dev/null
@@ -1,89 +0,0 @@
-<qt bgcolor="#f4f4c8" title="MusE - The Linux (Midi) Music Editor">
-<center><h1>MusE - The Linux (Midi) Music Editor</h1></center>
-
-<h2>5. Getting Started</h2>
-<p>
-<h2>5.1 Creating A New Song</h2>
-<p>
-Here's a very short tutorial on how to create a new song from scratch.
-
-<p>
-
-<ol>
-  <li> Start MusE with the name of a new song (ie. a filename that doesn't
-already exist):
-<pre>
-	muse blues1.med
-</pre>
-Alternatively, start MusE and select <tt>File-&gt;New</tt>.  The default song
-name is <tt>default</tt> and the first time you select <tt>File-&gt;Save</tt>,
-MusE asks you for a real name.
-
-  <li> Select a song type from the <tt>Type</tt> pulldown menu in the
-Toolbar.  This selects the capabilities of your MIDI hardware (either
-NO, GM, GS, or XG).
-
-  <li> Doubleclick on the first empty track to create a new track.
-  <li> Select the MIDI channel for the new track; click with the right mouse
-button on Ch column in the track list to increment channel nummber, click
-with middle mouse button to decrement.
-  <li> If the TrackInfo window is not visible, press TrackInfo.
-  <li> Select a MIDI instrument for the MIDI channel of your new track.
-  <li> Click with the middle mouse button on ruler to set left locator mark.
-  <li> Click with the right mouse button on the ruler to set right locator mark.
-<b>Note:</b> The right mark must be set to the right of the left mark.
-  <li> Double click between the left and right locators on first track to
-create a new part, <b>or</b> select the Pencil tool and draw with the left
-mouse button pressed to create a new part.
-</ol>
-
-<p>
-<h2>5.2 Recording Events</h2>
-<p>
-<b>Entering Notes Manually</b>
-
-<ol>
-  <li> Select Pointer tool from toolbar 
-  <li> Double click on part in part canvas to start the pianoroll editor 
-  <li> Select Pencil tool from toolbar in the pianoroll editor 
-  <li> Now you can draw events into the event canvas 
-</ol>
-
-<p>
-<b>Play The Notes</b>
-
-<ol>
-  <li> Click with middle mouse button on ruler to set left locator mark 
-  <li> Click with right mouse button on ruler to set right locator mark
-  <li> Note: right mark must be set right to left mark 
-  <li> Click with left mouse button on ruler to set current position between left and right locator 
-  <li> Select "loop" in the transport toolbar 
-  <li> Press play to start sequencer 
-  <li> You can enter new notes while the sequencer is playing 
-</ol>
-
-<p>
-<b>Some Hints</b>
-
-<ol>
-  <li> You can "play" in realtime on the piano keyboard on the left side of the pianoroll editor 
-  <li> You can change Channel Info and Track Info values during play 
-</ol>
-
-<p>
-<h2>5.3 Step Recording</h2>
-<p>
-<ol>
-  <li> Start the pianoroll editor 
-  <li> Click with left mouse button on ruler to set current position to the start position of your recording 
-  <li> Set the Snap value to the step distance 
-  <li> Set the Quantize value to the length of the notes to record 
-  <li> Enter step record mode by pressing the "S" toolbar button 
-  <li> Every click on the piano keyboard records a note with "Quantize" len and advances the current record position to
-  <li> The next "Snap" position 
-  <li> Shift+click records a note without advancing the current record position 
-  <li> Change the current position with the cursor keys 
-  <li> Shift+space inserts a gap; all notes to the right of the current position move to the next snap position 
-</ol>
-
-</qt>
diff --git a/muse2/share/html/index.html b/muse2/share/html/index.html
deleted file mode 100644
index c2e5b6a7..00000000
--- a/muse2/share/html/index.html
+++ /dev/null
@@ -1,66 +0,0 @@
-<html>
-<center><h1>MusE - The Linux Music Editor</h1></center>
-<p>
-<h2>About MusE</h2>
-
-MusE is a multitrack virtual studio for Linux that has support
-for sequencing of both midi and audio and has, among other things,
-support for LADSPA, Jack and ALSA. <br>
-MusE is written by Werner Schweer and others and is published under the
-<a href="COPYING.html"> GNU General Public License</a>.
-The latest release of MusE and the <b>up2date documentation</b> can be found at the MusE hompage:
-<a href="http://www.muse-sequencer.org/">http://www.muse-sequencer.org/</a>.
-<br>
-<br>
-This is the old manual of the 0.6.3 release but there is already a new one in development, try this:
-<a href="http://www.muse-sequencer.org/wiki/index.php/Manual">http://www.muse-sequencer.org/wiki/index.php/Manual</a>
-
-<p>
-<h2>1. Introduction (still to be written)</h2>
-
-<p>
-<h2>2. <a href="installation.html">Installation</a></h2>
-<ul>
-  <li>2.1 How to Obtain MusE
-  <li>2.2 System Requirements
-  <li>2.3 Compiliation and Installation
-</ul>
-
-<p>
-<h2>3. <a href="invocation.html">Invoking MusE</a></h2>
-<ul>
-  <li>3.1 Invoking MusE
-  <li>3.2 Command Line Options
-  <li>3.3 File Types Recognized by MusE
-</ul>
-
-<p>
-<h2>4. <a href="window_ref.html">Window Reference Guide</a></h2>
-<ul>
-  <li>4.1 The Main Window
-  <li>4.2 The Arranger
-  <li>4.2.1 The Left Pane
-  <li>4.2.1.1 Track Info
-  <li>4.2.2 The Right Pane
-
-  <li>4.3 The Button Bar &amp; Menus
-</ul>
-
-<p>
-<h2>5. <a href="getting_started.html">Getting Started</a></h2>
-<ul>
-  <li>5.1 Creating A New Song
-  <li>5.2 Recording Events
-  <li>5.3 Step Recording
-</ul>
-
-<p>
-<h2>6. Mixer Automation (still to be written)</h2>
-<ul>
-  <li>6.1 Record Automation Events (still to be written)
-</ul>
-
-
-<p>
-<h2>Glossary (still to be written)</h2>
-</html>
diff --git a/muse2/share/html/installation.html b/muse2/share/html/installation.html
deleted file mode 100644
index 19527333..00000000
--- a/muse2/share/html/installation.html
+++ /dev/null
@@ -1,64 +0,0 @@
-<qt bgcolor="#f4f4c8" title="MusE - The Linux (Midi) Music Editor">
-<center><h1>MusE - The Linux (Midi) Music Editor</h1></center>
-
-<h2>2. Installation</h2>
-<p>
-<h2>2.1 How to Obtain MusE</h2>
-MusE is available at the MusE Homepage, located at
-<a href="http://www.muse-sequencer.org/">http://www.muse-sequencer.org/</a>.
-Download the latest non-beta release and follow the
-installation instructions below.
-
-<h2>2.2 System Requirements</h2>
-To run MusE on your workstation, the following conditions must be met:
-<ul>
-  <li>A GNU/Linux distribution (Red Hat, Debian, etc.)
-  <li>A working windowing system (most likely X Windows)
-  <li>qt 2.2 (<a href="http://www.trolltech.com/products/qt">http://www.trolltech.com/products/qt</a>)
-  <li>gcc 2.95.2 (<a href="http://www.gnu.org/software/gcc/gcc.html">http://www.gnu.org/software/gcc/gcc.html</a>)
-  <li>glibc 2.1 (<a href="http://ftp.gnu.org/gnu/glibc">http://ftp.gnu.org/gnu/glibc</a>)
-  <li>Linux kernel configured with RealTimeClock support (<tt>/dev/rtc</tt>)
-  <li>ALSA (Advanced Linux Sound Architecture) 0.5.9c (it should work with standard OSS drivers as well)
-  <li>an external midi device
-</ul>
-
-<h2>2.3 Compiliation and Installation</h2>
-Unpack the newly-downloaded tarball into a directory and edit
-the file <tt>make.inc</tt>.
-<p>
-The most important variables to set in this file are:
-<ul>
-  <li>QTDIR
-  <li>ALSA
-  <li>OSS
-</ul>
-
-Point <tt>QTDIR</tt> to where your QT libraries are installed.
-<tt>ALSA</tt> and <tt>OSS</tt> are boolean values (ie. <tt>yes</tt>
-or <tt>no</tt>) that tell MusE how to handle Midi and Audio on your
-system.  It is safe to say <tt>yes</tt> to both.
-<p>
-A sample config:
-<p>
-<pre>
-	QTDIR = /usr/local/qt
-	ALSA = no
-	OSS = yes
-</pre>
-
-<p>
-When done, save <tt>make.inc</tt> and run the following commands:
-<pre>
-	make depend
-	make
-	make install
-</pre>
-
-<p>
-Note that <tt>make install</tt> will ask for the <tt>root</tt> password,
-as MusE is installed as a setuid-root binary.  Setuid-root is needed to allow
-MusE to get proper timing functions from the Linux kernel.
-<p>
-<b>Hint:</b> To get even better timing than that, run MusE with the -R option.
-
-</qt>
diff --git a/muse2/share/html/invocation.html b/muse2/share/html/invocation.html
deleted file mode 100644
index 778422c2..00000000
--- a/muse2/share/html/invocation.html
+++ /dev/null
@@ -1,54 +0,0 @@
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-   <title>MusE: Linux Music Editor</title>
-   <link rel="stylesheet" type="text/css" href="styles.css">
-</head>
-
-<body>
-<center><h1>MusE - The Linux (Midi) Music Editor</h1></center>
-
-<h2>3. Invoking MusE</h2>
-<p>
-<h2>3.1 Invoking MusE</h2>
-MusE is invoked from the command line by typing in:
-<pre>
-	<tt>muse</tt>
-</pre>
-
-Optionally, you can use command line options of the form:
-
-<pre>
-	muse &lt;options&gt; &lt;midifile&gt;
-</pre>
-
-&lt;options&gt; : see section 3.2 below for details on options.
-&lt;midifile&gt; can be either a standard MIDI file or a MusE
-file (*.med, *.med.gz or *.med.bz2).
-
-<h2>3.2 Command Line Options</h2>
-<p>
-MusE accepts some options as listed below:
-<pre>
-   -v  print version
-   -d  debug mode: no threads
-   -D  debug mode: enable some debug messages
-   -m  debug mode: trace midi Input
-   -M  debug mode: trace midi Output
-   -s  debug mode: trace sync
-   -R  enable real time scheduling
-</pre>
-
-<h2>3.3 File Types Recognized by MusE</h2>
-<p>
-<table border=1 cellpadding=5>
-<tr><td><tt>~/.MusE<td>MusE Configuration File ("~" refers to your home directory)
-<tr><td><tt>.musePrj<td>Hidden Project File; stores list of last projects
-<tr><td><tt>*.med<td>MusE song file; internal MusE format
-<tr><td><tt>*.mid<td>midi file; can be imported
-<tr><td><tt>*.kar<td>karaoke: midi file with additional information; some types can be imported
-</table>
-<p>
-With adding the additional extensions <tt>.gz</tt> or <tt>.bz2</tt>
-you can read or write compressed files.
-
-</qt>
diff --git a/muse2/share/html/left_pane.jpg b/muse2/share/html/left_pane.jpg
deleted file mode 100644
index a659e1ee..00000000
--- a/muse2/share/html/left_pane.jpg
+++ /dev/null
diff --git a/muse2/share/html/main_window.jpg b/muse2/share/html/main_window.jpg
deleted file mode 100644
index eee1e43f..00000000
--- a/muse2/share/html/main_window.jpg
+++ /dev/null
diff --git a/muse2/share/html/main_window_track_info.jpg b/muse2/share/html/main_window_track_info.jpg
deleted file mode 100644
index d4dc207c..00000000
--- a/muse2/share/html/main_window_track_info.jpg
+++ /dev/null
diff --git a/muse2/share/html/right_pane.jpg b/muse2/share/html/right_pane.jpg
deleted file mode 100644
index a770a4e8..00000000
--- a/muse2/share/html/right_pane.jpg
+++ /dev/null
diff --git a/muse2/share/html/styles.css b/muse2/share/html/styles.css
deleted file mode 100644
index 53026fa1..00000000
--- a/muse2/share/html/styles.css
+++ /dev/null
@@ -1,85 +0,0 @@
-:link     { color: #091cef; }
-:visited  { color: #091cef; }
-
-body  {
-   background: #eeeeee;
-   color: #00;
-   font-family: Arial, Geneva;
-   font-size: 10pt;
-   }
-h1.head {
-   margin: 0.05em 0.3em;
-   font-family: Arial, helvetica, sans-serif;
-   color: #091cef;
-   }
-td.head {
-   background: #aeb3e8;
-   color: #091cef;
-   }
-td.nav {
-   background: #aeb3e8;
-   color: #000;
-   }
-td.ld {
-   background: #aeb3e8;
-   valign: top;
-   width: 60;
-   font-weight: bold;
-   }
-td.lh {
-   background: #aeb3e8;
-   }
-td.lb {
-   background: #ced1e2;
-   }
-
-h3.navhead {
-   margin-top: 0.2em;
-   margin-bottom: 0em;
-   font-size: small;
-   font-family: Verdana, Geneva, Arial, sans-serif;
-   }
-
-.navlink {
-   font-size: small;
-   font-family: Verdana, Geneva, Arial, sans-serif;
-   }
-
-p, input {
-	font-family: Arial, Geneva;
-	font-size: 10pt;
-}
-
-b {
-	font-family: Arial, Geneva;
-	font-size: 10pt;
-	font-weight: bold;
-}
-
-h1 {
-	font-family: Arial, Geneva;
-	font-size: 24pt;
-	font-weight: bold;
-}
-h2 {
-	font-family: Arial, Geneva;
-	font-size: 18pt;
-	font-weight: bold;
-}
-
-a {
-	font-family: Arial, Geneva;
-	font-size: 12pt;
-}
-
-th {
-	font-family: Arial, Geneva;
-	font-size: 10pt;
-
-}
-
-td {
-      font-family: Arial, Geneva;
-	font-size: 12pt;
-      color: #000000;
-      }
diff --git a/muse2/share/html/toc_.txt b/muse2/share/html/toc_.txt
deleted file mode 100644
index d8503ff4..00000000
--- a/muse2/share/html/toc_.txt
+++ /dev/null
@@ -1,13 +0,0 @@
-"Glossary" "glossary.html"
-"Getting Started" "getting_started.html"
-+"Window Reference Guide" "window_ref.html"
- +"The Arranger"    "window_ref.html"
-  "The Button Bar & Menus" "window_ref.html"
-  "The Right Pane" "window_ref.html"
-  +"The Left Pane"  "window_ref.html"
-   "Track Info"    "window_ref.html"
- "The Main Window" "window_ref.html"
-"Invoking MusE"  "invocation.html"
-"Installation"   "installation.html"
-"Introduction"   "introduction.html"
-"Index"          "index.html"
diff --git a/muse2/share/html/track_info.jpg b/muse2/share/html/track_info.jpg
deleted file mode 100644
index 89834d71..00000000
--- a/muse2/share/html/track_info.jpg
+++ /dev/null
diff --git a/muse2/share/html/window_ref.html b/muse2/share/html/window_ref.html
deleted file mode 100644
index 549e88d3..00000000
--- a/muse2/share/html/window_ref.html
+++ /dev/null
@@ -1,180 +0,0 @@
-<qt bgcolor="#f4f4c8" title="MusE - The Linux (Midi) Music Editor">
-<center><h1>MusE - The Linux (Midi) Music Editor</h1></center>
-
-<h2>4. Window Reference Guide</h2>
-<p>
-<h2>4.1 The Main Window</h2>
-Here's a screenshot of the main window, with a standard MIDI file already
-loaded:
-<p>
-<img src="main_window.jpg"</img>
-
-<p>
-The main window is basically divided up into two panes separated by a
-veritcal bar that is movable horizontally.  These two panes together
-are called the Arranger.
-
-<h2>4.2 The Arranger</h2>
-<p>
-The left pane of the Arranger describes each track in detail,
-while the right pane describes each track graphically.
-
-<h3>4.2.1 The Left Pane</h3>
-<img src="left_pane.jpg"</img>
-<p>
-The left pane details the following information for each track:
-<ul>
-  <li>A -??
-  <li>M - Mute the track
-  <li>C - Defines whether the track is one of MIDI, Drum or Wave.
-  <li>Track - A freely-editable track name.
-  <li>Ch - Defines which MIDI Channel this track plays on.
-  <li>Port - Defines which MIDI port this track plays on.
-  <li>T -??
-</ul>
-
-You can select which track is currently "active" by simply clicking
-on the track.
-<p>
-When a track's M column is clicked, that track is marked as Muted with
-a red circle and upon playback that track will not be heard.  To hear
-the track, click on the M column for that track again.
-<p>
-Right click on the C column for a track to declare the track to be of
-type MIDI, Drum or Wave.
-<p>
-The Track column is free-form, meaning that a double-click on a track's
-Track column will allow you to enter a descriptive name for the track,
-for example "Hot Lead Guitar".
-<p>
-The Ch column for a track is changed by right-clicking to increment the
-number or middle-clicking to decrement the number.  It's generally a
-good idea to keep differing instruments on different MIDI channels and it's
-considered common to have the drum kit on channel 10.
-<p>
-<h4>4.2.1.1 Track Info</h4>
-<p>
-At the bottom of the left pane, you'll see a little button labelled
-"TrackInfo".  When clicked, the standard information plus more about
-the currently selected track is presented:
-<p>
-<img src="track_info.jpg"</img>
-<ul>
-  <li>Track Name
-  <li>Channel
-  <li>Transpose
-  <li>Delay
-  <li>Length
-  <li>Velocity
-  <li>Compr
-</ul>
-The bottom half of the TrackInfo display describes MIDI channel information:
-<ul>
-  <li>MIDI Instrument
-  <li>H-Bank
-  <li>L-Bank
-  <li>Progr
-  <li>Volume
-  <li>Pan
-</ul>
-
-<p>
-Operations that can be performed on the left pane:
-<table border=1>
-<th> <strong>Track Functions </strong></th> <th>&nbsp;</th>
-<tr><td>Select Track<td>
-  <ul>
-    <li>Left Mouse Button
-  </ul>
-<tr><td>Select multiple Tracks<td>
-  <ul>
-    <li>Shift + Left Mouse Button
-  </ul>
-<tr><td>Change Selected Track<td>
-  <ul>
-    <li>Key Up: previous Track
-    <li>Key Down: next Track
-    <li>click with left mouse button in name field
-  </ul>
-<tr><td>Move Track<td>
-  <ul>
-    <li>Drag with left Mouse Button
-  </ul>
-<tr><td>Create New Track<td>
-  <ul>
-    <li>Pulldown Edit<br>
-    <li>Ctrl T
-    <li>double click in empty track
-  </ul>
-<tr><td>Delete selected Track(s)<td>
-  <ul>
-    <li>Pulldown Edit
-    <li>Del
-  </ul>
-<tr><td>Rename Track<td>
-  <ul>
-    <li>doubleClick with left mouse button
-        on track name
-  </ul>
-<tr><td>Change Midi Channel<td>
-  <ul>
-    <li> left mouse button increments midi channel
-    <li> middle mouse button decrements midi channel
-  </ul>
-<tr><td>Select Midi Port<td>
-  <ul>
-    <li> click with right mouse button on portname;
-         select from pulldown menu
-  </ul>
-<tr><td>Mute Track<td>
-  <ul>
-    <li> click with left mouse button on "M" field in
-         Tracklist
-  </ul>
-<tr><td>Solo Track<td>
-  <ul>
-    <li> click "Solo" button
-  </ul>
-</table>
-
-
-<h2>4.2.2 The Right Pane</h2>
-<img src="right_pane.jpg"</img>
-<p>
-The right pane desribes each track graphically.  Time moves from left
-to right and is measured in beats that are referenced at the top of
-the right pane.  Tracks are displayed vertically in boxes, called
-"Parts", that depict where MIDI and audio data are played.
-<p>
-The small sliders that are adjacent to the bottom right corner affect
-the view of the right pane in terms of "zooming".  The vertical slider
-affects the height of the tracks, while the horizontal slider affects
-the width.
-<p>
-Operations that can be performed on the right pane:
-<p>
-<table border=1>
-<tr><td><b>To do this...</b><td><b>...Do this</b>
-<tr><td>Select Part<td>Left Click
-<tr><td>Select multiple parts<td>Shift + left click
-<tr><td>Change selected track<td>Key left: previous part, Key right: next part
-<tr><td>Move part<td>Drag with left mouse button
-<tr><td>Create new part<td>select Pencil tool; draw with left mouse button pressed, OR set left and right mark; double click on track
-<tr><td>Delete selected part(s)<td>select rubber tool; click part to delete
-<tr><td>Rename part<td>double click with left mouse button on part
-<tr><td>Copy part<td>drag with shift + left mouse button
-<tr><td>Cut part<td>select Cut Tool; click on part to cut
-<tr><td>Glue part<td>select Glue Tool; click on part to glue with next part
-</table>
-<p>
-
-<h2>4.2.3 The Button Bar &amp; Menus</h2>
-<img src="button_bar.jpg"</img>
-<p>
-Across the top, above the Arranger, are a menu system, icons and other
-widgets that you use to manipulate your project.  Most of these are
-self-explanatory, while others are described later in this document.
-
-
-
-</qt>
author	Tim E. Real <termtech@rogers.com>	2013-02-22 06:46:23 +0000
committer	Tim E. Real <termtech@rogers.com>	2013-02-22 06:46:23 +0000
commit	48b9d2ea9961f935bacabc75a2fbd5cc141010ae (patch)
tree	37512a1feed9d02145e0e52f0c96e5fe42a83f62
parent	2d1fc0416a2d8611659a4f630fbc5719f35b694d (diff)