<chapter id="project-wizard-format">
	<title>New Project Wizard format</title>
	<para>
		The new project wizard has been rewritten for Anjuta 2. It
		is a generic plugin able to create different kind of projects.
		The files needed by each project and the associated graphical
		interface used to get user choices are defined in a text file
		read by the plugin. This documentation will described the
		format of this file which is called a template.
	</para>

	<sect1 id="overview">
		<title>Overview</title>
		<para>
			The template files <emphasis>look like</emphasis>
			xml documents and have normally the extension
			<filename>.wiz</filename>. All templates and others
			related files are installed by default in <filename>$anjuta_install_dir/share/anjuta/templates</filename>. But the project wizard looks
			for templates in the sub directory <filename>anjuta/templates</filename> of
			all user data directories as defined by
			<ulink type="http" url="http://www.freedesktop.org/Standards/basedir-spec">XDG Base Directory Specification</ulink> too. It is possible to
			override a Anjuta project template by an user one put, 
			by example, in <filename>~/.local/share/anjuta/templates</filename>.
		</para>
		<para> The template file is divided in four parts:
			an header block, one or more page blocks, a content block
			and an optional action block. The file is read several times, one
			time for each block but before reading it,
			the whole file go though a transformation pass and only
			the resulting file must be a valid xml file. The transformation
			pass use <ulink url="http://autogen.sourceforge.net">autogen</ulink>.
		</para>
		<para>
		<emphasis>Autogen</emphasis> is a quite complete text transformation program, 
		it is able to make string substitutions, conditionally
		generate text, include files and it can even be extended with the
		guile language. Autogen takes as input a template file which is
		the wizard template file and some definitions which are generated
		at run time according to the user choices. Note that the first
		line of an autogen template need to have special format not
		compatible with an xml file, so this line is added at run time
		when needed. It defines the
		start and end macros marker of autogen which is fixed and
		defined as "[+" and "+]" in the wizard template.
		</para>
		<para>
		All blocks on the project wizard are included in a <emphasis>project-template
		</emphasis> block. This is needed because a valid XML file should have a
		single root block. This block was not used in older version of the format,
		so it is optional to keep backward compatibility.
		</para>
		<para>
		The <emphasis>header</emphasis> block is the only exception, it is read 
		directly from the template file and do not use autogen.
		It must be the first block and must be valid a xml
		block, that's why the first line of the template could not
		contains the autogen special line. The parsing is stopped when
		 the end of this block is
		reached, so we do not care for the remaining of the file. This
		block contains informations about the project kind like a name and
		a short description.
		</para>
		<para>
		The <emphasis>page</emphasis> blocks are read one by one after being transformed by
		autogen, they define some properties of the project which could
		be changed by the user, things like project name or use of a
		particular library. The graphical interface is created at run
		time according to these properties. Each page is generated when
		the user has completed all previous pages.
		You can ask the user for something on one
		page and his answers become available as autogen variables for
		generating the next page. You can, by example, skip a complete page
		for configuring a CVS reposit, if the user has decided to
		not use it. In case you insert or remove a complete page you need
		to take care to not do it before one already displayed.
		</para>
		<para>
		When all pages have been displayed. The program will read the <emphasis>content</emphasis>
		block which defined all files and directories needed by the project.
		This block goes through autogen so you can use this to adjust file
		names and paths. Typically, at least creating a project file with
		the name given by the user. Note that the project files itself are
		transformed with autogen if needed.
		</para>
		<para>
		Finally, if it exist the <emphasis>action</emphasis> block is read and the
		corresponding commands are executed in their order of apparition.
		Typically, it is useful for
		loading in Anjuta the newly created project.
		</para>
	</sect1>
	<sect1 id="header-block">
		<title>Wizard header</title>
		<para>
			Here is all the xml element used in the header block.
			As this block is read directly from the file, it
			can not contains autogen variables.
		</para>
		<para>
			<emphasis>project-wizard</emphasis>
			<programlisting>
&lt;project-wizard&gt;
	&lt;_name&gt;
	&lt;_description&gt;
	&lt;icon&gt;
	&lt;category&gt;
&lt;/project-wizard&gt;
			</programlisting>
			It represents the header block, and contains all other
			elements.
		</para>
		<para>
			<emphasis>name</emphasis>
			<programlisting>
&lt;_name&gt;
	text				
&lt;/_name&gt;
			</programlisting>
			text is the name of the project, its name start with
			a underscore to mark a translatable element.
		</para>
		<para>
			<emphasis>description</emphasis>
			<programlisting>
&lt;_description&gt;
	text				
&lt;/_description&gt;
			</programlisting>
			text gives a short description of the project, it appears when
			the project is selection. It's a translatable element too 
			which explains the underscore.
		</para>
		<para>
			<emphasis>icon</emphasis>
			<programlisting>
&lt;_icon&gt;
	filename				
&lt;/_icon&gt;
			</programlisting>
			filename is the name of the file containing a icon for
			the project, it must be in the same directory than the
			project template file. The picture must be of 48 by
			48 pixels in png format.
		</para>
		<para>
			<emphasis>category</emphasis>
			<programlisting>
&lt;_category&gt;
	text					
&lt;/_category&gt;
			</programlisting>
			text is a category name. It is a way to group related
			project, it is typically the programming language name,
			like C or C++.
		</para>
		<para>
			<emphasis>order</emphasis>
			<programlisting>
&lt;_order&gt;
	number					
&lt;/_order&gt;
			</programlisting>
			number is used to order project in the project
			selection view. If this element is not specified order
			is equal to 0. In this case, the projects are added
			at the end ordered according to their names.
		</para>
	</sect1>
	<sect1 id="page-block">
		<title>Wizard pages</title>
		<para>
			This block defines all properties use by the project
			and the corresponding graphical interface. These properties
			are grouped in pages. Each page is read and transform with
			autogen one by one taking in account the value of all properties
			already defined in previous pages. This allows you
			to generate pages according to the user inputs on the previous one.
		</para>
		<para>
			<emphasis>page</emphasis>
			<programlisting>
&lt;page name=name _label=label _description=description &gt;
	&lt;property&gt;
	...
&lt;/page&gt;
			</programlisting>
			<para>
				It represents one page block and contains a set of properties.
			</para>
			<para>
				name is the name of the page, currently unused.
			</para>	
			<para>
				label is the title of the page, it is a translatable
				attribute.
			</para>
			<para>
				description is a translatable sub title for the project page.
			</para>
		</para>
		<para>
			<emphasis>property</emphasis>
			<programlisting>
&lt;property type=hidden|boolean|integer|string|list|directory|file|icon|package
	name = name _label=label [_description=description] [default=default]
	[mandatory=yes|no] [exist=yes|no] [summary=yes|no] &gt;
	[&lt;item&gt;]
	...
&lt;/property&gt;
			</programlisting>
			<para>
				This is one of the most important element. A property
				correspond to an entry widget to get the user choice
				and a variable in the autogen definition file used to
				control the generation of the project.
			</para>
			<para>
				The type attribute define the kind of property. The following
				types are defined
				<variablelist>
					<varlistentry><term>hidden</term>
						<listitem>
							<para>
							This is the only property that does
							not correspond to any widget. This
							is useful to defined additional
							autogen variables using only
							name and default attributes. As this
							value cannot be changed by the user
							the default attribute defined the
							value of the property.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>boolean</term>
						<listitem>
							<para>
							This correspond to a boolean variable.
							It is represented by a toggle button. The
							value is 1 if the user select Yes, and 0
							if the user select No.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>integer</term>
						<listitem>
							<para>
							This correspond to a integer number. It
							is represented by a spin button. The
							value is the corresponding number.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>string</term>
						<listitem>
							<para>
							This is a string value represented by
							an entry box. The value is the text
							of this entry box.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>list</term>
						<listitem>
							<para>
							This property takes its value in
							a list of values and is represented
							by a list box. All the values
							are defined with child item
							element defined below. The value of
							the property is defined by the name
							attribute of the corresponding item.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>directory</term>
						<listitem>
							<para>
							This property get a directory selected
							by the user. The directory could be
							inexistent, see the exist attribute for
							more information. It looks like a string
							property with a Browse button.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>file</term>
						<listitem>
							<para>
							This property get a file selected
							by the user. It is very similar to
						       	the directory property.
							</para>
						</listitem>
					</varlistentry>	
					<varlistentry><term>icon</term>
						<listitem>
							<para>
							This property is quite similar to the
							file property and allow you to select
							an icon. The property value will be
							the name of the file containing the icon.
							</para>
						</listitem>
					</varlistentry>
					<varlistentry><term>package</term>
						<listitem>
							<para>
							This property is similar to the file
							property and allow you to select a
							pkg-config package. It displays an entry
							box, that you can fill directly, with a
							button allowing to display all
							installed packages and select one.
							The property value will be
							the name of the package.
							</para>
						</listitem>
					</varlistentry>	
				</variablelist>
			</para>
			<para>
				name is the name of the autogen variable corresponding
				to this property.
			</para>
			<para>
				label is a translatable label that appears near the entry
				widget.
			</para>
			<para>
				description is a translatable description that appears
				as a tips of the entry widget.
			</para>
			<para>
				default is the default value of the property. If none is
				specified the property is empty.
			</para>
			<para>
				minimum is the minimum value for an integer property.
				If none is specified the minimum value is 0.
			</para>
			<para>
				maximum is the maximum value for an integer property.
				If none is specified the maximum value is 10000.
			</para>
			<para>
				step is the increment step when clicking on the arrow buttons or
				using the cursor key, you can always write another value in the
				allowed range.
				If none is specified the value is incremented or decremented by 1.
			</para>
			<para>
				mandatory allow you to define if an empty value is
				acceptable, by default it is allowed. If you set it to
				yes and the user does not enter a value, he will get an
				error message and cannot go further.
			</para>
			<para>
				exist allow to check if a file or a directory
				corresponding to the value of the property exist. If exist
				is set to no, a warning message is displayed if the file or
				the directory exist. Moreover the value of the default
				property is tested and a number is automatically added at the end
				to avoid the warning message if necessary.
				By default or if exist is set to yes,
				no check is made.
			</para>
			<para>
				summary defined if the property and its value should
				appears at the end of the wizard. This happens if the
				attribute is set to yes, by default or if it is set to no
				the property is not displayed.
			</para>
		</para>
		<para>
			<emphasis>item</emphasis>
			<programlisting>
&lt;item _name=name [_label=label] /&gt;
			</programlisting>
			<para>
			This element is used to defined item of a list property.
			</para>
			<para>
				name is the name of the item, the property variable will be
				set with this value if the item is selected.
			</para>
			<para>
				label is an optional translatable name for this item.
				This label will be used translated in the graphical
				interface, typically a list box. If it does not exist
				the value of the name attribute is used.
			</para>
		</para>
	</sect1>
	<sect1 id="content-block">
		<title>Wizard content</title>
		<para>
			This block defines all files and directories used by the
			project.
		</para>
		<para>
			<emphasis>content</emphasis>
			<programlisting>
&lt;content&gt;
	&lt;directory&gt;
	...
&lt;/content&gt;
			</programlisting>
			<para>
			It represents the content block and contains any number
			of directory elements.
			</para>
		</para>
		<para>
			<emphasis>directory</emphasis>
			<programlisting>
&lt;directory source=source_name [destination=destination_name] &gt;
	&lt;directory&gt;
	...
	&lt;file&gt;
	...
&lt;/directory&gt;
			</programlisting>
			<para>
			This element will define the source and destination
			directory for included files and directories. By 
			default the source directory is the directory of the
			wizard template file, the destination directory is the
			current directory. You can put "." instead of a directory
			name to stay in the current directory. It is useful if you want
			to change the destination directory but not the source or the
			reverse. If you specify only the source directory, the
			destination will use the same value.
			</para>
		</para>
		<para>
			<emphasis>file</emphasis>
			<programlisting>
&lt;file source=source_name [destination=destination_name] [executable=yes|no] [autogen=yes|no] /&gt;
			</programlisting>
			<para>
			This element will copy a file name source_name to destination_name
			using the currently defined source and destination directories.
			If not specified, the destination name will be the name of the
			source file.
			</para>
			<para>
			The executable attribute allows to specify if the execute flag of
			the destination should be set, by default a file is not executable.
			The permission of the source file is not used.
			</para>
			<para>
				The autogen attribute allows to specify if the file must be
				transform or not by autogen. By the default the first line
				of the file is tested to recognize an autogen template. If autogen
				is used, the
				file will get all definitions those have been used for
				generating the content block of the wizard template.
			</para>
		</para>
	</sect1>
	<sect1 id="action-block">
		<title>Wizard actions</title>
		<para>
			This block is optional, it defines additional actions to do after
			creating the project.
		</para>
		<para>
			<emphasis>action</emphasis>
			<programlisting>
&lt;action&gt;
	&lt;run&gt;
	...
	&lt;open&gt;
	...
&lt;/action&gt;
			</programlisting>
			<para>
			It represents the action block and contains any number
			of run and open elements. All these actions are executed in order.
			</para>
		</para>
		<para>
			<emphasis>run</emphasis>
			<programlisting>
&lt;run command=command /&gt;
			</programlisting>
			<para>
				This element allow to run the command command after creating
			       	the new project. The output of the command is redirected to
				one Anjuta message window.
			</para>
		</para>
		<para>
			<emphasis>open</emphasis>
			<programlisting>
&lt;open file=file_name /&gt;
			</programlisting>
			<para>
				This element will open the file file_name
				in Anjuta.
			</para>
		</para>
	</sect1>
	<sect1 id="internationalization">
		<title>Internationalization</title>
		<para>
			The newer version of the project wizard format, used by Anjuta 2.31 and
			greater, supports the standard xml:lang attribute. So the translation
			can be merged in the .wiz file considering it as an xml file and
			using standard tools. The attributes having a name starting with '_'
			are considered as translatable.
		</para>
		<para>
			The translation tools (intltool-merge) has to
			recognized the .wiz as an .xml file before being preprocessed by
			<emphasis>autogen</emphasis>. This adds additional constraints when
			writing the .wiz file, in particular you have to take care of
			quoting in attribute values. In addition, you need to have the 
			<emphasis>project-template</emphasis> root node. So your template
			will not be compatible with older version of Anjuta.
		</para>
	</sect1>
	<sect1 id="distribution">
		<title>Distribution</title>
		<para>
			You can write your own project template and distribute them in a gzip
			compressed tar file. The archive has to included all files needed by
			your template.
		</para>
		<para>
			With Anjuta version 2.30 or below, the user has to decompress this archive
			in a directory named <filename>anjuta/templates</filename> in the data
			directory defined according to 
			<ulink type="http" url="http://www.freedesktop.org/Standards/basedir-spec">XDG Base Directory Specification</ulink>.
			With Anjuta version 2.31 or greater, if you name your archive with the
			extension <filename>.wiz.tgz</filename> the template will be automatically
			installed and then executed if used as anjuta argument.
		</para>
	</sect1>
</chapter>
