Reflog 2.0 French serial key or number

This manual documents contributing to LilyPond version It discusses technical issues and policies that contributors should follow. This manual is not intended to be read sequentially; new contributors should only read the sections which are relevant to them. For more information about different jobs, see Help us.

For more information about how this manual fits with the other documentation, or to read this manual in other formats, see Manuals. If you are missing any manuals, the complete documentation can be found at manicapital.com

---

This chapter presents a quick overview of ways that people can help LilyPond.

---

Help us

We need you!

Thank you for your interest in helping us — we would love to see you get involved! Your contribution will help a large group of users make beautifully typeset music.

Even working on small tasks can have a big impact: taking care of them allows experienced developers work on advanced tasks, instead of spending time on those simple tasks.

For a multi-faceted project like LilyPond, sometimes it’s tough to know where to begin. In addition to the avenues proposed below, you can send an e-mail to the lilypond-devel@manicapital.com mailing list, and we’ll help you to get started.

Simple tasks

No programming skills required!

• Mailing list support: answer questions from fellow users. (This may entail helping them navigate the online documentation; in such cases it may sometimes be appropriate to point them to version-agnostic URL paths such as or , which are automatically redirected.)
• Bug reporting: help users create proper Bug reports, and/or join the Bug Squad to organize Issues.
• Documentation: small changes can be proposed by following the guidelines for Documentation suggestions.
• LilyPond Snippet Repository (LSR): create and fix snippets following the guidelines in Adding and editing snippets.
• Discussions, reviews, and testing: the developers often ask for feedback about new documentation, potential syntax changes, and testing new features. Please contribute to these discussions!

Advanced tasks

These jobs generally require that you have the source code and can compile LilyPond.

Contributors using Linux or FreeBSD may also use Lilydev, but if they prefer their own development environment, they should read Working with source code, and Compiling.

Begin by reading Summary for experienced developers.

---

Overview of work flow

Git is a version control system that tracks the history of a program’s source code. The LilyPond source code is maintained as a Git repository, which contains:

• all of the source files needed to build LilyPond, and
• a record of the entire history of every change made to every file since the program was born.

The ‘official’ LilyPond Git repository is hosted by the GNU Savannah software forge at manicapital.com The server provides two separate interfaces for viewing the LilyPond Git repository online: cgit and gitweb.

However, the main development takes place at manicapital.com, which also hosts the project’s issues. Automatic mirroring ensures that ‘important’ branches (such as and ) are up-to-date on the ‘official’ repository at GNU Savannah, so you can also base your development on a clone from there.

Compiling (‘building’) LilyPond allows developers to see how changes to the source code affect the program itself. Compiling is also needed to package the program for specific operating systems or distributions. LilyPond can be compiled from a local Git repository (for developers), or from a downloaded tarball (for packagers). Compiling LilyPond is a rather involved process, and most contributor tasks do not require it.

Contributors can contact the developers through the ‘lilypond-devel’ mailing list. The mailing list archive is located at manicapital.com If you have a question for the developers, search the archives first to see if the issue has already been discussed. Otherwise, send an email to lilypond-devel@manicapital.com You can subscribe to the developers’ mailing list here: manicapital.com

---

Summary for experienced developers

If you are already familiar with typical open-source tools, here’s what you need to know:

• ‘official’ source repository: hosted by GNU Savannah

  manicapital.com?p=manicapital.com

• development platform: hosted by GitLab; also includes the issue tracker (see Issues)

  manicapital.com

• environment variables: many maintenance scripts, and many instructions in this guide rely on predefined Environment variables.
• mailing lists: given on Contact.
• Git branches:
  • : always base your work from this branch, but never push directly to it. Instead, use GitLab to merge changes after they have passed automatic testing (see below).
  • : Translators should base their work on this branch only and push any translation patches directly to it as well.
  • : feel free to push any new branch name under .
• regression tests: also known as “regtests”. A collection of more than a thousand files that are used to track LilyPond’s engraving output between released stable and unstable versions as well as checked for all patches submitted for testing.

  If a patch introduces any unintentional changes to any of the regtests it is very likely it will be rejected (to be fixed) – always make sure that, if you expect any regression test changes, that they are explained clearly as part of the patch description when submitting for testing. For more information see Regression tests.

• reviews: after finishing work on a patch or branch:
  1. Commit the changes and create a merge request. More information on this can be found in the section Uploading a patch for review.
  2. Patches are generally tested within 24 hours of submission. Once it has passed the basic tests – , , – the tracker will be updated and the patch’s status will change to for other developers to examine.
  3. Every third day, the “Patch Meister” will examine all merge requests currently under review, looking for any comments by other developers. Depending on what has been posted, the patch will be either; “moved on” to the next patch status (); set back to ; or if more discussion is needed, left at . In all cases the merge request will be updated by the Patch Meister accordingly.
  4. Once another three days have passed, any patch that has been given status will be changed to , the merge request is updated, and the developer can now rebase and merge to the branch (or ask one of the other developers to merge it for you).

  Advanced note: This process does means that most patches will take about a week before finally being merged into . With the limited resources for reviewing patches available and a history of unintended breakages in the branch (from patches that have not had time to be reviewed properly), this is the best compromise we have found.

---

Mentors

We have a semi-formal system of mentorship, similar to the medieval “journeyman/master” training system. New contributors will have a dedicated mentor to help them “learn the ropes”.

Contributor responsibilities

1. Ask your mentor which sections of the CG you should read.
2. If you get stuck for longer than 10 minutes, ask your mentor. They might not be able to help you with all problems, but we find that new contributors often get stuck with something that could be solved/explained with 2 or 3 sentences from a mentor.
3. If you have been working on a task much longer than was originally estimated, stop and ask your mentor. There may have been a miscommunication, or there may be some time-saving tips that could vastly simply your task.
4. Send patches to your mentor for initial comments.
5. Inform your mentor if you’re going to be away for a month, or if you leave entirely. Contributing to lilypond isn’t for everybody; just let your mentor know so that we can reassign that work to somebody else.
6. Inform your mentor if you’re willing to do more work – we always have way more work than we have helpers available. We try to avoid overwhelming new contributors, so you’ll be given less work than we think you can handle.

Mentor responsibilities

1. Respond to questions from your contributor(s) promptly, even if the response is just “sorry, I don’t know” or “sorry, I’m very busy for the next 3 days; I’ll get back to you then”. Make sure they feel valued.
2. Inform your contributor(s) about the expected turnaround for your emails – do you work on lilypond every day, or every weekend, or what? Also, if you’ll be unavailable for longer than usual (say, if you normally reply within 24 hours, but you’ll be at a conference for a week), let your contributors know. Again, make sure they feel valued, and that your silence (if they ask a question during that period) isn’t their fault.
3. Inform your contributor(s) if they need to do anything unusual for the builds, such as doing a “make clean / doc-clean” or switching git branches (not expected, but just in case)
4. You don’t need to be able to completely approve patches. Make sure the patch meets whatever you know of the guidelines (for doc style, code indentation, whatever), and then send it on to -devel for more comments. If you feel confident about the patch, you can push it directly (this is mainly intended for docs and translations; code patches should almost always go to -devel before being pushed).
5. Keep track of patches from your contributor. Either open merge requests yourself, or help and encourage them to upload the patches themselves.
6. Encourage your contributor to review patches, particularly your own! It doesn’t matter if they’re not familiar with C++ / scheme / build system / doc stuff – simply going through the process is valuable. Besides, anybody can find a typo!
7. Contact your contributor at least once a week. The goal is just to get a conversation started – there’s nothing wrong with simply copy&pasting this into an email:

   Hey there, How are things going? If you sent a patch and got a review, do you know what you need to fix? If you sent a patch but have no reviews yet, do you know when you will get reviews? If you are working on a patch, what step(s) are you working on?

---

Want to submit a patch for LilyPond? Great! Never created a patch before? Never compiled software before? No problem! This chapter is for you and will help you do this as quickly and easily as possible.

---

LilyDev

“LilyDev” is a custom GNU/Linux operating system which includes all the necessary software and tools to compile LilyPond, the documentation and the website (also see Website work). It is also prepared for building the Grand Unified Builder (GUB), though this is an involved process and may require further tweaking.

While compiling LilyPond on Mac OS and Windows is possible, both environments are complex to set up. LilyDev can be easily run inside a ‘virtual machine’ on either of these operating systems relatively easily using readily available virtualization software. We recommend using VirtualBox as it is available for all major operating systems and is very easy to install & configure.

LilyDev comes in two ‘flavours’: containers and a standard disk image. Windows or Mac OS users should choose the Debian disk image (to be run in a virtual machine), that is the file named ‘’. GNU/Linux users are recommended to choose one of the containers (currently Debian or Fedora), which are smaller in size, lightweight and easier to manage. The Fedora disk image has currently not been released, you can create it from the sources located in the ‘’ subdirectory of the LilyDev repository, however.

Download the appropriate file from here:

manicapital.com

If you are not familiar with GNU/Linux, it may be beneficial to read a few “introduction to Linux” type web pages.

---

Installing LilyDev in VirtualBox

This section discusses how to install and use LilyDev with VirtualBox.

1. Download VirtualBox from here:

   manicapital.com

   Note: In virtualization terminology, the operating system where VirtualBox is installed is known as the host. LilyDev will be installed ‘inside’ VirtualBox as a guest.

2. The zip archive you downloaded contains the raw disk image and its SHA checksum. You can verify the integrity of the downloaded archive with any hashing tool your OS does support. On Linux, run the following command in the directory where you have extracted the files (this may take some time):

   shasum -c SHASUMS

   For Windows, look for the tools or to compute the archive’s hash.

3. As VirtualBox does not support the raw format, you have to extract it and then convert it to VDI format. Make sure that ‘VBoxManage’ is in your or call it from your VirtualBox installation directory:

   VBoxManage convertfromraw manicapital.com \ manicapital.com

   Note: You need a fair amount of disk space (around 30GB) to extract the raw image. After converting to a dynamic VirtualBox image it will take up much less space (only the amount of space that is actually allocated by the guest filesystem)

4. Start the VirtualBox software and click ‘New’ to create a new “virtual machine”.

   The ‘New Virtual Machine Wizard’ walks you through setting up your guest virtual machine. Choose an appropriate name for your LilyDev installation and select the ‘Linux’ operating system. When selecting the ‘version’ choose ‘Debian (bit)’. If you do not have that specific option choose ‘Linux /3.x/4.x (bit)’.

5. Select the amount of RAM you allow the LilyDev guest to use from your host operating system when it is running. If possible, use at least 1GB of RAM; the more RAM you can spare from your host the better
6. In the ‘Hard Disk’ step, you use the VDI file you have previously created. You may move it within the virtual machine’s folder already created by the wizard (in GNU/Linux the default should be ‘’). Click on ‘Use an existing virtual hard disk file’ and browse to the VDI file.
7. Verify the summary details and click ‘Create’ as soon as you are satisfied. Your new guest shall be displayed in the VirtualBox window now.
8. Enable EFI within the virtual machine’s settings – click on System → Motherboard and select ‘Extended features: Enable EFI’. Otherwise, you won’t be able to boot the image.
9. VirtualBox ‘guest additions’, which are installed by default in the debian image, provide some additional features such as being able to dynamically resize the LilyDev window, allow seamless interaction with your mouse pointer on both the host and guest, and let you copy/paste between your host and guest if needed. It seems that dynamic window resizing works only with the ‘VBoxVGA’ graphics controller, which you can choose in Display → Graphics Controller. To enable clipboard sharing between guest and host, choose General → Advanced → Shared Clipboard → Bidirectional.
10. Click the ‘Start’ button and wait until the login screen appears. Log in as user then; type the password . Before starting any work, be sure to complete the next steps.

    Note: Since the default keyboard layout is US (American), you may have to type the password differently if you are using another layout, like ‘lilzpond’ on a German keyboard, for example.

11. Open a terminal by clicking Applications → Terminal at the upper left of the screen. You may want to change the password of user ‘dev’ before doing further work with the command .
12. You might need to change the keyboard layout from default US (American) to your national layout. Therefore open a terminal and run

    sudo dpkg-reconfigure keyboard-configuration

    Note: You need superuser rights to change certain aspects of the system configuration. The tool allows to gain superuser rights temporarily. It does show you a warning message on its first use that reminds you to use your extended rights carefully.

    At first, you are prompted for the model of your keyboard. Press Enter to show further models. In most cases, it is sufficient to choose ‘Generic, keys’. After that, choose your keyboard layout. Now, you can customize the function of your <AltGr> key. Normally, the default layout settings fit well, so take number 1. The same holds for the question of whether you want to configure a ‘compose’ key. At last, you are asked if you want to configure <Ctrl+Alt+Backspace> as a shortcut to terminate the X server. Presumably, you do not need this, so you can safely type ‘no’.

13. To set up your system language (charset, localized messages etc.), continue with

    sudo dpkg-reconfigure locales

    Note: Restarting is required in order to take the changes into effect.

14. Finally, you should run a setup script. If you are on the command line already, simply type to run the interactive script that does set up git and downloads all the repositories needed to build LilyPond.

---

Configuring LilyDev in VirtualBox

• In the settings for the virtual machine, set the network to Bridged mode to allow you to access shared folders when using Windows hosts.
• Set up any additional features, such as ‘Shared Folders’ between your main operating system and LilyDev. This is distinct from the networked share folders in Windows. Consult the external documentation for this.

  Some longtime contributors have reported that ‘shared folders’ are rarely useful and not worth the fuss, particularly since files can be shared over a network instead.

• Pasting into a terminal is done with .
• Right-click allows you to edit a file with the text editor (default is Leafpad).

Known issues and warnings

Not all hardware is supported in all virtualization tools. In particular, some contributors have reported problems with USB network adapters. If you have problems with network connection (for example Internet connection in the host system is lost when you launch virtual system), try installing and running LilyDev with your computer’s built-in network adapter used to connect to the network. Refer to the help documentation that comes with your virtualization software.

---

Compiling with LilyDev

LilyDev is our custom GNU/Linux which contains all the necessary dependencies to do LilyPond development; for more information, see LilyDev.

Preparing the build

To prepare the build directory, enter (or copy&paste) the below text. This should take less than a minute.

cd $LILYPOND_GIT sh manicapital.com --noconfigure mkdir -p build/ cd build/ ../configure

Building

Compiling LilyPond will take anywhere between 1 and 15 minutes on most ‘modern’ computers – depending on CPU and available RAM. We also recommend that you minimize the terminal window while it is building; this can help speed up on compilation times.

cd $LILYPOND_GIT/build/ make

It is possible to run with the option to help speed up compilation times even more. See Compiling LilyPond

You may run the compiled with:

cd $LILYPOND_GIT/build/ out/bin/lilypond manicapital.com

Building the documentation

Compiling the documentation is a much more involved process, and will likely take 2 to 10 hours.

cd $LILYPOND_GIT/build/ make make doc

The documentation is put in ‘’. You may view the html files by entering the below text; we recommend that you bookmark the resulting page:

firefox $LILYPOND_GIT/build/out-www/offline-root/manicapital.com

Installing

Don’t. There is no reason to install LilyPond within LilyDev. All development work can (and should) stay within the ‘’ directory, and any personal composition or typesetting work should be done with an official GUB release.

Problems and other options

To select different build options, or isolate certain parts of the build, or to use multiple CPUs while building, read Compiling.

In particular, contributors working on the documentation should be aware of some bugs in the build system, and should read the workarounds in Generating documentation.

---

Now start work!

LilyDev users may now skip to the chapter which is aimed at their intended contributions:

These chapters are mainly intended for people not using LilyDev, but they contain extra information about the “behind-the-scenes” activities. We recommend that you read these at your leisure, a few weeks after beginning work with LilyDev.

---

Advanced contributors will find this material quite useful, particularly if they are working on major new features.

---

Starting with Git

---

Setting up

---

Installing Git

If you are using a Unix-based machine, the easiest way to download and install Git is through a package manager such as or – the installation is generally automatic. The only required package is (usually) called , although some of the auxiliary packages are also useful (such as ).

Alternatively, you can visit the Git website (manicapital.com) for downloadable binaries and tarballs.

---

Initializing a repository

Once Git is installed, get a copy of the source code:

git clone git://manicapital.com ~/lilypond-git

The above command will put the it in ‘’, where represents your home directory.

Technical details

This creates (within the ‘’ directory) a subdirectory called ‘’, which Git uses to keep track of changes to the repository, among other things. Normally you don’t need to access it, but it’s good to know it’s there.

---

Configuring Git

Before working with the copy of the main LilyPond repository, you should configure some basic settings with the command. Git allows you to set both global and repository-specific options.

To configure settings that affect all repositories, use the ‘’ command line option. For example, the first two options that you should always set are your and , since Git needs these to keep track of commit authors:

git config --global manicapital.com "" git config --global manicapital.com

To configure Git to use colored output where possible, use:

git config --global manicapital.com auto

The text editor that opens when using can also be changed. If none of your editor-related environment variables are set ($GIT_EDITOR, $VISUAL, or $EDITOR), the default editor is usually or . If you’re not familiar with either of these, you should probably change the default to an editor that you know how to use. For example, to change the default editor to , enter:

git config --global manicapital.com

Finally, and in some ways most importantly, let’s make sure that we can easily see the state of our working copy, without the need of typing repeatedly. If you’re not using LilyDev, add the following lines to your ‘’:

export PS1="\u@\h \w\$(__git_ps1)$ " export GIT_PS1_SHOWDIRTYSTATE=true export GIT_PS1_SHOWUNTRACKEDFILES=true export GIT_PS1_SHOWUPSTREAM=auto

The first line will show the branch we’re on. The other lines will use some symbols next to the branch name to indicate some kind of state. “*” means that there are unstaged changes, “+” indicates staged changes; if there are untracked files, a “%” will appear. Finally, we can also see if our HEAD is behind (“<”) or ahead (“>”) of its upstream, and if they have diverged (“<>”) or they are synced (“=”).

You may need to install the additional package, but it is definitely worth it. After installation you must log out, and then log back in again to enable it.

Technical details

Git stores the information entered with in the file ‘’, located in your home directory. This file can also be modified directly, without using . The ‘’ file generated by the above commands would look like this:

[user] name = John Smith email = john@manicapital.com [color] ui = auto [core] editor = nano

Using the command without the ‘’ option configures repository-specific settings, which are stored in the file ‘’. This file is created when a repository is initialized (using ), and by default contains these lines:

[core] repositoryformatversion = 0 filemode = true bare = false logallrefupdates = true

However, since different repository-specific options are recommended for different development tasks, it is best to avoid setting any now. Specific recommendations will be mentioned later in this manual.

---

Git for the impatient

Since our review process delays patches by hours, and you want to be able to work on other stuff while your previous work is getting reviewed, you’re going to use branches.

You can think of a branch as being a separate copy of the source code. But don’t worry about it.

Start work: make a new branch

Let’s pretend you want to add a section to the Contributor’s Guide about using branches.

Start by updating the repository, then making a new branch. Call the branch anything you want as long as the name starts with . Branch names that don’t begin with are reserved for special things in lilypond.

git checkout master git pull -r origin master git branch dev/cg

Switch to that branch

Nothing has happened to the files yet. Let’s change into the new branch. You can think of this as “loading a file”, although in this case it’s really “loading a directory and subdirectories full of files”.

git checkout dev/cg

Your prompt now shows you that you’re on the other branch:

gperciva@LilyDev:~/lilypond-git (dev/cg)$

To be able to manage multiple lilypond issues at once, you’ll need to switch branches. You should have each lilypond issue on a separate branch. Switching branches is easy:

git checkout master git checkout origin/release/unstable git checkout dev/cg

Branches that begin with are part of the remote repository, rather than your local repository, so when you check them out you get a temporary local branch. You should never make changes directly on a branch beginning with . You get changes into the remote repository by making them in local branches, and then Merging to master.

Make your changes

Edit files, then commit them.

git commit -a

Remember how I said that switching to a branch was like “loading a directory”? Well, you’ve just “saved a directory”, so that you can “load” it later.

When you create a new file, you need to add it to git, then commit it:

git add input/regression/manicapital.com git commit -a

Edit more files. Commit them again. Edit yet more files, commit them again. Go eat dinner. Switch to so you can play with the latest changes from other developers. Switch back to your branch and edit some more. Commit those changes.

At this stage, don’t worry about how many commits you have.

Save commits to external files

Branches are nerve-wracking until you get used to them. You can save your hard work as individual ‘’ files. Be sure to commit your changes first.

git commit -a git format-patch master

I personally have between 4 and 20 of those files saved in a special folder at any point in time. Git experts might laugh as that behavior, but I feel a lot better knowing that I’ve got those backups.

Prepare your branch for review

After committing, you can update your branch with the latest master:

git commit -a git checkout master git pull -r origin master git checkout dev/cg git rebase master

Due to the speed of lilypond development, sometimes has changed so much that your branch can no longer be applied to it. In that happens, you will have a merge conflict. Stop for a moment to either cry or have a stiff drink, then proceed to Merge conflicts.

Upload your branch

Finally, you’re finished your changes. Time to upload for review. Make sure that you’re on your branch, then upload:

git checkout dev/cg git push

Afterwards create a merge request to indicate the branch is ready for review.

Wait for reviews

While you’re waiting for a countdown and reviews, go back to master, make a branch, and start adding doc suggestions from issue from the tracker. Or make a and fix bug in page breaking. Or whatever. Don’t worry, your is safe.

Combining commits (optional unless you have broken commits)

Does the history of your branch look good?

gitk

If you have a lot of commits on your branch, you might want to combine some of them. Alternately, you may like your commits, but want to edit the commit messages.

git rebase -i master

Follow instructions on the screen.

Merge to master

When you’ve got the coveted status, time to merge your changes as described in Merging to master.

Delete your branch

After the merge request has passed testing and was merged to , you can update and then try removing your branch:

git checkout master git pull -r origin master git branch -d dev/cg

The last command will fail if the commit hashes of are not present in . This can be because you used GitLab to rebase your branch, which modifies the commit data and changes the hash. If you are sure that the branch is not needed anymore, replace the on the final line with a instead.

---

Other repositories

We have a few other code repositories.

---

lilypond-extra

There is a separate repository for general administrative scripts, as well as pictures and media files for the website. People interested in working on the website should download this repository, and set their environment variable to point to that repository.

manicapital.com

To configure an environment variable in bash (the default for most GNU/Linux distributions),

export LILYPOND_WEB_MEDIA_GIT=$HOME/dir/of/lilypond-extra/

Be aware that is the definitive source for some binary files - in particular PDF versions of papers concerning LilyPond. To add further PDFs of this sort, all that is necessary is to add the PDF to and then add a reference to it in the documentation. The file will then be copied to the website when is run.

However, pictures that are also used in the documentation build are mastered in the main git repository. If any of these is changed, it should be updated in git, and then the updates copied to .

---

Grand Unified Builder (GUB)

Another item of interest might be the Grand Unified Builder, our cross-platform building tool. Since it is used by other projects as well, it is not stored in our gub repository. For more info, see manicapital.com

The location for the repository is:

manicapital.com

---

LilyPad

Our binary releases on MacOS X and Windows contain a lightweight text editor.

To make any modifications the Windows editor, you will need to do the following:

1. Clone the git repository from
2. Make changes to the source, and check it compiles. In a Windows environment provides both a installation and a compiler. This can be obtained from
3. Update the version which is contained in the ‘’. Check this compiles, too.
4. Commit the changes with an informative commit message.
5. Push the changes to github. You will need to use syntax similiar to this:

   git push https://UserName@manicapital.com

   You will need to have push access to the git repository for this to be successful.

6. Make a tarball of the source code to be used by GUB by pulling the updated repository from GitHub. Ensure that the tarball has the correct Version number.
7. Copy the tarball to . You will need to have SSH access to . If you do not, contact the Release Manager via the lilypond-devel mailing list.
8. Update GUB to make it use the new tarball by editing ‘’ and changing the line to point to the new source.
9. Push this updated ‘’ version to the GUB repository on GitHub.
10. Test the changes with a new GUB compile.

---

yet more repositories

There are a few other repositories floating around, which will hopefully be documented in the near future.

---

Downloading remote branches

---

Organization of remote branches

The main LilyPond repository is organized into branches to facilitate development. These are often called remote branches to distinguish them from local branches you might create yourself (see Using local branches).

The branch contains all the source files used to build LilyPond, which includes the program itself (both stable and development releases), the documentation (and its translations), and the website. Generally, the branch is expected to compile successfully.

The branch is a side branch that allows translators to work without needing to worry about compilation problems. Periodically, the Translation Meister (after verifying that it doesn’t break compilation), will merge this branch into to incorporate recent translations. Similarly, the branch is usually merged into the branch after significant changes to the English documentation. See Translating the documentation for details.

---

LilyPond repository sources

The recommended source for downloading a copy of the main repository is:

git://manicapital.com

However, if your internet router filters out connections using the GIT protocol, or if you experience difficulty connecting via GIT, you can try these other sources:

ssh://manicapital.com manicapital.com

The SSH protocol can only be used if your system is properly set up to use it. Also, the HTTP protocol is slowest, so it should only be used as a last resort.

---

Downloading individual branches

Once you have initialized an empty Git repository on your system (see Initializing a repository), you can download a remote branch into it. Make sure you know which branch you want to start with.

To download the branch, enter the following:

git remote add -ft master -m master \ origin git://manicapital.com

To download the branch, enter:

git remote add -ft translation -m \ translation origin git://manicapital.com

The process could take up to ten minutes, depending on the speed of your connection. The output will be something like this:

Updating origin remote: Counting objects: , done. remote: Compressing objects: % (/), done. remote: Total (delta ), reused (delta ) Receiving objects: % (/), MiB | KiB/s, done. Resolving deltas: % (/), done. From git://manicapital.com * [new branch] master -> origin/master From git://manicapital.com * [new tag] flower/ -> flower/ * [new tag] flower/ -> flower/ ⋮ * [new tag] release/ -> release/ * [new tag] release/ -> release/

When is finished, the remote branch should be downloaded into your repository—though not yet in a form that you can use. In order to browse the source code files, you need to create and checkout your own local branch. In this case, however, it is easier to have Git create the branch automatically by using the command on a non-existent branch. Enter the following:

git checkout -b origin/

where is the name of your tracking branch, either or .

Git will issue some warnings; this is normal:

warning: You appear to be on a branch yet to be born. warning: Forcing checkout of origin/master. Branch master set up to track remote branch master from origin. Already on 'master'

By now the source files should be accessible—you should be able to edit any files in the ‘’ directory using a text editor of your choice. But don’t start just yet! Before editing any source files, learn how to keep your changes organized and prevent problems later—read Basic Git procedures.

Technical Details

The command should add some lines to your local repository’s ‘’ file:

[remote "origin"] url = git://manicapital.com fetch = +refs/heads/master:refs/remotes/origin/master

---

Downloading all remote branches

To download all remote branches at once, you can the entire repository:

git clone git://manicapital.com

---

Other branches

Most contributors will never need to touch the other branches. If you wish to do so, you will need more familiarity with Git; please see Other Git documentation.

• : These branches are for individual developers. They store code which is not yet stable enough to be added to the branch.
• : The branches are kept for archival reasons.
• : The branches are kept for archival reasons.

---

Basic Git procedures

---

The Git contributor’s cycle

Here is a simplified view of the contribution process on Git:

1. Update your local repository by pulling the most recent updates from the remote repository.
2. Edit source files within your local repository’s working directory.
3. Commit the changes you’ve made to a local branch.
4. Generate a patch to share your changes with the developers.

---

Pulling and rebasing

When developers push new patches to the repository, your local repository is not automatically updated. It is important to keep your repository up-to-date by periodically pulling the most recent commits from the remote branch. Developers expect patches to be as current as possible, since outdated patches require extra work before they can be used.

Occasionally you may need to rework some of your own modifications to match changes made to the remote branch (see Resolving conflicts), and it’s considerably easier to rework things incrementally. If you don’t update your repository along the way, you may have to spend a lot of time resolving branch conflicts and reconfiguring much of the work you’ve already done.

Fortunately, Git is able to resolve certain types of branch conflicts automatically with a process called rebasing. When rebasing, Git tries to modify your old commits so they appear as new commits (based on the latest updates). For a more involved explanation, see the man page.

To pull without rebasing (recommended for translators), use the following command:

git pull # recommended for translators

If you’re tracking the remote branch, you should add the ‘’ option (short for ‘’) to keep commits on your local branch current:

git pull -r # use with caution when translating

If you don’t edit translated documentation and don’t want to type ‘’ every time, configure the master branch to rebase by default with this command:

git config manicapital.com true

If pull fails because of a message like

error: Your local changes to 'Documentation/learning/manicapital.com' would be overwritten by merge. Aborting.

or

Documentation/learning/manicapital.com: needs update refusing to pull with rebase: your working tree is not up-to-date

it means that you have modified some files in you working tree without committing changes (see Commits); you can use the command to work around this:

git stash # save uncommitted changes git pull -r # pull using rebase (translators omit "-r") git stash pop # reapply previously saved changes

Note that will try to apply a patch, and this may create a conflict. If this happens, see Resolving conflicts.

TODO: I think the next paragraph is confusing. Perhaps prepare the reader for new terms ‘committish’ and ‘head’? -mp

Abstract

This document specifies VoiceXML, the Voice Extensible Markup Language. VoiceXML is designed for creating audio dialogs that feature synthesized speech, digitized audio, recognition of spoken and DTMF key input, recording of spoken input, telephony, and mixed-initiativemixed initiative conversations. Its major goal is to bring the advantages of web-based development and content delivery to interactive voice response applications.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is the 10 December W3C Candidate Recommendation of "Voice Extensible Markup Language (VoiceXML) Version ". W3C publishes a technical report as a Candidate Recommendation to indicate that the document is believed to be stable, and to encourage implementation by the developer community. Candidate Recommendation status is described in section of the Process Document.

The exit criteria for this phase is at least two independently developed interoperable implementations of each required feature, and at least one implementation of each feature. Detailed implementation requirements and the invitation for participation in the Implementation Report are provided in the Implementation Report Plan. Note, this specification already has significant implementation experience that will soon be reflected in its Implementation Report. We expect to meet all requirements of that report within a Candidate Recommendation period closing 28th February

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than "work in progress."

Comments on this document and requests for further information should be sent to the Working Group's public mailing list www-voice@manicapital.com (archive). Note as a precaution against spam, you should first subscribe to this list by sending an email to <www-voice-request@manicapital.com> with the word subscribe in the subject line (include the word unsubscribe if you want to unsubscribe). Please check the disposition of comments received during the last call period.

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page in conformance with W3C policy.

This document has been produced as part of the W3C Voice Browser Activity, following the procedures set out for the W3C Process. The authors of this document are members of the Voice Browser Working Group (W3C Members only).

A list of current W3C Recommendations and other technical documents can be found at manicapital.com

Conventions of this Document

In this document, the key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" are to be interpreted as described in [RFC] and indicate requirement levels for compliant VoiceXML implementations.

Table of Contents

Abbreviated Contents

Full Contents

---

This document defines VoiceXML, the Voice Extensible Markup Language. Its background, basic concepts and use are presented in Section 1. The dialog constructs of form, menu and link, and the mechanism (Form Interpretation Algorithm) by which they are interpreted are then introduced in Section 2. User input using DTMF and speech grammars is covered in Section 3, while Section 4 covers system output using speech synthesis and recorded audio. Mechanisms for manipulating dialog control flow, including variables, events, and executable elements, are explained in Section 5. Environment features such as parameters and properties as well as resource handling are specified in Section 6. The appendices provide additional information including the VoiceXML Schema, a detailed specification of the Form Interpretation Algorithm and timing, audio file formats, and statements relating to conformance, internationalization, accessibility and privacy.

The origins of VoiceXML began in as an XML-based dialog design language intended to simplify the speech recognition application development process within an AT&T project called Phone Markup Language (PML). As AT&T reorganized, teams at AT&T, Lucent and Motorola continued working on their own PML-like languages.

In , W3C hosted a conference on voice browsers. By this time, AT&T and Lucent had different variants of their original PML, while Motorola had developed VoxML, and IBM was developing its own SpeechML. Many other attendees at the conference were also developing similar languages for dialog design; for example, such as HP's TalkML and PipeBeach's VoiceHTML.

The VoiceXML Forum was then formed by AT&T, IBM, Lucent, and Motorola to pool their efforts. The mission of the VoiceXML Forum was to define a standard dialog design language that developers could use to build conversational applications. They chose XML as the basis for this effort because it was clear to them that this was the direction technology was going.

In , the VoiceXML Forum released VoiceXML to the public. Shortly thereafter, VoiceXML was submitted to the W3C as the basis for the creation of a new international standard. VoiceXML is the result of this work based on input from W3C member companies, other W3C working groups, and the public.

Developers familar with VoiceXML are particularly directed to Changes from Previous Public Version which summarizes how VoiceXML differs from VoiceXML

Introduction

VoiceXML is designed for creating audio dialogs that feature synthesized speech, digitized audio, recognition of spoken and DTMF key input, recording of spoken input, telephony, and mixed-initiativemixed initiative conversations. Its major goal is to bring the advantages of web-based development and content delivery to interactive voice response applications.

Here are two short examples of VoiceXML. The first is the venerable "Hello World":

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <form> <block>Hello World!</block> </form> </vxml>

The top-level element is <vxml>, which is mainly a container for dialogs. There are two types of dialogs: forms and menus. Forms present information and gather input; menus offer choices of what to do next. This example has a single form, which contains a block that synthesizes and presents "Hello World!" to the user. Since the form does not specify a successor dialog, the conversation ends.

Our second example asks the user for a choice of drink and then submits it to a server script:

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <form> <field name="drink"> <prompt>Would you like coffee, tea, milk, or nothing?</prompt> <grammar src="manicapital.com" type="application/srgs+xml"/> </field> <block> <submit next="manicapital.com"/> </block> </form> </vxml>

A field is an input field. The user must provide a value for the field before proceeding to the next element in the form. A sample interaction is:

C (computer): Would you like coffee, tea, milk, or nothing?

H (human): Orange juice.

C: I did not understand what you said. (a platform-specific default message.)

C: Would you like coffee, tea, milk, or nothing?

H: Tea

C: (continues in document manicapital.com)

Background

This section contains a high-level architectural model, whose terminology is then used to describe the goals of VoiceXML, its scope, its design principles, and the requirements it places on the systems that support it.

Architectural Model

The architectural model assumed by this document has the following components:

Figure 1: Architectural Model

A document server (e.g. a web server) processes requests from a client application, the VoiceXML Interpreter, through the VoiceXML interpreter context. The server produces VoiceXML documents in reply, which are processed by the VoiceXML Interpreter. The VoiceXML interpreter context may monitor user inputs in parallel with the VoiceXML interpreter. For example, one VoiceXML interpreter context may always listen for a special escape phrase that takes the user to a high-level personal assistant, and another may listen for escape phrases that alter user preferences like volume or text-to-speech characteristics.

The implementation platform is controlled by the VoiceXML interpreter context and by the VoiceXML interpreter. For instance, in an interactive voice response application, the VoiceXML interpreter context may be responsible for detecting an incoming call, acquiring the initial VoiceXML document, and answering the call, while the VoiceXML interpreter conducts the dialog after answer. The implementation platform generates events in response to user actions (e.g. spoken or character input received, disconnect) and system events (e.g. timer expiration). Some of these events are acted upon by the VoiceXML interpreter itself, as specified by the VoiceXML document, while others are acted upon by the VoiceXML interpreter context.

Goals of VoiceXML

VoiceXML’s main goal is to bring the full power of web development and content delivery to voice response applications, and to free the authors of such applications from low-level programming and resource management. It enables integration of voice services with data services using the familiar client-server paradigm. A voice service is viewed as a sequence of interaction dialogs between a user and an implementation platform. The dialogs are provided by document servers, which may be external to the implementation platform. Document servers maintain overall service logic, perform database and legacy system operations, and produce dialogs. A VoiceXML document specifies each interaction dialog to be conducted by a VoiceXML interpreter. User input affects dialog interpretation and is collected into requests submitted to a document server. The document server replies with another VoiceXML document to continue the user’s session with other dialogs.

VoiceXML is a markup language that:

• Minimizes client/server interactions by specifying multiple interactions per document.

• Shields application authors from low-level, and platform-specific details.

• Separates user interaction code (in VoiceXML) from service logic (e.g. CGI scripts).

• Promotes service portability across implementation platforms. VoiceXML is a common language for content providers, tool providers, and platform providers.

• Is easy to use for simple interactions, and yet provides language features to support complex dialogs.

While VoiceXML strives to accommodate the requirements of a majority of voice response services, services with stringent requirements may best be served by dedicated applications that employ a finer level of control.

Scope of VoiceXML

The language describes the human-machine interaction provided by voice response systems, which includes:

• Output of synthesized speech (text-to-speech).

• Output of audio files.

• Recognition of spoken input.

• Recognition of DTMF input.

• Recording of spoken input.

• Control of dialog flow.

• Telephony features such as call transfer and disconnect.

The language provides means for collecting character and/or spoken input, assigning the input results to document-defined request variables, and making decisions that affect the interpretation of documents written in the language. A document may be linked to other documents through Universal Resource Identifiers (URIs).

Principles of Design

VoiceXML is an XML application [XML].

1. The language promotes portability of services through abstraction of platform resources.

2. The language accommodates platform diversity in supported audio file formats, speech grammar formats, and URI schemes. While producers of platforms may support various grammar formats the language requires a common grammar format, namely the XML Form of the W3C Speech Recognition Grammar Specification [SRGS], to facilitate interoperability. Similarly, while various audio formats for playback and recording may be supported, the audio formats described in Appendix E must be supported

3. The language supports ease of authoring for common types of interactions.

4. The language has well-defined semantics that preserves the author's intent regarding the behavior of interactions with the user. Client heuristics are not required to determine document element interpretation.

5. The language recognizes semantic interpretations from grammars and makes this information available to the application.

6. The language has a control flow mechanism.

7. The language enables a separation of service logic from interaction behavior.

8. It is not intended for intensive computation, database operations, or legacy system operations. These are assumed to be handled by resources outside the document interpreter, e.g. a document server.

9. General service logic, state management, dialog generation, and dialog sequencing are assumed to reside outside the document interpreter.

10. The language provides ways to link documents using URIs, and also to submit data to server scripts using URIs.

11. VoiceXML provides ways to identify exactly which data to submit to the server, and which HTTP method (GET or POST) to use in the submittal.

12. The language does not require document authors to explicitly allocate and deallocate dialog resources, or deal with concurrency. Resource allocation and concurrent threads of control are to be handled by the implementation platform.

Implementation Platform Requirements

This section outlines the requirements on the hardware/software platforms that will support a VoiceXML interpreter.

Document acquisition. The interpreter context is expected to acquire documents for the VoiceXML interpreter to act on. The "http" URI protocol must be supported. In some cases, the document request is generated by the interpretation of a VoiceXML document, while other requests are generated by the interpreter context in response to events outside the scope of the language, for example an incoming phone call. When issuing document requests via http, the interpreter context identifies itself using the "User-Agent" header variable with the value "<name>/<version>", for example, "acme-browser/"

Audio output. An implementation platform must support audio output using audio files and text-to-speech (TTS). The platform must be able to freely sequence TTS and audio output. If an audio output resource is not available, an manicapital.comurce event must be thrown. Audio files are referred to by a URI. The language specifies a required set of audio file formats which must be supported (see Appendix E); additional audio file formats may also be supported.

Audio input. An implementation platform is required to detect and report character and/or spoken input simultaneously and to control input detection interval duration with a timer whose length is specified by a VoiceXML document. If an audio input resource is not available, an manicapital.comurce event must be thrown.

• It must report characters (for example, DTMF) entered by a user. Platforms must support the XML form of DTMF grammars described in the W3C Speech Grammar Recognition SpecificationSpeech Recognition Grammar Specification[SRGS]. They should also support the Augmented BNF (ABNF) form of DTMF grammars described in the W3C Speech Grammar Recognition SpecificationSpeech Recognition Grammar Specification[SRGS].

• It must be able to receive speech recognition grammar data dynamically. It must be able to use speech grammar data in the XML Form of the W3C Speech Recognition Grammar Specification [SRGS]. It should be able to receive speech recognition grammar data in the ABNF form of the W3C Speech Recognition Grammar Specification [SRGS], and may support other formats such as the JSpeech Grammar Format [JSGF] or proprietary formats. Some VoiceXML elements contain speech grammar data; others refer to speech grammar data through a URI. The speech recognizer must be able to accommodate dynamic update of the spoken input for which it is listening through either method of speech grammar data specification.

• It must be able to record audio received from the user. The implementation platform must be able to make the recording available to a request variable. The language specifies a required set of recorded audio file formats which must be supported (see Appendix E); additional formats may also be supported.

Transfer The platform should be able to support making a third party connection through a communications network, such as the telephone.

Concepts

A VoiceXML document (or a set of related documents called an application) forms a conversational finite state machine. The user is always in one conversational state, or dialog, at a time. Each dialog determines the next dialog to transition to. Transitions are specified using URIs, which define the next document and dialog to use. If a URI does not refer to a document, the current document is assumed. If it does not refer to a dialog, the first dialog in the document is assumed. Execution is terminated when a dialog does not specify a successor, or if it has an element that explicitly exits the conversation.

Dialogs and Subdialogs

There are two kinds of dialogs: forms and menus. Forms define an interaction that collects values for a set of field item variables. Each field may specify a grammar that defines the allowable inputs for that field. If a form-level grammar is present, it can be used to fill several fields from one utterance. A menu presents the user with a choice of options and then transitions to another dialog based on that choice.

A subdialog is like a function call, in that it provides a mechanism for invoking a new interaction, and returning to the original form. Variable instances, grammars, and state information are saved and are available upon returning to the calling document. Subdialogs can be used, for example, to create a confirmation sequence that may require a database query; to create a set of components that may be shared among documents in a single application; or to create a reusable library of dialogs shared among many applications.

Sessions

A session begins when the user starts to interact with a VoiceXML interpreter context, continues as documents are loaded and processed, and ends when requested by the user, a document, or the interpreter context.

Applications

An application is a set of documents sharing the same application root document. Whenever the user interacts with a document in an application, its application root document is also loaded. The application root document remains loaded while the user is transitioning between other documents in the same application, and it is unloaded when the user transitions to a document that is not in the application. While it is loaded, the application root document's variables are available to the other documents as application variables, and its grammars remain active for the duration of the application, subject to the grammar activation rules discussed in Section While it is loaded, the application root document’s variables are available to the other documents as application variables, and its grammars can also be set to remain active for the duration of the application.

Figure 2 shows the transition of documents (D) in an application that share a common application root document (root).

Figure 2: Transitioning between documents in an application.

Grammars

Each dialog has one or more speech and/or DTMF grammars associated with it. In machine directed applications, each dialog’s grammars are active only when the user is in that dialog. In mixed initiative applications, where the user and the machine alternate in determining what to do next, some of the dialogs are flagged to make their grammars active (i.e., listened for) even when the user is in another dialog in the same document, or on another loaded document in the same application. In this situation, if the user says something matching another dialog’s active grammars, execution transitions to that other dialog, with the user’s utterance treated as if it were said in that dialog. Mixed initiative adds flexibility and power to voice applications.

Events

VoiceXML provides a form-filling mechanism for handling "normal" user input. In addition, VoiceXML defines a mechanism for handling events not covered by the form mechanism.

Events are thrown by the platform under a variety of circumstances, such as when the user does not respond, doesn't respond intelligibly, requests help, etc. The interpreter also throws events if it finds a semantic error in a VoiceXML document. Events are caught by catch elements or their syntactic shorthand. Each element in which an event can occur may specify catch elements. Catch elements are also inherited from enclosing elements "as if by copy". In this way, common event handling behavior can be specified at any level, and it applies to all lower levels.

Links

A link supports mixed initiative. It specifies a grammar that is active whenever the user is in the scope of the link. If user input matches the link’s grammar, control transfers to the link’s destination URI. A link can be used to throw an event or go to a destination URI.

VoiceXML Elements

Document Structure and Execution

A VoiceXML document is primarily composed of top-level elements called dialogs. There are two types of dialogs: forms and menus. A document may also have <meta> and <metadata> elements, <var> and <script> elements, <property> elements, <catch> elements, and <link> elements.

Execution within One Document

Document execution begins at the first dialog by default. As each dialog executes, it determines the next dialog. When a dialog doesn’t specify a successor dialog, document execution stops.

Here is "Hello World!" expanded to illustrate some of this. It now has a document level variable called "hi" which holds the greeting. Its value is used as the prompt in the first form. Once the first form plays the greeting, it goes to the form named "say_goodbye", which prompts the user with "Goodbye!" Because the second form does not transition to another dialog, it causes the document to be exited.

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <meta name="author" content="John Doe"/> <meta name="maintainer" content="hello-support@manicapital.com"/> <var name="hi" expr="'Hello World!'"/> <form> <block> <value expr="hi"/> <goto next="#say_goodbye"/> </block> </form> <form id="say_goodbye"> <block> Goodbye! </block> </form> </vxml>

Alternatively the forms can be combined:

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <meta name="author" content="John Doe"/> <meta name="maintainer" content="hello-support@manicapital.com"/> <var name="hi" expr="'Hello World!'"/> <form> <block> <value expr="hi"/> Goodbye! </block> </form> </vxml>

Attributes of <vxml> include:

version	The version of VoiceXML of this document (required). The current version number is
xmlns	The designated namespace for VoiceXML (required). The namespace for VoiceXML is defined to be manicapital.com
xml:base	The base URI for this document as defined in [XML-BASE]. As in [HTML], a URI which all relative references within the document take as their base.
xml:lang	The language identifier for this document as defined in [RFC]. If omitted, the value is a platform-specific default.
application	The URI of this document’s application root document, if any.

Language information is inherited down the document hierarchy: the value of "xml:lang" is inherited by elements which also define the "xml:lang" attribute, such as <grammar> and <prompt>, unless these elements specify an alternative value.

Executing a Multi-Document Application

Normally, each document runs as an isolated application. In cases where you want multiple documents to work together as one application, you select one document to be the application root document, and the rest to be application leaf documents. Each leaf document names the root document in its <vxml> element.

When this is done, every time the interpreter is told to load and execute a leaf document in this application, it first loads the application root document if it is not already loaded. The application root document remains loaded until the interpreter is told to load a document that belongs to a different application. Thus one of the following two conditions always holds during interpretation:

• The application root document is loaded and the user is executing in it: there is no leaf document.

• The application root document and a single leaf document are both loaded and the user is executing in the leaf document.

If there is a chain of subdialogs defined in separate documents, then there may be more than one leaf document loaded although execution will only be in one of these documents.

When a leaf document load causes a root document load, none of the dialogs in the root document are executed. Execution begins in the leaf document.

There are several benefits to multi-document applications.

• The root document's variables are available for use by the leaf documents, so that information can be shared and retained.
• Root document <property> elements specify default values for properties used in the leaf documents.
• Common ECMAScript code can be defined in root document <script> elements and used in the leaf documents.
• Root document <catch> elements define default event handling for the leaf documents.
• Document-scoped grammars in the root document are active when the user is in a leaf document, so that the user is able to interact with forms, links, and menus in the root document.

Here is a two-document application illustrating this:

Application root document (manicapital.com)

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <var name="bye" expr="'Ciao'"/> <link next="operator_manicapital.com"> <grammar type="application/srgs+xml" root="root" version=""> <rule id="root" scope="public">operator</rule> </grammar> </link> </vxml>

Leaf document (manicapital.com)

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version="" application="manicapital.com"> <form id="say_goodbye"> <field name="answer"> <grammar type="application/srgs+xml" src="/grammars/manicapital.com"/> <prompt>Shall we say <value expr="manicapital.com"/>?</prompt> <filled> <if cond="answer"> <exit/> </if> <clear namelist="answer"/> </filled> </field> </form> </vxml>

In this example, the application is designed so that manicapital.com must be loaded first. Its application attribute specifies that manicapital.com should be used as the application root document. So, manicapital.com is then loaded, which creates the application variable bye and also defines a link that navigates to manicapital.com whenever the user says "operator". The user starts out in the say_goodbye form:

C: Shall we say Ciao?

H: Si.

C: I did not understand what you said. (a platform-specific default message.)

C: Shall we say Ciao?

H: Ciao

C: I did not understand what you said.

H: Operator.

C: (Goes to operator_manicapital.com, which transfers the caller to a human operator.)

Note that when the user is in a multi-document application, at most two documents are loaded at any one time: the application root document and, unless the user is actually interacting with the application root document, an application leaf document. A root document's <vxml> element does not have an application attribute specified. A leaf document's <vxml> element does have an application attribute specified. An interpreter always has an application root document loaded; it does not always have an application leaf document loaded.

The name of the interpreter's current application is the application root document's absolute URI. The absolute URI includes a query string, if present, but it does not include a fragment identifier. The interpreter remains in the same application as long as the name remains the same. When the name changes, a new application is entered and its root context is initialized. The application's root context consists of the variables, grammars, catch elements, scripts, and properties in application scope.

During a user session an interpreter transitions from one document to another as requested by <choice>, <goto> <link>, <subdialog>, and <submit> elements. Some transitions are within an application, others are between applications. The preservation or initialization of the root context depends on the type of transition:

Root to Leaf Within Application

A root to leaf transition within the same application occurs when the current document is a root document and the target document's application attribute's value resolves to the same absolute URI as the name of the current application. The application root document and its context are preserved.

Leaf to Leaf Within Application

A leaf to leaf transition within the same application occurs when the current document is a leaf document and the target document's application attribute's value resolves to the same absolute URI as the name of the current application. The application root document and its context are preserved.

Leaf to Root Within Application

A leaf to root transition within the same application occurs when the current document is a leaf document and the target document's absolute URI is the same as the name of the current application. The current application root document and its context are preserved when the transition is caused by a <choice>, <goto>, or <link> element. The root context is initialized when a <submit> element causes the leaf to root transition, because a <submit> always results in a fetch of its URI.

Root to Root

A root to root transition occurs when the current document is a root document and the target document is a root document, i.e. it does not have an application attribute. The root context is initialized with the application root document returned by the caching policy in Section The caching policy is consulted even when the name of the target application and the current application are the same.

Subdialog

A subdialog invocation occurs when a root or leaf document executes a <subdialog> element. As discussed in Section , subdialog invocation creates a new execution context. The application root document and its context in the calling document's execution context are preserved untouched during subdialog execution, and are used again once the subdialog returns. A subdialog's new execution context has its own root context and, possibly, leaf context. When the subdialog is invoked with a non-empty URI reference, the caching policy in Section is used to acquire the root and leaf documents that will be used to initialize the new root and leaf contexts. If a subdialog is invoked with an empty URI reference and a fragment identifier, e.g. "#sub1", the root and leaf documents remain unchanged, and therefore the current root and leaf documents will be used to initialize the new root and leaf contexts.

Inter-Application Transitions

All other transitions are between applications which cause the application root context to be initialized with the next application's root document.

If a document refers to a non-existent application root document, or if a document's application attribute refers to a document that also has an application attribute specified, an manicapital.comic event is thrown.

If a document refers to a non-existent application root document, an manicapital.comch event is thrown. If a document's application attribute refers to a document that also has an application attribute specified, an manicapital.comic event is thrown.

The following diagrams illustrate the effect of the transitions between root and leaf documents on the application root context. In these diagrams, boxes represent documents, box texture changes identify root context initialization, solid arrows symbolize transitions to the URI in the arrow's label, dashed vertical arrows indicate an application attribute whose URI is the arrow's label.

Figure 3: Transitions that Preserve the Root Context

In this diagram, all the documents belong to the same application. The transitions are identified by the numbers across the top of the figure. They are:

1. A transition to URI A results in document 1, the application context is initialized from document 1's content. Assume that this is the first document in the session. The current application's name is A.
2. Document 1 specifies a transition to URI B, which yields document 2. Document 2's application attribute equals URI A. The root is document 1 with its context preserved. This is a root to leaf transition within the same application.
3. Document 2 specifies a transition to URI C, which yields another leaf document, document 3. Its application attribute also equals URI A. The root is document 1 with its context preserved. This is a leaf to leaf transition within the same application.
4. Document 3 specifies a transition to URI A using a <choice>, <goto>, or <link>. Document 1 is used with its root context intact. This is a leaf to root transition within the same application.

The next diagram illustrates transitions which initialize the root context.

Figure 4: Transitions that Initialize the Root Context

1. Document 1 specifies a transition to its own URI A. The resulting document 4 does not have an application attribute, so it is considered a root document, and the root context is initialized. This is a root to root transition.
2. Document 4 specifies a transition to URI D, which yields a leaf document 5. Its application attribute is different: URI E. A new application is being entered. URI E produces the root document 6. The root context is initialized from the content of document 6. This is an inter-application transition.
3. Document 5 specifies a transition to URI A. The cache check returns document 4 which does not have an application attribute and therefore belongs to application A, so the root context is initialized. Initialization occurs even though this application and this root document were used earlier in the session. This is an inter-application transition.

Subdialogs

A subdialog is a mechanism for decomposing complex sequences of dialogs to better structure them, or to create reusable components. For example, the solicitation of account information may involve gathering several pieces of information, such as account number, and home telephone number. A customer care service might be structured with several independent applications that could share this basic building block, thus it would be reasonable to construct it as a subdialog. This is illustrated in the example below. The first document, manicapital.com, seeks to adjust a customer’s account, and in doing so must get the account information and then the adjustment level. The account information is obtained by using a subdialog element that invokes another VoiceXML document to solicit the user input. While the second document is being executed, the calling dialog is suspended, awaiting the return of information. The second document provides the results of its user interactions using a <return> element, and the resulting values are accessed through the variable defined by the name attribute on the <subdialog> element.

Customer Service Application (manicapital.com)

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <form id="billing_adjustment"> <var name="account_number"/> <var name="home_phone"/> <subdialog name="accountinfo" src="acct_manicapital.com#basic"> <filled> <!-- Note the variable defined by "accountinfo" is returned as an ECMAScript object and it contains two properties defined by the variables specified in the "return" element of the subdialog. --> <assign name="account_number" expr="manicapital.comm"/> <assign name="home_phone" expr="manicapital.comone"/> </filled> </subdialog> <field name="adjustment_amount"> <grammar type="application/srgs+xml" src="/grammars/manicapital.com"/> <prompt> What is the value of your account adjustment? </prompt> <filled> <submit next="/cgi-bin/updateaccount"/> </filled> </field> </form> </vxml>

Document Containing Account Information Subdialog (acct_manicapital.com)

<?xml version="" encoding="UTF-8"?> <vxml xmlns="manicapital.com" xmlns:xsi="manicapital.com" xsi:schemaLocation="manicapital.com manicapital.com" version=""> <form id="basic"> <field name="acctnum"> <grammar type="application/srgs+xml" src="/grammars/manicapital.com"/> <prompt> What is your account number? </prompt> </field> <field name="acctphone"> <grammar type="application/srgs+xml" src="/grammars/phone_manicapital.com"/> <prompt> What is your home telephone number? </prompt> <filled> <!-- The values obtained by the two fields are supplied to the calling dialog by the "return" element. --> <return namelist="acctnum acctphone"/> </filled> </field> </form> </vxml>

Subdialogs add a new execution context when they are manicapital.com subdialog could be a new dialog within the existing document, or a new dialog within a new document.

Subdialogs can be composed of several documents. Figure 5 shows the execution flow where a sequence of documents (D) transitions to a subdialog (SD) and then back.

Figure 5: Subdialog composed of several documents
returning from the last subdialog document.

The execution context in dialog D2 is suspended when it invokes the subdialog SD1 in document manicapital.com This subdialog specifies execution is to be transfered to the dialog in manicapital.com (using <goto>). Consequently, when the dialog in manicapital.com returns, control is returned directly to dialog D2.

Figure 6 shows an example of a multi-document subdialog where control is transferred from one subdialog to another.

Figure 6: Subdialog composed of several documents
returning from the first subdialog document.

The subdialog in manicapital.com specifies that control is to be transfered to a second subdialog, SD2, in manicapital.com When executing SD2, there are two suspended contexts: the dialog context in D2 is suspending awaiting SD1 to return; and the dialog context in SD1 awaiting SD2 to return. When SD2 returns, control is returned to the SD1. It in turn returns control to dialog D2.

Final Processing

Under certain circumstances (in particular, while the VoiceXML interpreter is processing a disconnect event) the interpreter may continue executing in the final processing state after there is no longer a connection to allow the interpreter to interact with the end user. The purpose of this state is to allow the VoiceXML application to perform any necessary final cleanup, such as submitting information to the application server. For example, the following <catch> element will catch the manicapital.com event and execute in the final processing state:

<catch event="manicapital.com"> <submit namelist="myExit" next="http://mysite/manicapital.com"/> </catch>

While in the final processing state the application must remain in the transitioning state and may not enter the waiting state (as described in Section ). Thus for example the application should not enter <field>, <record>, or <transfer> while in the final processing state. The VoiceXML interpreter must exit if the VoiceXML application attempts to enter the waiting state while in the final processing state.

Aside from this restriction, execution of the VoiceXML application continues normally while in the final processing state. Thus for example the application may transition between documents while in the final processing state, and the interpreter must exit if no form item is eligible to be selected (as described in Section ).

Forms

Forms are the key component of VoiceXML documents. A form contains:

• A set of form items, elements that are visited in the main loop of the form interpretation algorithm. Form items are subdivided into input items that can be 'filled' by user input and control items that cannot.

• Declarations of non-form item variables.

• Event handlers.

• "Filled" actions, blocks of procedural logic that execute when certain combinations of input item variables are assigned.

Form attributes are:

id

The name of the form. If specified, the form can be referenced within the document or from another document. For instance <form id="weather">, <goto next="#weather">.

scope

The default scope of the form’s grammars. If it is dialog then the form grammars are active only in the form. If the scope is document, then the form grammars are active during any dialog in the same document. If the scope is document and the document is an application root document, then the form grammars are active during any dialog in any document of this application. Note that the scope of individual form grammars takes precedence over the default scope; for example, in non-root documents a form with the default scope "dialog", and a form grammar with the scope "document", then that grammar is active in any dialog in the document.

This section describes some of the concepts behind forms, and then gives some detailed examples of their operation.

Form Interpretation

Forms are interpreted by an implicit form interpretation algorithm (FIA). The FIA has a main loop that repeatedly selects a form item and then visits it. The selected form item is the first in document order whose guard condition is not satisfied. For instance, a field’s default guard condition tests to see if the field’s form item variable has a value, so that if a simple form contains only fields, the user will be prompted for each field in turn.

Interpreting a form item generally involves: