Authoring DVD-Video
Using Alex Thüring's DVDStyler© 2011 Jonathan Blair
Permission is granted to copy, distribute and/or modify thisdocument under the terms of the GNU Free Documentation
License, Version 1.3 or any later version published by the Free
Software Foundation; with no Invariant Sections, no FrontCover Texts, and no Back-Cover Texts. A copy of the license isincluded in the section entitled “GNU Free Documentation
License”.
0. Disclaimer of Warranty
THERE IS NO WARRANTY FOR THIS DOCUMENT, TO THE EXTENT PERMITTED BYAPPLICABLE LAW. THIS DOCUMENT IS PROVIDED “AS-IS” WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THISDOCUMENT IS WITH YOU. SHOULD THE DOCUMENT PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
1. Contact Information
Future contributors may contact me for permissions pursuant to theterms of the GNU Free Documentation License Version 1.3 by e-mail to:need-more-input@users.sourceforge.net
Now that the formalities are out of the way, please keep your hands and feet inside
the vehicle at all times and enjoy the ride!

Authoring DVD-Video
Using Alex Thüring's DVDStyler
Rev 1.03© 2011 Jonathan Blair

Table of Contents∙ Introduction∙ Project Configuration∙ Adding Menus and Video∙ Basic Menu Editing∙ Menu Errata∙ Chapters, Video Options∙ Basic Scripting∙ Advanced Scripting∙ Example Structures∙ Further Resources∙ Acknowledgements∙ Revision History∙ GNU FDL
Introduction
DVDStyler provides a unified graphic interface for creating interactive menus,transcoding and multiplexing video, audio and subtitle streams, and generating
DVD images to be burned to recordable media or archived for later use.
The menu bar contains the File, Edit, DVD, Configuration, and Help menus. The
File menu opens and saves project files and launches the Burn interface which
generates DVD images and discs. The Edit menu provides undo and redo
capabilities. The DVD menu sets properties for the current project, and theConfiguration menu sets overarching properties for the program. Finally, the Help
menu provides access to the internal guide and version information. The toolbar
underneath the menu bar provides quick access to the most commonly usedfunctions from the menu bar. Tooltips are available by hovering the cursor over the
buttons. The sidebar provides a file browser as well as default background andbutton selections.
The titleset manager along the bottom of the interface provides a graphic list ofelements that will be present on the disc in linear order. Drag and drop from a file
manager to add elements or right-click whitespace or individual elements for adrop-down menu. In addition, modifying the order of elements is only possible
through this menu by selecting the appropriate action from the Move dialog.
The status bar forming the bottom of the window provides a description of theobject under the cursor as well as remaining disc capacity and bitrate of the
project.
Last, but not least is the main display providing a graphical menu editor. Like
the titleset manager, objects may be modified by the right-click drop-down menu.

On initially loading, DVDStyler provides a Welcome Menu to help set up a new
project or open an existing one. This menu is a combination of the DVD>Options
window and a list of recently opened projects. The two windows appear as follows:

Project Configuration
When starting a new project, the Welcome window and DVD Options window
provide the basic configuration options.
∙ The Disc label will become the volume label for the disc (visible on computers).
∙ Standard single-layer DVD±R discs have a capacity of 4.7 GB; dual-layer discs
have a capacity of 8.5 GB. The unlimited option in Disc capacity is intended forcomputer use only; the image generated cannot be burned to disc if it exceeds
the applicable capacity.
∙ Video Quality is best left on Auto; DVDStyler can manage the bitrate according
to the length of included titles. The manual options offer fine tuning if desired.
∙ The video format, aspect ratio and audio format should be set according to thestandards of target DVD players and the title video. Information on NTSC / PAL
and supported audio formats is available in Further Resources.
Further considerations before editing the project include the number of menus
and features desired. Users must have an interface to select options, and draftinga list of menus will expedite project editing. Generic menu information is available
in Menu Errata and detailed menu limitations and solutions are available in
Advanced Scripting. This guide will cover the following features:
∙
∙
∙
∙
∙
∙

Forced First play clip
Play all command
Menu transitions
Remember last-pressed menu buttons (if manual implementation is necessary)
Enable resume
Prevent access to selected elements except by the menu interface

Adding Menus and Video
Menus and titles will be encoded into the project in the order that they areadded, with one exception: vmMenus (video manager menus) are always at the
beginning of the project. Menus and titles can be linked from anywhere in the discand title and menu locations can be shifted somewhat, so order is not paramount,however if a particular structure is desired the corresponding elements must be
added in the correct order. Following preference, add all necessary menus andtitles using the DVD>Add menu list, the toolbar Add button, or the right clickmenu while hovering over the titleset manager's whitespace. Note that the toolbar
Add button is restricted to adding titles. This process is demonstrated below.

This project includes one main menu (vmMenu 1), one sub-menu (Menu 1) and
four titles. DVDStyler starts a non-template project with a single menu (Menu 1),
so the vmMenu and titles (videos) 1 through 4 were added in succession.
Now that all elements are present, roughly edit the menus to identify what eachwill eventually be. Select each menu icon in the titleset manager to display it forediting and choose a temporary background from the built-in set by double
clicking on an appropriate image in the sidebar. Add a title to the menu by rightclicking on the main display and selecting Add>Text. Type in the title of the menu
and select OK. Don't forget to save this rough version; the project now has theoverall structure which will be on the final DVD.

Basic Menu Editing
DVDStyler provides many tools for menu editing. The first is the border outline
showing the TV safe area. Televisions regularly clip a percentage of the image,called overscan (see Further Resources), but this percentage varies from display
to display. Important text and buttons that must be displayed, for instance menu
interfaces, should be confined to an area which is ten percent smaller in eachdimension, thus five percent per edge. Provided no necessary information is in thisregion, the menu should appear complete to the viewer. This border may be
toggled by right clicking on the main display and (de)selecting View>Show Safe
TV area.
Other menu editing tools include drawing elements such as ellipses, rectangles
and frames (which are rectangles with rounded corners) as well as text and text
with shadow. External images may also be added. All of these tools are accessible
by right clicking on the main display and selecting the appropriate option from the
Add menu.
Customized backgrounds are possible by modifying the properties of the menu:
right click the main display while the menu is visible or right click its icon in thetitleset manager and select Properties. In the Background section of the window,
type in the location of the custom background or click the ellipsis button to theright to open the file manager window and navigate to the custom image (orvideo). Media should be the same aspect ratio as the disc (16x9 or 4x3); all input
will be scaled to 720x576 or 720x480 according to the format of the disc.
All graphic elements in the menu are aligned to a grid by default. Toggling thegrid and modifying its dimensions and visibility are accomplished by right clicking
the main display and selecting the appropriate option from the Grid menu.

Menu Errata
Professional DVD menus typically have video backgrounds and accompanying
audio which loop to provide an immersive experience immediately on loading a
disc. DVDStyler partially (as of version 1.8.4) supports custom video backgrounds(without static overlays), including the functionality to loop playback. While theoption to pause the menu exists, this functionality is not optimal for every
circumstance. Some free software media players omit menu functionality, and in
the remainder the menu stability is often questionable. For reasons beyond thescope of this document, rendering button graphics correctly seems to be an
ongoing issue. Continuous looping playback is presently one of the best
workarounds. This adds the benefit of re-rendering the interface at each loop,
mitigating issues with rendering failure (black screen).
DVD menus typically divide viewer-selectable features into several separate
menus. Each feature corresponds with a button present on most DVD-player
remotes which jumps directly to the corresponding menu. Designating a function
for a menu is not mandatory; it is done only to simplify direct menu navigation.
Many combinations are possible; the following is a guideline for two basic DVD
structures that result in an intuitive interface:
∙
∙
∙
∙
∙

The main menu is always a vmMenu (video manager menu), and isdesignated the title menu.
The audio menu and subtitle menu comprise one Menu, which isdesignated as both the audio and subtitle menu.
In a single title (single video) DVD, the chapter menu is a Menu and isdesignated both the chapter and root menu.
In a multiple title (multiple video) DVD, the chapter menu is a Menu andis designated the chapter menu.
In a multiple title DVD, the episode selection menu is a Menu and isdesignated the root menu.

Importantly, a vmMenu can only be marked as the title menu and a normal(titleset) Menu can be marked as any menu other than the title menu. While
DVDStyler offers the feature of an Angle menu, the documentation for dvdauthor(the back end which creates the DVD filesystem) states that this is untested. Angle
functionality requires additional information in the video stream, but you can test
it with a multiplexed video stream if you have one (see Further Resources).
As a general rule, menus which include thumbnails (shrunken pictures) of video
frames should have at maximum four to six thumbnails depending on their size
relative to the menu. Scaling frames smaller to include more thumbnails results ina lack of detail rendering the use of thumbnails inconsequential. DVDStyler
supplies a default frame button to simplify this implementation.
Since video backgrounds are partially supported in menus, additional menus
may be used to implement menu transitions. Since transitions are not interactive
menus, they probably should not be designated as any of the primary menus listed
above; rather, command scripting should handle their display. Menu transitions, aswell as other features, are detailed in Advanced Command Scripting.

Managing Chapters
Before working on the commands to link menus and titles, set the chapter
points for each title. Chapters are used to access particular scenes of the title
conveniently without fast-forward- or rewind-type scanning.
Type in the chapter points following
the format [[H:]MM:]SS[.sss] where
the units in brackets are optional, andseparate each chapter with a comma
without spaces.
i.e.

0:00,22.234,1:14:28.467

Optionally, use the Chapters Menu
to define chapter, program and cell
points. Programs, cells, and cellcommands will be described in
Advanced Command Scripting.

Chapters
Menu

The Chapters Menu provides areference frame when setting
navigation points. Use the slider orprovided field to select anappropriate time for your chapter
points. Add the chapter by clicking
on the green plus button. To remove
a chapter, highlight the appropriate
entry in the left-hand list and click
the red minus button.

Cell Properties
Menu

Chapters, programs and cells can beedited later, so setting all navigation
points as chapters is fine for now.

If you wish to change theproperties of a highlighted
chapter in the list, click on thewrench icon button. This will open
the Cell Properties Menu. In themenu, you can select whether thenavigation point is a chapter, cell
(Regular cell) or a program. You
can also set a pause length at theend of the cell, program or
chapter and execute a single DVDplayer cell command.

Video Encoding
With chapters accounted for, the encoding settings for titles and menus should
now be set. Select the correct video and audio format and language for each title
according to the disc format (PAL / NTSC).
The Title Properties window
provides a drop-down box with options
for video and audio encoding. Copying
audio or video uses that particular
aspect of the input file in the final DVD
as-is. This requires that the input
format is DVD compatible, and speeds
up the DVD creation process.
Click on the tool-icon button toaccess the Video Properties window
for the title. This presents editing
options including trimming, cropping,
padding, and fading, with interlacedor progressive encoding. Additionally,
FFmpeg command-line video filters
may be applied by using the provided
field (audio filters are not supported).
See Further Resources for more
information on interlacing and video
filters. Set the destination format andaspect ratio and the auto / nopanscan /noletterbox format if widescreen. The
latter two restrict the display mode forsubtitles and subpictures.

Video
Properties

Menu Encoding / Command Introduction
Video encoding and chapters have now been set. All that remains of the video
options is to specify how the menus will be displayed. All vmMenus and Menus
within a single titleset will have the same display settings. Thus for bothwidescreen and full frame presentations on a disc, multiple titlesets must be used.
Set the format, aspect ratio and auto /nopanscan / noletterbox setting (ifwidescreen) as appropriate for Menus ineach titleset and vmMenus. Using thenopanscan or noletterbox settings
permit more buttons on widescreen
menus. This will be covered in moredetail in Advanced Command Scripting.
Introducing Commands
At this point everything is ready for
setting the commands which will control
how the disc will function. In addition to
buttons on the menus, the behavior ofeach menu, title, and portions thereof(chapters, programs, cells) can becontrolled by commands. DVDStyler
offers an extensive list of default
commands you can use when building
your disc. They are presented in dropdown menus on each of the appropriate
properties menus.
While this is more than adequate for basic and moderately complicated discs,
sometimes the default commands cannot accomplish unique tasks. This is where
the command scripting section of this guide comes into play. Command Scripting
will begin with fundamentals, explaining how navigation, logical tests andarithmetic form the core of commands. Variables are used to store information
for later use, like which menu was last viewed. This is followed by more complex
commands and their uses as well as a section on possible features to implement.
Since reference manuals are typically dry and difficult to follow, two
Example Structures are included after the scripting section to relate thecommands in a functional manner to a disc structure.
Completing the DiscWhen the commands to control the disc functions have been added, generate
the disc image and optionally burn the disc from the Burn window (the red discbutton on the main interface toolbar). If you have hard drive space, saving theimage (ISO) to burn later will help prevent burning discs with errors. You canalso preview the finished project by the option in the Burn window.

Command Scripting – The Basics
One of the functions of DVDStyler is to provide a Graphical User Interface (GUI)to the DVD filesystem generating program dvdauthor. All scripting commands fordiscs generated by DVDStyler therefore inherit their language and syntax fromthis back end. Generally, this looks similar to the C programming language.
The commands used in authoring a disc are composed of statements, eachstatement being a sentence in the scripting language. Each statement ends in asemicolon (;) which allows multiple statements to be written on the same line. Thisis important for our purposes since commands in DVDStyler must be entered in asingle line input menu – provided that the supplied commands do not suffice.
Statements may assign a value to a variable, navigate from one part of the DVD
to another, perform a test to conditionally do one of the previous operations, or
combine all three actions. These will be broken down in order:∙

Variables allow user options and playing conditions to be temporarily stored.
Functionally, they are called registers and the registers available forcommand scripting are called general purpose registers. This is abbreviatedby the letter 'g' followed by a number designation. In total, there are 16 ofthese general purpose registers ranging from g0 to g15. However, due tothe specifications of the DVD standard, navigating from an arbitrary pointon the disc to a particular menu or title is potentially complicated. A helper
function is available to handle those complexities (more later), but it
reserves g13, g14 and g15 to perform its tasks. Generally, minimizing thenumber of variables used will permit more interactivity and features in themenu interface as well as allow the use of this shortcut.

∙

The syntax for assigning a value to a variable is:register name = your number or equation;i.e. g0=1024;∙

Navigation between pairs of DVD menus and titles is accomplished by thecommands “jump” and “call” and each is tailored to a specific purpose. The
call command navigates from a title to a menu. In addition, the origin
location is saved so that the title can optionally be resumed by the “resume”
command. All other navigation throughout the disc is accomplished by thejump command, which saves no point for resume.

∙

The syntax for navigation is as follows:
Menu to Menu
jump menu name;i.e.
jump menu 1;

Menu to Title
jump title name;i.e.
jump title 1;

Title to Menu
call menu name;i.e. call menu 2;

Title to Title
jump title name;i.e.
jump title 2;More advanced usage of these commands is included later.

Basic Command Scripting – Conditional Statements
Conditionally executed operations take the form of an if statement. Provided thetest is true, the proceeding operation is executed.
∙

The test for an if statement must be either true or false. Because of thelimited scripting commands, this means that the test must be a comparison
between two values, i.e. the first is equal, not equal, less than, greater than,less than or equal to, or greater than or equal to the second value.
Respectively, these comparisons use the symbols ==, !=, <, >, <=, >= orthe alphabetic mnemonics eq, ne, lt, gt, le, ge. Importantly, the symbol ==compares the two values in the test whereas = sets the value of a variable;
remember to use the appropriate symbol.

∙

Comparisons may use the following set of mathematical operations:addition, subtraction, multiplication, division, and modulo
Respectively, these use the symbols +, ‒, *, /, and %(an additional class of operators is reserved for later discussion)‣ These operations are also permitted throughout the script‣ for reference, the modulo operation returns the remainder of one
integer divided by another,i.e. 11%3 = 2 since 11/3 = 3 + 2/3∙

Comparisons are not statements, so they do not end in a semicolon.

∙

The complete form of the if statement is as follows:
if ( comparison ) conditional operation; else conditional operation;
where the else clause of the if statement is optional.

An if statement can conditionally execute a block of statements. This provides
multiple consequences for a single test. This takes the form:
if ( comparison ) { first operation; second operation; ... ; }∙Blocks group a set of statements (already ended by semicolons) by placing
them inside braces, so they do not use any further symbols to designate
their end. Blocks are necessary in the above form for if statements; they
may be used outside of this context, but such use is optional.
More advanced usage of these commands is included later.

Command scripting is used for button actions, before and after menus and titles
as pre- and post-commands, and in defining the first play commands (executed onloading the disc). Provided a button is selected before the menu ends, the buttoncommand is executed instead of the menu post command. The following example
demonstrates the combination of the preceding statements.
First play command:menu 1 length:menu 1 post-command:menu 1 button 1:
title 1 pre-command:
title 1 post-command:

g0=8; jump menu 1;
100 frames
jump menu 1;
jump title 1;
if (g0%2==1) call menu 1;
call menu 1;

Is title 1 shown if thecorresponding button
in menu 1 is pressed?
Yes ‒ since 8%2 = 0,
the condition does notsatisfy the if statement,so the title is played.

Advanced Command Scripting ‒ Completing the Command Set
While the command list from the previous section covers the basics of scripting,this section will provide an exhaustive list of commands and demonstrate a set offeatures in various permutations. Treat this section as a desk reference and return
to it for definitions and clarification. Understanding the entirety of DVD scripting
by reading the command set alone is an excessive expectation; this illustrates thepremise behind this guide.
∙

There are two varieties of menus: one is the video manager menu (vmMenu)
and the second is the titleset menu (Menu). Ideological use aside, the only
difference between these two menus is their restrictions on navigation.
Navigating from a vmMenu (“vmgm menu number” in script) to a titleset
menu (“titleset number menu number”) requires that the titleset menu is
the root menu in the titleset (marked by red brackets in the titleset manager
of DVDStyler). This is directly due to the formal DVD specification.
Permitted navigation is as follows:‣ A vmMenu can jump to any other vmMenu, the root menu in each titleset(defaulting to the first menu) or any title. Titles are numbered sequentiallyon the disc independent of titlesets in this usage.
jump vmgm menu number;jump titleset number menu;
jump title number;‣ A titleset menu can jump to any vmMenu or any menu or title in its
titleset. The titleset number descriptor is optional.
jump vmgm menu number;jump menu number;jump title number;‣ A title can call any vmMenu or the root menu in its titleset or jump to any
title in its titleset. The titleset number descriptor is not permitted. Title
numbers are determined by the present titleset only.
call vmgm menu number;call menu;

jump title number;

To alleviate the inconvenience of restricted navigation, the dvdauthor
developers created a feature called “jumppads” which reserves general
purpose registers g13, g14 and g15 to permit navigation between any twotitles, menus or combination thereof. This distinguishes titleset menus andtitles by the titleset which contains them. If enabled, they may be written as“titleset number menu number” and “titleset number title number” inall circumstances; dvdauthor adds in the necessary scripting for navigation.
If the formal navigation is sufficient, this feature need not be enabled;
otherwise, go to the DVD>Options window to activate “Create jumppads.”∙

More generalized menu calls and jumps are possible (given the proper tags
are set in the menu properties) by specifying menus by their entries insteadof numbers. Entries are: title, root, subtitle, audio, angle, and ptt *.
call / jump menu name entry menu tag;i.e.
call menu entry root; jump menu entry audio;* ptt = chapter
menu

Menus without tags must use the number method. Navigation rules apply.

Advanced Command Scripting ‒ Command Set Continued∙

Any chapter in a title is a valid jump target from any menu (though thecommand is different without jumppads). Chapter navigation is as follows:
jump titleset number title number chapter number;jump title number chapter number;jump title number program number;jump title number cell number;(upper example
uses jumppads)

The last three examples presume navigation in the present titleset. Custom
cell and program definitions expand on the use of chapters. Hierarchically, acell is the most basic unit of video and has no direct method for userinteraction. Programs are supersets of cells which also provide navigation
points for the previous and next buttons on a player. Finally, chapters areprograms that dvdauthor has marked for direct navigation. The commands
jump program number; and jump cell number; navigate within a title(or menu! ‒ menu calls also work). Other targets are:cell top
program top
pgc top*up pgc

next cell
next program
next pgc
pgc tailprev cellprev program
prev pgc(*currently unsupported)

These targets in the blue box can only be accessed by the jump command.
The “top” group identifies the beginning of each unit, “next” is the following
unit, and “prev” is the previous unit. Generally, a single title or menu is a
pgc and the pgc tail is the post command of the present title or menu.
∙

Cell commands are like pre- and post-commands, but are executed at theend of a cell (prior to a post-command) and must compile to a single
command for a DVD-player. See Further Resources for a complete list.

∙

The resume command ( “resume;” ) may be used from any menu, but thetitle it jumps to (and the particular time within that title) depends onwhether or not the menu has been called during a title. If the menu is called
while a title is playing, the resume command will jump back to the title andtime when the menu was called earlier. Otherwise, the command will jump
to the first title in the first titleset. A resume point may be manually set
when the menu is called (by pre- or post-command, cell command or buttonover-video [last currently unsupported in DVDStyler]) by specifying thereturn cell if the resume command is issued. This is done in the callcommand as follows:call target menu resume cell;
By default, dvdauthor processes the chapter list resulting in cells withoutcell commands. Therefore, replace cell with the desired chapter number (inthe present title). If using custom cells, cells may differ from chapters.

∙

A pseudo-random number generator is provided by the function random().
The function accepts positive values or expressions which produce positive
values and outputs an integer between 1 and the input value, inclusively.
random(4) will output either 1, 2, 3 or 4, in a pseudo-random fashion.

Advanced Command Scripting ‒ Command Set Completed∙

In addition to the general purpose registers available for any scripting,there are twenty-four purpose-defined system registers denoted s0 to s23.
Of these, four are common for interface purposes; they control the default
angle, audio, highlighted (focused) button, and subtitle. These registers may
be invoked as angle, audio, button, and subtitle or referred to by theirformal designations, respectively s3, s1, s8 and s2.
‣ Currently, dvdauthor documentation states that angle functionality isuntested. According to the DVD standard, this accepts values 1-9. Celldefinitions and commands are helpful to gain full angle functionality, butdvdauthor may need further development to enable this.
‣ There are eight permitted audio streams, 0-7. DVDStyler automaticallydenotes them from lowest to highest, beginning with the audio embeddedin the input video (if present). The stream number increases according tothe order in which the audio tracks are added to each title via theproperties window. If the stream is set to a value of 15, no sound will play.
‣ The default highlighted button is referenced by the button number
multiplied by 1024. Each button number is shown on its properties
window, counting up from 1 according to the order in which the buttons
are added. A maximum of thirty-six buttons are permitted on a menu,
divided between the display modes; for full frame, all thirty-six are
permitted, and for widescreen, twelve may be displayed unless theoptions “nopanscan” or “noletterbox” are set, which permit eighteen.
‣ There are a maximum of thirty-two subtitle streams, 0-31. DVDStyler does
not provide forced subtitle controls (where only some subtitles are forced
to be displayed) – by default all subtitles are forced. Still, adding 64 to thestream number shows all subtitles in tracks with non-forced subtitles.
Track 64 shows everything in stream 0. Track 62 disables subtitles, andtrack 63 finds the viewer's default language tag (with stream 0 default).
Setting values:∙

register name = value;audio=0;

or

s1=0;

In addition to the comparison operators ( ==, !=, <, >, <=, >= ), Boolean
logical operators may chain up to two comparisons together in an if
statement. This uses Boolean logic via 'and', 'not', 'or' and 'xor' (exclusiveor). Boolean 'and' requires that both comparisons before and after 'and' aretrue for the test to be satisfied. For instance, “2==2 and 4==4” would test
true, so the conditional operation would be executed. Boolean 'not' logicallynegates the truth of the comparison after it. Thus, “not 2==3” would test
true. Boolean 'or' requires that either (or both) of the comparisons are true.
Hence, “5==5 or 2==2” would test true. Boolean 'xor' requires that one of
the comparisons is true (but not both). So “5==5 xor 2==2” would test
false; both comparisons are true. The logical 'and', 'not', and 'or' operators
may also be written '&&', '!' and '||', respectively.
Note: not all players will correctly process two comparisons; nested if
statements are reliable, however. if (test_1) { if (test_2) {commands;} }∙Bitwise logical operators 'and', 'or' and 'xor' are supplied by the symbols'&', '|', and '^' ‒ these perform the same Boolean logic as above, but
individually to each bit in a value. All values are 16 bit nonnegative integers.

Advanced Command Scripting ‒ Feature Demonstration
With the fundamentals and detailed definitions now covered, examples of somepossible features are in order. This is where the fun begins and authoringcustomization starts. A little more on menu structure first.
Suppose you want a simple one-menu DVD. This seems fine in principle, butshould the interface be a vmMenu or a titleset Menu? Remember that a vmMenu
is the only menu type that can be a title menu. This means that without avmMenu, pressing the title menu button on a viewer's remote will result in anerror; in the best circumstances the player will ignore the button press. Without atitleset Menu, though, none of the other entries (root, chapter, etc.) can be set.
The solution is to make the titleset Menu the main menu interface and add a blankvmMenu with the title entry set. Set the pre-command of the vmMenu to jump to
the titleset Menu and you have an instant everything-in-one menu. This principle
applies even to multi-menu interfaces where you want the title menu remotebutton and the root menu remote button to display the same menu. Note that thisis referred to as a “dummy menu” since it serves no purpose but to redirect
navigation.
With all the complexity of navigation with multiple titlesets, why not throw themout and just keep it simple? It's a fair point and will simplify the process ofbuilding a DVD, but there is a very nice feature available to multiple titlesets:
each titleset can have its own root, chapter, audio, subtitle and angle menus. If aviewer presses the remote button to call one of these menus from a particular
titleset, the menu in that titleset will be displayed. This allows very diverse
content to be compiled onto a disc and results in menus which are tailored fortheir particular titles. Themed appearances result is a professional-looking DVD
interface. The end goal is ease of use for a viewer; an intuitive interface is always
a good idea. Just remember that the DVDStyler interface does not let you add
more menus or titles to an earlier titleset once you've added a new titleset (rightclick on whitespace in the titleset manager for the option).
Of all features to include, a first play clip is probably the most noticeable.
Since interactive menus in DVDStyler cannot have video backgrounds, theinterface will seem very spartan if there is no video introduction. A first play clip
is one of the easiest features to enable. This may be a feature title or the
background of a menu used as an introduction. Go to DVD>Options and set theFirst Play Commands to jump to the appropriate menu or title. In the introduction
case, set the post-command to jump to the main menu. Technically speaking,that's all that is necessary. If you would like to make your discs dummy-proof, alittle scripting can force the clip to be played as long as the player follows precommands. When a DVD is loaded, every general purpose register is set to zero.
This can be used to determine if the disc has been recently loaded. Pick a general
purpose register to use in your test ‒ it really doesn't matter what variable isused, just that a single variable is referenced. Add the following pre-command to
all primary (tagged) menus and every title on the disc (except the first play clip):if (your variable==0) navigate to first play clip destination;and the following post-command to the first play clip:
your variable=some value greater than zero; navigate to desired location;

Advanced Command Scripting ‒ More Features
The previous first play clip can act as an introduction, but further transitional
elements will likely improve the reception of the interface. Menu transitions
help to make the DVD presentation seamless. Similarly as the first play clip, menu
transitions use an additional menu to display the video content, using a manuallyset background clip. Use the following commands for each menu transition:
outbound button:menu post-command:

jump transition menu destination;
jump appropriate menu destination;

Note: a transition clip can function as the navigation bridge between two titleset
menus (thus avoiding jumppads) if the clip is the background of a vmMenu.
The resume feature helps viewers change settings mid-title while not losing the
progress on viewing the title. However, sometimes a “play” button is assumed to
be a resume button and this confusion can result in the loss of the resume point.
To combine these two buttons, dedicate a register to the current playing status:
when the main title is selected, save a nonzero value to the register and when thetitle is complete set the value back to zero. Therefore, if any play button is pressed
and the value in the play status register is not zero, the button will resume.
play button:

if (your variable==0) { your variable=value greater than zero;
jump title destination; } else { resume; }title post-command:

your variable=0; call appropriate menu;

This same principle can be used to create a play all button. Here, one value
indicates that some sequence should be played and another indicates that a single
episode should be played. The “play all” flag in the button properties uses values“1” and “0” in register g0 to handle this in the background for all titles.
play all button:

your variable=value 1; jump first title in sequence;play episode button:

your variable=value 2; jump particular title;

title post-commands:

if (your variable==value 1) jump next title;
else { your variable=0; call menu destination; }last title post-command: if (your variable==value 1){ your variable=0; call menu with play all button; }else {your variable=0; call menu destination; }This principle is not limited to two settings (playing the entire disc versus one
title), and may be extended to a play-list button. In this mode, the value of thevariable indicates the precise navigation through all the titles on the disc. For
instance, music videos could be categorized according to individual performers,
group performers, songwriters, genre, dates, albums, track numbers (thoughcreating groups of first, second, etc. tracks from different albums might seem alittle random), or any other criteria imaginable to determine the titles to be played
and in what particular order. Each play-list has a number assigned to it and each
title uses a long string of post-command tests to navigate according to the play-list
value. Though this would take a while to set up, it would likely be impressive tothe viewer. Creating a spreadsheet for reference when scripting this is a must.

Advanced Command Scripting ‒ Completing the Feature Set
Finally, what menu interface would seem professional without a reasonable
default highlighted button? To remember the last-pressed menu button, selectone general purpose register for each menu which will remember buttons. In thecommand of every button which jumps away from the menu, save the value of the
button number multiplied by 1024 to the appropriate register. Button numbers arevisible on their properties window as well as in the status bar. Set the precommand of each applicable menu to highlight the saved menu button as follows:
button command:

your variable=1024*button number;jump destination;menu pre-command:

button=pressed button variable;

The default button may also be set by the above pre-command using a fixed value.
This feature is included in DVDStyler, but is referenced here for further use below.
Conserving Variables
When combining features, it helps to note when conditions for one featureoverlap with another feature. For instance, the zero value of some register used totest the first-play video is compatible with all other features so the variable usedby the first-play test can easily be shared with another feature. Similarly, the playall, resume and title restriction features can all share a variable since they are all
related to the current status of play. Sharing variables conserves scripting
resources and permits more features and interactivity. If space gets particularly
cramped, try designing the menu interface so that jumppads may be deactivated(this provides three more registers). Perhaps better in conserving variables (butmore complicated to implement), the last pressed button on several menus can be
combined by treating the variable as a sixteen-bit counter. Suppose there areeight buttons on a menu; then three bits of the shared variable (23=8) can then be
used to save which button was last pressed via bitwise logic.
3 bits for this menu

first bit place ‒ 1 = 4

binary value 1111111110001111 = 65423 decimal value

24 = 16Erases previous
value

storing: temporary variable = your variable & 65423;
your variable = temporary variable | ((button number ‒ 1)*16);
Stores newvaluebinary 0000000001110000 = 112
retrieving:

temporary variable = (your variable & 112)+1;
button= temporary variable * 1024;

This is a little complicated ;-) but if variables are in short supply this method willdefinitely conserve space. Note that variable sharing can be implemented in otherinstances also. Ultimately, it is possible to have a very large number of menus andfeatures included on a DVD provided that you plan out the structure thoroughly.
Most projects do not even remotely need to consider the binary logic above, but
it can serve as a reminder of the adaptability and flexibility of the DVD platform.
The final step after designing all of the menus, adding titles, setting chapter
points and encoding settings, and adding assorted commands is to save theproject and burn the disc. The project is complete! See Completing the Disc.

Example Structure 1
This structure generates a DVD with a first-play clip, play all command, whichremembers last-pressed menu buttons, implements menu transitions, and resumes
by default to remedy accidental navigation. There are five feature titles treated as
episodes, four vmMenus (main menu, first play / main menu introduction, twomenu transition elements), and one Menu (episode selection).
DVD Options:First play commands:

g0=0; g1=0; g2=0; jump vmgm menu 2;

vmMenu 1 "Main Menu" Properties:
Video Object – [select] –> Loop
Menu – [select] –> Title
Pre commands:
if (g0==0) { jump vmgm menu 2; } else { button=g0; }vmMenu 1 button "Play All" (button 1):
g0=1024; g2=1; resume;
vmMenu 1 button "Episode Selection" (button 2):
jump vmgm menu 3;
vmMenu 2 “Main Menu Introduction Clip” Properties:
Background – Image: [introduction_clip]
Video Object – Audio: [introduction_audio]
Post commands:

Pause: 0g0=1024; jump vmgm menu 1;

vmMenu 3 “Main Menu to Episode Selection Menu Transition":
Background – Image: [transition_clip_1]
Video Object – Audio: [transition_1_audio]
Post commands:

Pause: 0

g1=1024; jump titleset 1 menu;

vmMenu 4 "Episode Selection Menu to Main Menu Transition":
Background – Image: [transition_clip_2]
Video Object – Audio: [transition_2_audio]
Post commands:

Pause: 0g0=2048; jump vmgm menu 1;

Menu 1 "Episode Selection Menu" Properties:
Video Object – [select] –> Loop
Menu – [select] –> Root
Pre commands:
if (g0==0) { jump vmgm menu 2; } else { button=g1; }Menu 1 button "Resume Feature" (button 1):
g1=1024; g2=0; resume;

Example Structure 1 Part 2
Menu 1 button "Episode 1" (button 2):
g1=1024; g2=0; jump title 1;
Menu 1 button "Episode 2" (button 3):
g1=1024; g2=0; jump title 2;
Menu 1 button "Episode 3" (button 4):
g1=1024; g2=0; jump title 3;
Menu 1 button "Episode 4" (button 5):
g1=1024; g2=0; jump title 4;
Menu 1 button "Episode 5" (button 6):
g1=1024; g2=0; jump title 5;
Menu 1 button "Main Menu" (button 7):
jump vmgm menu 4;
Title 1 "Episode 1":
Pre commands:
Post commands:
Title 2 "Episode 2":
Pre commands:
Post commands:
Title 3 "Episode 3":
Pre commands:
Post commands:
Title 4 "Episode 4":
Pre commands:
Post commands:
Title 5 "Episode 5":
Pre commands:
Post commands:

if (g0==0) {call vmgm menu 2; }if (g2==1) { jump title 2; }else { g1=3072; call menu entry root; }if (g0==0) {call vmgm menu 2; }if (g2==1) { jump title 3; }else { g1=4096; call menu entry root; }if (g0==0) {call vmgm menu 2; }if (g2==1) { jump title 4; }else { g1=5120; call menu entry root; }if (g0==0) {call vmgm menu 2; }if (g2==1) { jump title 5; }else { g1=6144; call menu entry root; }if (g0==0) {call vmgm menu 2; }if (g2==1) { g2=0; call vmgm menu 1; }else { g1=7168; call menu entry root; }Example Structure 1 Part 3
List of variable values and their meanings
g0(first-play test, main menu button highlight [focus])=0 - Disc has been recently loaded. First play engage!
=1024 - Highlight first button on Main Menu (Play All button)=2048 - Highlight second button on Main Menu (Episode Selection button)
g1(episode selection menu button highlight [focus])=0 - Disc has been recently loaded. Value will be overwritten after first-play.
=1024 - Highlight first button on Episode Selection Menu (Resume Feature
button)=2048 - Highlight second button on Episode Selection Menu (Episode 1 button)=3072 - Highlight third button on Episode Selection Menu (Episode 2 button)=4096 - Highlight fourth button on Episode Selection Menu (Episode 3 button)=5120 - Highlight fifth button on Episode Selection Menu (Episode 4 button)=6144 - Highlight sixth button on Episode Selection Menu (Episode 5 button)=7168 - Highlight seventh button on Episode Selection Menu (Main Menu
button)g2(activate play-all mode, activate single episode mode)=0 Single episode mode; after playing episode, will return to EpisodeSelection Menu
=1 Activate play-all mode; episodes will play back-to-backThis first example demonstrated a basic episode-based DVD. This is excellent tobecome familiar with the functioning of commands, but employs few features
which cannot be implemented by standard DVDStyler-provided drop-downcommands. The following example is a more complex design, based on a singletitle DVD. I decided to create a disc which would track where the viewer was
throughout the movie. When a viewer selects the chapter menu, the present
chapter is auto-highlighted on the correct menu (one of three). Also, the present
chapter is detected within one second of playing that chapter (the division ofchapters and cells). This shows one small capability of cell commands.

Example Structure 2This structure generates a DVD with a first-play clip, remembers last-pressed
menu buttons, navigates to present chapter button on calling chapter menu, andresumes by default to remedy accidental navigation. There is one feature title, one
vmMenu (dummy menu), and seven Menus (main menu, chapter menu, two static
information menus, and one first-play / main menu introduction menu).
DVD Options:First play commands:

g0=0; g1=0; jump titleset 1 menu entry root;

vmMenu 1 "Dummy Menu" Properties:
Menu – [select] –> Title
Pre commands:
jump titleset 1 menu entry root;
Menu 1 “Main Menu” Properties:
Video Object – Audio: [menu_audio]
Pre commands:

Pause: [select] -> Loopif (g0==0) jump menu 7; else button=g0;

Menu 1 button “Play” (button 1):
g0=1024; if (g1==0) jump title 1; else resume;
Menu 1 button “DVD-ROM Features” (button 2):
jump menu 6;
Menu 1 button “Chapters” (button 3):
jump menu entry ptt;
Menu 1 button “Links” (button 4):
jump menu 5;
Menu 2 “Chapter Menu Part 1":
Video Object – Audio: [chapter_audio]

Pause: [select] -> Loop

Menu Entry: [select] -> Chapter
Pre commands:
if (g0==0) jump menu 7; else { if (g1&1==1) button=5120;
else { if (g1/2<5) { if (g1==0) button=1024; else button=g1/2*1024; }else { if (g1/2<9) jump menu 3; else jump menu 4; } } }Menu 2 button “Chapter 1” (button 1):
if (g1&30==2) resume; else jump title 1 chapter 1;
Menu 2 button “Chapter 2” (button 2):
if (g1&30==4) resume; else jump title 1 chapter 2;

Example Structure 2 Part 2
Menu 2 button “Chapter 3” (button 3):
if (g1&30==6) resume; else jump title 1 chapter 3;
Menu 2 button “Chapter 4” (button 4):
if (g1&30==8) resume; else jump title 1 chapter 4;
Menu 2 button “Chapter Menu 1-4” (button 5):
g2=g1&30; g1=g2|1; jump menu entry ptt;
Menu 2 button “Chapter Menu 5-8” (button 6):
g2=g1&30; g1=g2|1; jump menu 3;
Menu 2 button “Chapter Menu 9-10” (button 7):
g2=g1&30; g1=g2|1; jump menu 4;
Menu 2 button “Main Menu” (button 8):
g2=g1&30; g1=g2; g0=3072; jump menu entry root;
Menu 3 "Chapter Menu Part 2":
Video Object – Audio: [chapter_audio]

Pause: [select] -> Loop

Pre commands:
if (g1&1==1) button=6114; else { if (g1/2<9) {if (g1/2>4)
button=(g1/2-4)*1024; else jump menu entry ptt; } else jump menu 4; }Menu 3 button “Chapter 5” (button 1):
if (g1&30==10) resume; else jump title 1 chapter 5;
Menu 3 button “Chapter 6” (button 2):
if (g1&30==12) resume; else jump title 1 chapter 6;
Menu 3 button “Chapter 7” (button 3):
if (g1&30==14) resume; else jump title 1 chapter 7;
Menu 3 button “Chapter 8” (button 4):
if (g1&30==16) resume; else jump title 1 chapter 8;
Menu 3 button “Chapter Menu 1-4” (button 5):
g2=g1&30; g1=g2|1; jump menu entry ptt;
Menu 3 button “Chapter Menu 5-8” (button 6):
g2=g1&30; g1=g2|1; jump menu 3;
Menu 3 button “Chapter Menu 9-10” (button 7):
g2=g1&30; g1=g2|1; jump menu 4;

Example Structure 2 Part 3
Menu 3 button “Main Menu” (button 8):
g2=g1&30; g1=g2; g0=3072; jump menu entry root;
Menu 4 "Chapter Menu Part 3":
Video Object – Audio: [chapter_audio]
Pause: [select] -> Loop
Pre commands:
if (g1&1==1) button=5120; else { if (g1/2>8) button=(g1/2-8)*1024;
else { if (g1/2>4) jump menu 3; else jump menu entry ptt; } }Menu 4 button “Chapter 9” (button 1):
if (g1&30==18) resume; else jump title 1 chapter 9;
Menu 4 button “Chapter 10” (button 2):
if (g1&30==20) resume; else jump title 1 chapter 10;
Menu 4 button “Chapter Menu 1-4” (button 3):
g2=g1&30; g1=g2|1; jump menu entry ptt;
Menu 4 button “Chapter Menu 5-8” (button 4):
g2=g1&30; g1=g2|1; jump menu 3;
Menu 4 button “Chapter Menu 9-10” (button 5):
g2=g1&30; g1=g2|1; jump menu 4;
Menu 3 button “Main Menu” (button 6):
g2=g1&30; g1=g2; g0=3072; jump menu entry root;
Menu 5 “Links”:
Video Object – Audio: [links_audio]

Pause: [select] -> Loop

Pre commands:

button=1024;

Menu 5 button “Main Menu” (button 1):g0=4096; jump menu entry root;

Menu 6 “DVD-ROM Features”:
Video Object – Audio: [dvd-rom_audio]

Pause: [select] -> Loop

Pre commands:

button=1024;

Menu 5 button “Main Menu” (button 1):

g0=2048; jump menu entry root;

Menu 7 “Main Menu Introduction Clip”:
Background – Image: [introduction_clip]
Post commands:

g0=1024; g1=0; jump menu entry root;Example Structure 2 Part 4
Title 1 "Main Title":
Pre commands:

if (g0==0) call menu entry root;

Post commands:

g0=1024; g1=0; call menu entry root;

Chapters Options:
0:00:00.000 – 0:00:01.000
0:00:01.000 – 0:09:25.231
0:09:25.231 – 0:09:26.231
0:09:26.231 – 0:19:25.231
0:19:25.231 – 0:19:26.231
0:19:26.231 – 0:28:28.172
0:28:28.172 – 0:28:29.172
0:28:29.172 – 0:38:17.364
0:38:17.364 – 0:38:18.364
0:38:18.364 – 0:45:47.814
0:45:47.814 – 0:45:48.814
0:45:48.814 – 0:56:07.634
0:56:07.634 – 0:56:08.634
0:56:08.634 – 1:06:09.435
1:06:09.435 – 1:06:10.435
1:06:10.435 – 1:16:12.439
1:16:12.439 – 1:16:13.439
1:16:13.439 – 1:21:01.326
1:21:01.326 – 1:21:02.326
1:21:02.326 – 1:25:09.442

Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;
Chapter;
Regular;Commands:

g1=2;

Commands:

g1=4;

Commands:

g1=6;

Commands:

g1=8;

Commands:

g1=10;

Commands:

g1=12;

Commands:

g1=14;

Commands:

g1=16;

Commands:

g1=18;

Commands:

g1=20;

List of variable values and their meanings
g0
first play test;
Main Menu button control; = button number * 1024
g1
Chapter Menu button control;
if bit 1 = 1, the particular portion of the chapter menu was forcibly
displayed, therefore, highlight the button for the present menu;
if bit 1 = 0, the chapter menu was auto-navigated, therefore bits 2-5 should
be checked to highlight the present chapter;
present chapter in bits 2-5 = g1&30 / 2; the first calculation finds the valueof bits 2-5 and the second divides the number by 2 to produce the current
chapter;Thanks for reading along! Happy authoring!

Best Regards,

JonathanFurther Resources
The following websites may prove useful.
DVDStyler Help Forum
DVDStyler Wiki FAQCreating New Buttons for DVDStyler
The dvdauthor man pageThe dvdauthor man page for spumux - subpicture & subtitle renderer and muxer
For the ambitious - subtitling via Linux command line with spumux
DVD Videos on Linux and Unix - format information
DVD specifications - everything you wanted to know about the architectureThis is useful for cell commands when checking if a command passed to
dvdauthor will compile to a single command for a DVD-player. In the section
titled Virtual Machine Coding, see the link titled Command Details.
Another page with DVD specifications
Retail site wanting to sell you unofficial DVD specs; some free info nonethelessBasic reference for using FFmpeg
In addition to being an excellent introduction to and reference for FFmpeg, thisis useful for selecting and configuring command line video filters for the Video
Properties window.
Wikipedia's page on NTSC
Wikipedia's page on PAL
Wikipedia's page on overscan
Wikipedia's page on interlaced video
Wikipedia's page on progressive scan video
Wikipedia's page on MPEG-2 encoding, used for DVD-Video
Wikipedia's page on Pan and Scan display mode
Wikipedia's page on Letterbox display modeAcknowledgements
DVDStyler Program Author: Alex Thüring <alex@thuering.biz>
Guide Author: Jonathan Blair <need-more-input@users.sourceforge.net>
Proofreaders:Alex Thüring <alex@thuering.biz>
Contributors:

Revision History
1.03

1.02

1.01
1.00

Cell command functionality corrected per DVDStyler 1.8.4
specifications and requirements / limitations added to scripting
section; angle functionality tests suggested as appropriate; chapter
options, video and menu encoding expanded with updated window
properties and placed before scripting section; Menu Errata edited toreflect flexibility in menu flag choices; introduction and purpose of
scripting section added; cell command example structure added;
FFmpeg command-line reference added.
Revision History added; corrected guide to demonstrate the partial
support of background video in menus; removed resume location
preservation and conditional menu transitions with use of video-inmenu transitions; revised subtitle track / stream number value
description; revised chapter navigation; expanded play-all button
demonstration to include play-list functionality; added parenthesis toretrieval command in bitwise logic diagram for clarity; vastly
simplified example structure by video-in-menu transitions andformatted description for easier reading.
Chapter point time format revised; various typos fixed (thanks Alex!).
All sections, less Revision History included.
To Do (in no particular order)
Demonstrate full subtitle / audio menu commands; write explanationof command compilation to explain limitation of cell commands.

GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
<http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copiesof this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or otherfunctional and useful document "free" in the sense of freedom: toassure everyone the effective freedom to copy and redistribute it,with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleftlicense designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a freeprogram should come with manuals providing the same freedoms that thesoftware does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONSThis License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants aworld-wide, royalty-free license, unlimited in duration, to use thatwork under the conditions stated herein. The "Document", below,
refers to any such manual or work. Any member of the public is alicensee, and is addressed as "you". You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A "Modified Version" of the Document means any work containing theDocument or a portion of it, either copied verbatim, or withmodifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is inpart a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal,commercial, philosophical, ethical or political position regardingthem.
The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the noticethat says that the Document is released under this License. If asection does not fit the above definition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says thatthe Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to thegeneral public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed ofpixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters orfor automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent fileformat whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amountof text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGMLor XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples oftransparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and themachine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works informats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies of
the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements","Dedications", "Endorsements", or "History".) To "Preserve the Title"of such a section when you modify the Document means that it remains asection "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice whichstates that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in thisLicense, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, thecopyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add noother conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enoughnumber of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, andyou may publicly display copies.

3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly haveprinted covers) of the Document, numbering more than 100, and theDocument's license notice requires Cover Texts, you must enclose thecopies in covers that carry, clearly and legibly, all these CoverTexts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent andvisible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treatedas verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacentpages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensurethat this Transparent copy will remain thus accessible at the statedlocation until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of theDocument well before redistributing any large number of copies, togive them a chance to provide you with an updated version of theDocument.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copyof it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions(which should, if there were any, be listed in the History sectionof the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of theDocument (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license noticegiving the public permission to use the Modified Version under theterms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.

I. Preserve the section Entitled "History", Preserve its Title, and add
to it an item stating at least the title, year, new authors, andpublisher of the Modified Version as given on the Title Page. If
there is no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document asgiven on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section.
You may omit a network location for a work that was published atleast four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections orappendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or allof these sections as invariant. To do this, add their titles to thelist of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of astandard.
You may add a passage of up to five words as a Front-Cover Text, and apassage of up to 25 words as a Back-Cover Text, to the end of the listof Cover Texts in the Modified Version. Only one passage ofFront-Cover Text and one of Back-Cover Text may be added by (orthrough arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under thisLicense, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of theInvariant Sections of all of the original documents, unmodified, andlist them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, andmultiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique byadding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list ofInvariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and otherdocuments released under this License, and replace the individual
copies of this License in the various documents with a single copythat is included in the collection, provided that you follow the rulesof this License for verbatim copying of each of the documents in allother respects.
You may extract a single document from such a collection, anddistribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow thisLicense in all other respects regarding verbatim copying of that
document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rightsof the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to thesecopies of the Document, then if the Document is less than one half ofthe entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the wholeaggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to theoriginal versions of these Invariant Sections. You may include atranslation of this License, and all the license notices in theDocument, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versionsof those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a noticeor disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements","Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, andwill automatically terminate your rights under this License.
However, if you cease all violation of this License, then your licensefrom a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finallyterminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder isreinstated permanently if the copyright holder notifies you of theviolation by some reasonable means, this is the first time you havereceived notice of violation of this License (for any work) from thatcopyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate thelicenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the
GNU Free Documentation License from time to time. Such new versions
will be similar in spirit to the present version, but may differ indetail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of thisLicense "or any later version" applies to it, you have the option offollowing the terms and conditions either of that specified version orof any later version that has been published (not as a draft) by theFree Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (notas a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of thisLicense can be used, that proxy's public statement of acceptance of aversion permanently authorizes you to choose that version for theDocument.
11. RELICENSING"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A"Massive Multiauthor Collaboration" (or "MMC") contained in the sitemeans any set of copyrightable works thus published on the MMC site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,California, as well as future copyleft versions of that license
published by that same organization.

"Incorporate" means to publish or republish a Document, in whole or inpart, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under thisLicense, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole orin part into the MMC, (1) had no cover texts or invariant sections, and(2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright andlicense notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNUFree Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with...Texts." line with this:with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some othercombination of the three, merge those two alternatives to suit thesituation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.