Update of /project/gsharp/cvsroot/gsharp/Doc In directory common-lisp.net:/tmp/cvs-serv6768

Modified Files: commands.tex gsharp.tex plans.tex release-notes.tex Log Message: Updated the `getting started' to reflect the new and altered commands for staves and layers.

Updated the command summary in the reference manual for the same reason.

Added items to the release notes to reflect user-visible changes.

Removed and modified some items in the `future plans' section to reflect some improvements already made.

At some point in the future, I need to update the `internals' part to reflect the existence of lyrics, etc., but since the way it is implemented might change some, there is no point in doing that right now.

Date: Fri Jul 23 23:41:55 2004 Author: rstrandh

Index: gsharp/Doc/commands.tex diff -u gsharp/Doc/commands.tex:1.3 gsharp/Doc/commands.tex:1.4 --- gsharp/Doc/commands.tex:1.3 Sun Jul 18 23:23:53 2004 +++ gsharp/Doc/commands.tex Fri Jul 23 23:41:54 2004 @@ -114,21 +114,23 @@ \hline \end{tabular}

-\section{Operations on the current layer} +\section{Operations on layers}

\begin{tabular}{|l|l|l|} \hline Key & Command name & Description\ \hline -\kbd{Meta-n} & Next Layer & Make the next layer current\ -\kbd{Meta-p} & Previous Layer & Make the previous layer current\ - & Insert Layer After & Insert new layer after current\ - & Insert Layer Before & Insert new layer before current\ - & Delete Layer & Delete the current layer\ - & Add Layer Staff & Adds a new staff to the layer\ - & & (promts for a name of an existing staff)\ - & Delete Layer Staff & Deletes a staff from the layer\ - & & (promts for a name of an existing staff)\ + & Select Layer & Prompts for a new current lsyer\ + & Rename Layer & Prompts for a layer and a new name\ + & Add Layer & Prompts for a name and an initial\ + & & staff for the new layer. The type\ + & & of the new layer is determined by\ + & & the type of the initial staff.\ + & Delete Layer & Prompts for a layer to delete\ + & Rotate Staves & If they layer is displayed on \ + & & multiple staves, rotate them so\ + & & that a different one becomes the\ + & & current one.\ \hline \end{tabular}

@@ -136,22 +138,22 @@

\begin{tabular}{|l|l|l|} \hline -Key & Command name & Description\ +Key & Command name & Description\ \hline - & Add Staff After & Add a new staff after an existing one\ - & & (prompts for the existing staff, \ - & & for the name and the type of the new staff, \ - & & and a clef and a line for the clef\ - & & if type is \texttt{fiveline})\ - & Add Staff Before & Add a new before after an existing one\ - & & (prompts for the existing staff, \ - & & for the name and the type of the new staff, \ - & & and a clef and a line for the clef\ - & & if type is \texttt{fiveline})\ - & Delete Staff & Delete a staff (promts for staff to delete)\ - & Rename Staff & Rename current staff (prompts for a new name)\ - & Set clef & Set the clef of the current staff\ - & & (promts for name of clef and line number)\ + & Insert Staff After & Add a new staff after an existing one\ + & & (prompts for the existing staff, \ + & & for the name and the type of the new staff, \ + & & and a clef and a line for the clef\ + & & if type is \texttt{fiveline})\ + & Insert Staff Before & Add a new before after an existing one\ + & & (prompts for the existing staff, \ + & & for the name and the type of the new staff, \ + & & and a clef and a line for the clef\ + & & if type is \texttt{fiveline})\ + & Delete Staff & Delete a staff (promts for staff to delete)\ + & Rename Staff & Rename current staff (prompts for a new name)\ + & Set clef & Set the clef of the current staff\ + & & (promts for name of clef and line number)\ \kbd{Meta-#} & More Sharps & removes a flat or adds a sharp to the key signature\ \kbd{Meta-@} & More Flats & removes a sharp or adds a flat to the key signature\ \hline

Index: gsharp/Doc/gsharp.tex diff -u gsharp/Doc/gsharp.tex:1.3 gsharp/Doc/gsharp.tex:1.4 --- gsharp/Doc/gsharp.tex:1.3 Fri Apr 2 09:13:35 2004 +++ gsharp/Doc/gsharp.tex Fri Jul 23 23:41:54 2004 @@ -121,12 +121,41 @@ You should be seeing a main window (known as a \emph{frame}) with a menu bar and four sub-windows, known as \emph{panes}.

+\subsection{The score pane} +\label{sec-score-pane} + The largest pane is the \emph{score pane}\index{score - pane}\index{pane!score|)} where you will do most of the editing, + pane}\index{pane!score|)} where you will do most of the editing, + +When prompted for some item on display in the score pane, you can +usually click on it. For instance, if you have issued a command that +operates on a particular staff, you can usually click on a visual +representation of the staff in the score pane to satisfy the request +for the staff. + +\subsection{The command pane} +label{sec-command-pane}

The pane at the bottom is a {\clim} \emph{command pane}\index{command pane}\index{pane!command|)}. In it, you can type -commands that do not have keyboard shortcuts. +commands that do not have keyboard shortcuts. + +The command pane is also where you get prompted for arguments to +various {\gs} commands. In those cases, you usually have a choice +between clicking on a visual representation of the argument you would +like to supply as mentioned in section \ref{sec-score-pane}, or to +type some textual representation of it directly at the prompt. + +When typing some textual representation of some existing object, such +as the name of a layer or of a staff, you can usually use +\emph{completion}\index{completion}, which means that you can type a +unique prefix of the text and then use the \kbd{TAB} key to get {\gs} +to fill in the rest. Using completion after having issued a command +in the command pane is usually faster (provided you have some idea of +what the textual representation is) than to grab the mouse and click +on the object in the score pane. + +\subsection{Other panes}

In the upper-right corner, you will see a the pane that determines the \emph{input state}\index{input state}\index{pane!input state|)} @@ -364,31 +393,177 @@ \chapter{Operations on measures}

You add a measure bar at the cursor location by typing \kbd{|}. As - with other element, the cursor will be positioned right after the - newly created measure bar. In fact, a measure bar is just like any - other element as far as editing operations are concerned. +with other element, the cursor will be positioned right after the +newly created measure bar. In fact, a measure bar is just like any +other element as far as editing operations are concerned.

Thus, to delete a measure bar, you simply use the ordinary commands for erasing or deleting elements.

+\chapter{Operations on staves} +\label{chap-op-staves} + +Initially, when {\gs} starts up, there is a single staff on display. +It is a standard five-line staff with a treble clef on staff step 2 +(we count the bottom line of the staff as staff step 0). + +\section{Renaming and existing staff} + +Staves have unique names in {\gs}. Initially, the name of the first +staff on display is some default name such as ``default staff''. You +typically want to use names of staves that suggest the kind of musical +material displayed on it, such as ``Trumpets'' or ``Piano right +hand'', etc. + +You can give a different name to an existing staff by issuing the +command \command{Rename Staff}, either from a menu or form the command +pane. This command prompts for a staff to rename and a new name for +the staff. At the prompt for the staff to rename, you have a choice +of clicking on a staff on display as indicated in section +\ref{sec-score-pane}, or typing its name in the command pane possibly +with \emph{completion}\index{completion} as indicated in section +\ref{sec-score-pane}. Renaming a staff is such an infrequent +operation that there is no keyboard shortcut for it. + +\section{Inserting a new staff} +\label{sec-inserting-staff} + +Unless you are writing some very simple music, or a part for a +monophonic instrument, you probably want to be able to add new staves +to the score. Because adding new staves are done fairly infrequently, +there is no keyboard shortcut for doing it. Instead, you have to +issue one of the commands for doing this either by typing it (with +completion, see \ref{sec-command-pane}) in the command pane or using +the mouse to select one from a menu. + +{\gs} imposes an \emph{order} on the staves of a score. This order is +the one used to display the staves from top to bottom. There are two +commands available for inserting new staves, \command{Insert Staff + After} to insert a staff \emph{after} an existing one, and \command{Insert + Staff Before} to insert a staff \emph{before} an existing one. + +In both cases, you will be prompted for some required information, in +order for {\gs} to be able to create the new staff. First, you will +be prompted for an existing staff after which (in the case of +\command{Insert Staff After} or before which (in the case of +\command{Insert Staff Before} you would like to insert the new staff. +As usual, you can either click on a visual representation of the staff +in the score pane (see section \ref{sec-score-pane}) or type its name +in the command pane with completion (see section +\ref{sec-command-pane}). + +Next, you are prompted for the type of the staff to create. There are +currently two types of staves, namely `fiveline' and `lyrics'. At the +moment, the only way to answer this question is to type it in the +command pane (again, completion is available). + +If you requested a five-line staff to be created, you will also be +prompted for the type of clef you would like the staff to have. There +are three possible choices `treble', `bass', and `c', which you have +to type in the command pane at the prompt. You will also be prompted +for a `line' number on which the clef is to be placed. Recall that +the lines are numbered with even numbers starting with `0' for the +bottom line of the staff. The normal place for a treble clef is thus +`2' and the normal place for a bass clef is `6'. For the c clef it +varies. + +If instead you requested a lyrics staff to be created, there is no +more information to supply. + +\section{Deleting a staff} + +To delete an existing staff, you issue the \command{Delete Staff} +command, either from a menu or in the command pane. Deleting an +existing staff is such an infrequent operation that no keyboard +shortcut is provided. + +The command prompts for a staff to be deleted. As usual, you can +either satisfy the request by clicking on the visual representation of +a staff in the score pane (see section \ref{sec-score-pane}) or typing +a response in the command pane (see section \ref{sec-command-pane}). + +\section{Changing the key signature} + +To alter the key signature of a staff, use the commands \kbd{Meta-#} +\command{More Sharps} and \kbd{Meta-@} \command{More Flats}. + \chapter{Operations on layers}

-To change the current layer, you can type \kbd{Meta-p} -(\command{Previous Layer}) or \kbd{Meta-n} (\command{Next Layer}. +{\gs} organizes musical material into \emph{layers}\index{layer}. A +{\gs} layer corresponds roughly to a \emph{void}\index{voice} in +traditional music terminology. The reason a different term was chosen +is that there might be some notations that require a voice to be split +into several layers. Each layer can be displayed on one or more +staves, one of which is always the \emph{current}\index{current staff} +one. + +In {\gs}, layers have unique names. Initially, when {\gs} starts up, +it has a single layer with some default name such as ``default +layer''. It has a single staff on which it is displayed, namely the +default staff (see chapter \ref{chap-op-staves}). + +You typically want to choose names for layers that suggest the kind of +music material that is contained in it. Since a layer has (or will +have) a unique \emph{instrument}\index{instrument} associated with it, +we advice you not to mix material for different instruments in a +layer. Therefore, when a part plays several instruments (presumably +not simultaneously) we advice you to use a different layer for each +instrument in the part. Typically, then, a layer name would be the +name of an instruments playing a single part, such as ``First Violin'' +or ``Solo Guitar''. + +\section{Renaming an existing layer} + +You can rename any layer by issuing the command \command{Rename +Layer}, either in the command pane (see section +\ref{sec-command-pane}) or from a menu. + +You will first be prompted for a layer to rename. Currently the only +way to satisfy this request is by typing the name of the layer to the +prompt in the command pane. Completion is possible as usual (see +section \ref{sec-command-pane}). + +Next, you will be prompted for a new name of the layer. To satisfy +the request, you type any string at the prompts. Notice that names +must be unique. If you type the name of an existing layer, your +entire command will be rejected. + +\section{Selecting a layer} + +{\gs} has the concept of a \emph{current layer}\index{current layer} +which receives all music material typed in the score pane, such as +notes, rests, etc. + +To change the current layer, issue the \command{Select Layer} either +from a menu or in the command pane. + +You will be prompted for a layer to be used as the current one. At +the moment, the only way to satisfy this request is to type its unique +name (with completion, see \ref{sec-command-pane}) at the prompt in +the command pane. + +\section{Adding a new layer} + +Before adding a new layer, make sure you have created one of the +staves on which you would its material to be displayed (see section +\ref{sec-inserting-staff}). + +Adding a new layer is done by issuing the command \command{Add + Layer}. You will be prompted for a unique name of the new layer, +and for an existing staff to use as the initial staff of the layer. + +The type of the layer that is created as a result of this command +depends on the type of the initial staff. If the initial staff is an +ordinary five-line staff, then a melody layer is created. If instead +the initial staff is a lyrics staff, a lyrics layer is created.

-To insert a new layer, you have to go to the command pane and type the -full command, either \command{Insert Layer After} or \command{Insert - Layer Before} according to whether you would like the new layer to -be ordered before or after the current one. The order between layers -only affects the order in which they are presented to you with the -\command{Next Layer} and \command{Previous Layer} commands. You will -be prompted for the name of a staff to use for displaying material in -this layer. Later, you can modify the relation between layers and -staves. +\section{Deleting a layer}

To delete the current layer, you have to use the command pane (since this is an operation that is presumably rare). The command to use is -\command{Delete Layer}. +\command{Delete Layer}. You will be prompted for a layer to delete. + +\section{Adding an existing staff to a layer}

A layer can be displayed on one or several \emph{staves}. Most layers will have a single staff associated with them, but is occasionally @@ -398,6 +573,12 @@ displayed on one staff and some other elements on a different staff.

+To add a staff to the possible staves of a layer, use the command +\command{Add Staff To Layer}. You will be prompted for a staff to add +and a layer to add it to. + +\section{Stem direction of a layer} + A layer can have a preferred stem direction for all clusters in it\unimp{It is not hard to do, though}. The user can override this stem direction for individual elements, but if the stem direction of @@ -405,25 +586,6 @@ be displayed with the stem direction determined by the layer. If the stem direction of the layer is also \emph{auto}, the layout engine will determine the stem direction. - -\chapter{Operations on staves} - -To add a new staff, use the command \command{Add Staff}. You will be prompted -for the name of the new staff. - -To delete a staff, use the command \command{Delete Staff}. Again, you -will be prompted for the name of the staff to delete. - -To add a staff to the current layer (so that material in that layer -can be displayed on that staff), use the command \command{Add Layer - Staff}. You will be prompted for the name of a staff to add. - -To delete a staff from the current layer, use the command -\command{Delete Layer Staff}. You will be prompted for the name of a -staff. - -To alter the key signature of a staff, use the commands \kbd{Meta-#} -\command{More Sharps} and \kbd{Meta-@} \command{More Flats}.

% *********************************************************** \part{Reference manual}

Index: gsharp/Doc/plans.tex diff -u gsharp/Doc/plans.tex:1.2 gsharp/Doc/plans.tex:1.3 --- gsharp/Doc/plans.tex:1.2 Mon Feb 16 08:08:01 2004 +++ gsharp/Doc/plans.tex Fri Jul 23 23:41:54 2004 @@ -27,8 +27,6 @@ \item Playing as MIDI should create a temporary file with a unique name in \texttt{/tmp} as opposed a file in the current directory with a name that can clash with others. -\item Someone who knows how pathnames work needs to find out how to - use them in place of strings for filenames. \end{itemize}

\section{Major issues} @@ -170,12 +168,6 @@ itself. Such space would include space for lyrics, accidentals of complicated clusters, etc.

-\subsection{Menu items with arguments} - -This is a {\clim} project. Currently {\clim} does not know how to -read arguments when a command has been invoked from a menu item. -Consequently, we are restricted to menu items that have no arguments. - \subsection{Layout by page}

We need to have a more sophisticated layout algorithm that divides the @@ -223,7 +215,8 @@ \subsection{Other major projects}

\begin{itemize} -\item presentations everywhere (note heads, clusters, beam groups). +\item presentations everywhere (note heads, clusters, beam groups). + Currently, McCLIM is a bit to slow for this. \item context menus on notes, etc \item allow mouse-based input of new notes by making staff steps around cursor into presentations. Move pointer to horizontal

Index: gsharp/Doc/release-notes.tex diff -u gsharp/Doc/release-notes.tex:1.5 gsharp/Doc/release-notes.tex:1.6 --- gsharp/Doc/release-notes.tex:1.5 Sun Jul 18 23:23:53 2004 +++ gsharp/Doc/release-notes.tex Fri Jul 23 23:41:54 2004 @@ -25,6 +25,43 @@ arguments now prompt for existing staves as opposed to just names of staves. \item Added completion for clef types and staff types. +\item Added completion for names of staves and of layers. +\item Naming a layer or a staff requires the user to give a unique + name. +\item Added beginning of support for lyrics. Lyrics are ultimately + going to be Unicode strings, but only a subset of ASCII (letters, + digits) is currently handled. +\item Layers are no longer ordered. Commands related to this ordering + (Next Layer, Previous Layer, Insert Layer After, etc) were removed. + New commands were added: Select Layer prompts for a layer and makes + it the current one. Rename Layer prompts for a layer and a new name + (that must be unique). Add Layer prompts for a unique name and an + initial staff for the layer. The type of the staff determines what + type of layer is created. Delete Layer prompts for a layer + deletes the layer, and automatically inserts a new one if the last + one was deleted. +\item Commands for manipulating staves are now: Insert Staff Before, + which prompts for a staff after which the new one is to be inserted, + for the unique name of the new staff, for the type of the new staff + (currently fiveline or lyrics), for the type of clef to be used on + the new staff, and for a line number on which the clef is to be + placed. Insert Staff After is like Insert Staff Before, except that + the new staff is inserted before an existing one. Delete Staff + prompts for a staff to delete. Rename Staff prompts for a staff to + rename and a new unique name. +\item Each layer contains a list of staves on which music material + from the layer can be presented. There is usually just one staff in + the list, but sometimes two (for piano music). Add Staff To Layer + is a command that prompts for an existing staff to add, and for an + existing layer to which to add the staff, and adds the staff to the + list managed by the layer. The new staff is made the current one + for the layer. +\item Each layer now has its own current staff. When returning to a + multi-staff layer after having edited some other layer, the user now + finds that the last staff that was used in that layer is the current + one. +\item Added a `Staves' menu in the menu bar for mouse access to the + staff commands. \end{itemize}

\subsection{Bug fixes from 0.2}