[Blends-commit] [SCM] blends-gsoc branch, master, updated. ba66d82a011f6196d755464a3c47bfba43a45026
Emmanouil Kiagias
e.kiagias at gmail.com
Tue Sep 24 18:16:20 UTC 2013
The following commit has been merged in the master branch:
commit ba66d82a011f6196d755464a3c47bfba43a45026
Author: Emmanouil Kiagias <e.kiagias at gmail.com>
Date: Tue Sep 24 20:16:17 2013 +0200
added doc/en/A_devel.xml converted documentation, remember the TODOs comments in the end of the page. Conversion completed so it's time to fix all the TODOs of the all the pages
diff --git a/doc/debian-blends.en.xml b/doc/debian-blends.en.xml
index f7d0319..6a2733c 100644
--- a/doc/debian-blends.en.xml
+++ b/doc/debian-blends.en.xml
@@ -13,6 +13,7 @@
<!ENTITY ch-starting SYSTEM "en/07_starting.xml">
<!ENTITY ch-websentinel SYSTEM "en/08_websentinel.xml">
<!ENTITY ch-todo SYSTEM "en/09_todo.xml">
+ <!ENTITY ap-devel SYSTEM "en/A_devel.xml">
<!ENTITY ap-quickintro SYSTEM "en/B_quickintro.xml">
<!ENTITY ap-bts SYSTEM "en/C_bts.xml">
@@ -32,6 +33,7 @@
&ch-websentinel;
&ch-todo;
+ &ap-devel;
&ap-quickintro;
&ap-bts;
diff --git a/doc/en/A_devel.xml b/doc/en/A_devel.xml
new file mode 100644
index 0000000..22abcce
--- /dev/null
+++ b/doc/en/A_devel.xml
@@ -0,0 +1,833 @@
+ <appendix id="DevelDescription">
+ <title>Description of development tools</title>
+ <sect1 id="blends-dev">
+ <title>Package <package>blends-dev</package></title>
+
+<para>
+If metapackages are builded using the tools inside the
+<package>blends-dev</package> package it can be ensured that the
+resulting metapackages will work nicely with the same version of
+<package>blends-common</package> package. The goal is to keep
+necessary changes for the source of the metapackages of a Debian Pure
+Blend as low as possible when the version of the
+<package>blends</package> source package changes. Thus it is
+strongly recommended to use the tools described below.
+</para>
+<para>
+The usage of the tools in the <package>blends-dev</package> package might
+introduce a versioned dependency in the
+<varname><blend></varname>-<package>config</package> package from which
+all other metapackages of the <varname>Blend</varname> in question will
+depend. This <varname><blend></varname>-<package>config</package> package
+instantiates the <varname>Blend</varname> in the common registry for all Blends in
+<filename>/etc/blends</filename>.
+</para>
+
+<para>
+The version <package>0.7.0</package> of <package>blends-dev</package> uses
+<ulink url="https://wiki.debian.org/UltimateDebianDatabase">UDD</ulink>
+to generate Blends' metapackages. Currently all Blends' info is stored into UDD.
+Information such as VCs, description, homepage etc for a Blend can be found into the
+<ulink url="http://udd.debian.org/schema/udd.html#public.table.blends-metadata">blends_metadata</ulink>
+UDD table. All the info about Blends' tasks and their package dependencies are also stored
+into the <ulink url="http://udd.debian.org/schema/udd.html#public.table.blends-tasks">blends_tasks</ulink> and
+<ulink url="http://udd.debian.org/schema/udd.html#public.table.blends-dependencies-alternatives">
+blends_dependencies_alternatives</ulink>
+tables. Having the latter in combination with other UDD tables
+(such as a table with info about all Debian available packages)
+provides the ability to check whether a package exists for an architecture or not thus
+<package>blends-dev</package> can generate architecture dependent metapackages.
+</para>
+
+<para>
+The best idea to use the tools provided by the
+<package>blends-dev</package> is to put a <filename>Makefile</filename> into the
+build directory containing one single line
+
+<informalexample>
+ <programlisting>
+ include /usr/share/blends-dev/Makefile
+ </programlisting>
+</informalexample>
+
+(see <filename>/usr/share/doc/blends-dev/examples/Makefile</filename>).
+Users using <package>blends-dev 0.7.0</package> on existing Blends
+which have more than one releases might encouter some <filename>Makefile</filename>
+errors for more info see <xref linkend="statusdump"/> and <xref linkend="changelogentry"/>.
+
+Using this <filename>Makefile</filename> all tools that were contained in
+<package>blends-dev</package> package versions before 0.4. These tools
+are moved to <filename>/usr/share/blends-dev/</filename> because there is no need
+to call them directly. Here is a list of the <filename>make</filename> targets.
+</para>
+
+<sect2 id="blends-tasks.desc">
+ <title>Blend<package>-tasks.desk</package></title>
+
+<para>
+This target generates a <package>task-description.template</package> file.
+The template can be converted to a proper description file that is used in
+<package>tasksel</package> to enable selecting the tasks belonging to the Blend.
+The initial template contains all the needed package dependencies
+for a Blend. But because some packages might not be available for a(or multiple)
+architectures the template uses the following syntax when specifying packages:
+<informalexample><programlisting> package1 [!arch1 arch2]</programlisting></informalexample>
+
+That says do not include the package1 in the
+taskdescription file when arch1 or arch2 is used.
+When a Blends' <package>orig.tar.gz</package> is generated,
+the initial template gets converted
+from the <package>blends-dev rules</package> file to a proper taskdescription file.
+The convertion is filtering out the packages which are not available for the
+host's (where the <package>orig.tar.gz</package> is generated) architecture.
+This make sure that the taskdescription file will not include package which are
+not available for the target architecture.
+Finally the file will be moved to the
+<varname>blend</varname><package>-tasks</package>. All information
+about Blends package dependencies is obtained from the UDD.
+</para>
+
+</sect2>
+<sect2 id="debian_control">
+ <title><filename>debian/control</filename></title>
+
+<para>
+The <filename>debian/control</filename> file of a Blend metapackage source
+archive is auto generated out of dependencies that are specified in so
+called <filename>tasks</filename> files. The rationale behind this is to
+enhance flexibility about changes inside the Debian package pool where
+new packages might appear and others might be renamed.
+The <filename>tasks</filename> just define which dependencies the Blend
+maintainer group wants to be fulfilled and the
+script <package>blend-gen-control</package> using UDD verifies whether these
+dependencies exist in a specified package pool. A
+package pool can be considered as the packages available for a
+combination of distribution, component and release values. By default when
+creating metapackages debian,main,testing values are used to "create" a package pool from UDD.
+Once a Blends' dependencies are verified the <filename>debian/control</filename> file is generated
+according to the available packages. This does not only work for the Debian package pool
+containing the distributions stable, testing and unstable. You can
+even build your metapackages against a different package pool of a
+Debian based distribution. This is for instance used to create the
+SkoleLinux metapackages.
+</para>
+
+<para>
+As mentioned in the previous section, using UDD in Blends' tools provides the ability to generate
+architecture dependent metapackages. Thus the generated
+<package>debian/control</package> specifies for every task source target as architecture value:
+<informalexample>
+ <programlisting>Architecture: any</programlisting></informalexample>
+
+Specifying <package>any</package> indicates that the source package isn't dependent
+on any particular architecture and should compile fine on any one. To fulfil this
+in case of missing packages <package>control</package> file uses the following syntax:
+
+<informalexample>
+ <programlisting>Depends: package1 [!arch1 !arch2]</programlisting></informalexample>
+
+If a package is not available for a specific arch, exclude it from it. So the above example says:
+depend on package1 but not when architecture arch1 or arch2 is used. More info about
+<package>debian/control</package> syntax can be found in
+<ulink url="http://www.debian.org/doc/debian-policy/">Debian Policy Manual</ulink>
+</para>
+
+<para>
+The syntax of the <filename>tasks</filename> files which serve as the central
+database for the information in the <filename>debian/control</filename> file
+is defined by RFC822. Some of the tags were mentioned formerly in
+<xref linkend="packageslist"/> to explain how the <filename>tasks</filename> files
+can be used to create the web sentinel pages. Now the tags that
+influence the creation of the <filename>debian/control</filename> file are given.
+</para>
+<para>
+ <variablelist>
+
+ <varlistentry>
+ <term>Depends</term>
+ <listitem><para>Will be turned to "Recommends" in the
+ resulting <filename>debian/control</filename> file. The
+ rationale behind this is to enable installing the
+ metapackage even if a package belonging to this task is
+ missing for whatever reason. It also allows finally to
+ remove the metapackage. This makes even more
+ sense since <package>apt-get</package> considers "Recommends"
+ as default installation targets.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Recommends</term>
+ <listitem><para>The packages that are listed as "Recommends" in the
+ tasks file should be installed on the machine where the
+ metapackage is installed and which are needed to work
+ on a specific task.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Suggests</term>
+ <!-- [BA] Why would we suggest non-free? Doesn't policy allow a non-free
+ package to specify "Enhances" to avoid this problem?
+ [AT] I have to admit that "Enhances" is new to me. When
+ reading policy I think this field is out of control of
+ the metapackage developer because it has to be included
+ by the package maintainer. I'm not really convinced that
+ this is a good solution - but I would follow the suggestions
+ of others in this issue.
+ -->
+ <listitem><para>Use "Suggests" for packages of lesser importance that
+ might be possibly useful, or non-free packages.</para>
+ <para>
+ If a package is not available in the package pool of the
+ target distribution when creating
+ the <filename>debian/control</filename> file inside the meta
+ package source archive any "Depends" or "Recommends" are
+ turned into "Suggests" to enable a flawless installation
+ of the metapackage. Generally packages are concerned as missing if
+ they do not exist into Debian main component(default is testing release).
+ Packages that are specified with
+ "Suggests" will not be taken over to
+ the <package>tasksel</package> control file
+ (Blend<filename>-tasks.desk</filename>,
+ see <xref linkend="blends-tasks.desc"/>) but only to the list of
+ suggested packages of the according metapackage.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Ignore</term>
+ <listitem><para>The "Ignore" key can be used as kind of "Soft-Suggests"
+ to put a package on the radar of the Blend. Packages that
+ are tagged with Ignore will not be taken over into the
+ list of dependencies inside
+ the <filename>debian/control</filename> file of the resulting
+ metapackage neither to the Blend<filename>-tasks.desk</filename>
+ control file for <package>tasksel</package> but will be taken
+ over onto the installation medium of a Blend in case there
+ is some space left. This key becomes especially
+ important for specifying not yet packaged software that
+ might be packaged in the future (prospective packages).
+ This is explained in detail in the paragraph about the
+ web sentinel (see <xref linkend="packageslist"/>).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Avoids</term>
+ <listitem><para>The "Avoids" key specifies existing packages that will
+ be listed in the the <filename>debian/control</filename> file as
+ "Recommends" or "Suggests" but, should not go to a
+ installation medium (CD, DVD, etc.) that might be
+ produced by the Blend. A reason to avoid a package might
+ be that it belongs to the non-free section.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+</para>
+</sect2>
+
+<sect2 id="statusdump">
+ <title><package>statusdump</package></title>
+
+<para>
+This target generates a json file containing the latest package dependencies
+for the selected Blend. It parses the files from the <package>tasks</package> directory
+and generates a <varname>blend</varname><package>_version.json</package> into a <package>dependency_data</package>
+directory. As <package>version</package> it gets the latest version specified in the Blend's
+<package>debian/changelog</package> file. In case the <package>dependency_data</package> directory
+does not exist into a Blend's root directory it automatically creates it.
+</para>
+
+<para>
+A user can also generate a json dependencies file manually
+using the <package>tasks_diff</package> script. The script can be called
+from a Blend's root directory:
+
+<informalexample>
+ <programlisting>
+ /usr/share/blends-dev/task_diff --status-dump --tasks . --output blend_version.json
+</programlisting>
+</informalexample>
+If the user does not specify the output argument the script by default
+will generate the json file under the <package>tasks.json</package> name in the
+current directory.
+</para>
+
+<para>
+Note: in case a user needs to generate a json file for a previous release
+(rather than the latest) to get the <package>changelogentry</package>
+(see <xref linkend="changelogentry"/>) target to work, must keep the following thing in mind:
+
+The user must provide to <package>task_diff</package> script the <emphasis>root</emphasis> directory of a previous Blend release
+(through the --task(-t) argument). He should also save the output into the <package>dependency_data</package>
+directory into the latest Blend release providing manually
+the name <varname>blend</varname><package>_version.json</package> (through the --output(-o) argument:
+
+<informalexample>
+ <programlisting>
+/usr/share/blends-dev/task_diff --status-dump -t blend/tags/previous/ -o latest_blend/dependency_data/blend_version.json
+</programlisting>
+</informalexample>
+
+For example if the name of the Blend is <package>myblend</package> and the release is <package>0.2.0</package>
+then the json file must have the name <package>myblend_0.2.0.json</package>
+</para>
+
+</sect2>
+
+<sect2 id="changelogentry">
+ <title>changelogentry</title>
+
+<para>
+This target compares the latest and the previous Blend release and dumps the tasks'
+package differences. It reports the added/removed packages
+per task (or added/removed task files)
+between releases. This "report" is automatically
+added into the <filename>debian/changelog</filename>
+in the latest relase section under the file's manual changes.
+In case a previous difference report
+exists, it overrides it. In case a Blend does not have more than release
+(initial release) then this target is ignored.
+</para>
+
+<para>
+In order the comparison to be properly performed the
+<varname>blend</varname><filename>_version.json</filename> files for the two latest releases
+must exist under the <filename>dependency_data</filename> directory. In case any of the
+previous files is missing then the target will fail with an error
+(specifying the missing version_file). The json file for the latest
+release is automatically generated from the <package>statusdump</package> target
+so it this will not cause the problem.
+</para>
+
+<para>
+This changelog entry is a new feature so the problem of this target failing
+(because of a missing json file) will appear for existing Blends which have
+more than one releases and do not have a <varname>blend</varname><filename>_version.json</filename>
+for the previous release under their <filename>dependency_data</filename> directory.
+Usually Blend's releases are tagged into the VCs, so the previous problem
+can be solved by generating the dependency json file for the previous
+release (using a previous VCs tag). This can be done by calling manually
+the <package>task_diff</package> script (see <xref linkend="statusdump"/>)
+</para>
+
+</sect2>
+
+<sect2>
+ <title>Apt <filename>sources.list</filename> files in <filename>/etc/blends/</filename></title>
+<para>
+These files are used by <!-- <manref name="blend-gen-control" section="1"> --> to
+build valid <filename>debian/control</filename> files that contain only
+available packages in their dependencies. This enables building meta
+packages for <package>stable</package>, <package>testing</package>, <package>unstable</package> or
+even a completely different distribution that has valid
+<filename>sources.list</filename> entries. The file
+<filename>/etc/blends/control.list</filename> is used as default for <!-- <manref
+name="blend-gen-control" section="1"> --> and usually is a symbolic link
+(see <!-- <manref name="ln" section="1"> -->) to
+<filename>sources.list.</filename><varname>distribution</varname>. It might be
+changed using the <package>-s </package><varname>dist</varname> option of <!-- <manref
+name="blend-gen-control" section="1"> -->.
+</para>
+<para>
+<emphasis>TODO:</emphasis> <emphasis>Either parse the available
+<filename>/etc/apt/sources.list</filename> or use a sane <orgname>debconf</orgname>
+question to use the "nearest" mirror.</emphasis>
+</para>
+</sect2>
+
+<sect2>
+ <title>Templates in <filename>/usr/share/blends/templates</filename></title>
+<para>
+The directory <filename>/usr/share/blends/templates</filename> contains templates
+that can be used to build a <varname><blend></varname><package>-config</package>,
+which uses the tools that are contained in the
+<package>blends-common</package> package, and are useful to manage
+<varname><blend></varname> user groups (see <xref linkend="userroles"/>).
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="blends-common">
+ <title>Package <package>blends-common</package></title>
+
+<para>
+This package creates a common registry for all Blends in
+<filename>/etc/blends</filename>. Each Blend should put the files that are used
+into a subdirectory named like the Blend of <filename>/etc/blends</filename>. The
+<package>blends-common</package> package installs a common configuration
+file <filename>/etc/blends/blends.conf</filename>, which can be used to influence the
+behaviour of the tools described below.
+</para>
+
+<sect2>
+ <title><!-- document type does not allow element "MANREF" here--><package>blend-role(8)</package></title>
+<para>
+<variablelist>
+<varlistentry>
+ <term>NAME</term>
+ <listitem><para>
+ <package>blend-role</package> - add/remove roles in registered Debian Pure Blend
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>SYNOPSIS</term>
+ <listitem><para>
+ <package>blend-role</package> <varname>add|del</varname> <varname>Blend</varname>
+ [<varname>Role</varname>]</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>DESCRIPTION</term>
+ <listitem><para>Add/remove (register/unregister) <varname>Role</varname> for the
+ specified <varname>Blend</varname>. If <varname>Role</varname> is not specified, it's
+ assumed to be named like <varname>Blend</varname>.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>OPTIONS</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term><varname>Blend</varname></term>
+ <listitem><para>A registered Blend in /etc/blends, for example
+ one of <package>med</package>, <package>junior</package>,
+ <package>edu</package> or <package>science</package></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>AUTHOR</term>
+ <listitem><para>Andreas Tille <email>tille at debian.org</email>,
+ Cosimo Alfarano <email>kalfa at debian.org</email>.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+</sect2>
+
+<sect2 id="blend-update-menus">
+ <title><!-- document type does not allow element "MANREF"
+ here--><package>blend-update-menus(8)</package></title>
+<para>
+<variablelist>
+
+<varlistentry>
+ <term>NAME</term>
+ <listitem><para>
+ <package>blend-update-menus</package> - add menu of metapackage to all Blend users</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>SYNOPSIS</term>
+ <listitem><para>
+ <package>blend-update-menus</package> [<varname>--blend Blend</varname> | <varname>--user
+ user</varname>]</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>DESCRIPTION</term>
+ <listitem>
+ <para>
+ blend-update-menus behaves differently depending on who run the
+ command:
+ </para>
+
+ <para>
+ If it is called by a user, it adds, and keeps updated, menu
+ entries for the user who runs it.
+ </para>
+
+ <para>
+ If it is called by root, it adds and keeps updated user's menu
+ entries (see menu package for users' menus) for all users who
+ belong to the group of the specified Blend, or only for a specified
+ user, depending on which parameter is passed to the script.
+ </para>
+ </listitem>
+ </varlistentry>
+
+<varlistentry>
+ <term>OPTIONS</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term><varname>Blend</varname></term>
+ <listitem><para>one of the installed Blends, listed in /etc/blends/, for example
+ (if installed: <package>med</package>, <package>junior</package>,
+ <package>edu</package> or <package>science</package>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>user</varname></term>
+ <listitem><para>system user</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>AUTHOR</term>
+ <listitem><para>Andreas Tille <email>tille at debian.org</email>,
+ Cosimo Alfarano <email>kalfa at debian.org</email>.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</para>
+</sect2>
+
+<sect2>
+ <title><!-- document type does not allow element "MANREF" here--><package>blend-user(8)</package></title>
+<para>
+
+<variablelist>
+
+<varlistentry>
+ <term>NAME</term>
+ <listitem><para>
+ <package>blend-user</package> - add/remove user to Role of a registered Blend</para>
+
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>SYNOPSIS</term>
+ <listitem><para>
+ <package>blend-user</package> <varname>add|del</varname> <varname>Blend</varname> <varname>user</varname> [<varname>Role</varname>]
+ </para></listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>DESCRIPTION</term>
+ <listitem><para>Add/remove user to a <varname>Role</varname> of the specified <varname>Blend</varname>.
+
+ If <varname>Role</varname> is not specified, it's assumed to be named like
+ <varname>Blend</varname></para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>OPTIONS</term>
+ <listitem>
+ <variablelist>
+ <varlistentry>
+ <term><varname>Blend</varname></term>
+ <listitem><para>A registered Blend in /etc/blends, for example
+ one of <package>med</package>, <package>junior</package>,
+ <package>edu</package> or <package>science</package>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>user</varname></term>
+ <listitem><para>user to add</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>Role</varname></term>
+ <listitem><para>the role in the <varname>Blend</varname> that <varname>user</varname> will
+ assume</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>AUTHOR</term>
+ <listitem><para>Andreas Tille <email>tille at debian.org</email>,
+ Cosimo Alfarano <email>kalfa at debian.org</email>.</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+</sect2>
+
+<sect2>
+ <title><filename>blends.conf(5)</filename></title>
+<para>
+
+<variablelist>
+
+<varlistentry>
+ <term>NAME</term>
+ <listitem><para>
+ <filename>blends.conf</filename> - configuration for Debian Pure Blends registry
+ </para></listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>DESCRIPTION</term>
+ <listitem><para>This file is sourced from shell scripts inside the Debian
+ Pure Blends package <package>blends-common</package> and thus
+ it has to follow shell syntax. The variables that are set
+ inside this configuration file can be overriden by special
+ Blend configration files
+ <filename>/etc/blends/</filename><varname>Blend></varname>/<varname>Blend></varname><filename>.conf</filename>
+ for each single Blend.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>SYNTAX</term>
+ <listitem><para>The following variables can be set:</para>
+ <variablelist>
+ <varlistentry>
+ <term><package>DBBACKEND</package></term>
+ <listitem><para>Set the backend for the user role management system.
+ Currently the only implemented role management system is
+ <package>unixgroups</package> but others might be implemented
+ later. Unsetting this variable leads to use no roles at all.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><package>UPDATEUSERMENU</package></term>
+ <listitem><para>If this is set to <package>yes</package>, the user menus of meta
+ packages can be created automatically at install time of
+ the package if the postinst script of the package allows
+ this. It is suggested to use this option in the specific
+ configuration files of a special Debian Pure Blend that
+ override the settings of the general configuration file.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><package>SHAREDIR</package></term>
+ <listitem><para>Set the base directory for the user role management
+ system. While this is more or less a feature for
+ debugging this might be also used otherwise. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><package>DRYRUN</package></term>
+ <listitem><para>This variable can be set for debugging. Normally it
+ should be left unset (<emphasis>NOT</emphasis> set to <package>false</package>
+ or anything else!). If set to <package>true</package> a dry run of
+ the tools is performed or <package>echo DRYRUN:</package> would
+ print debugging information. </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><package>DEBUG</package></term>
+ <listitem><para>If set to <package>1</package> debugging mode is switched on.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>SEE ALSO</term>
+ <listitem><para>
+ <filename>blend-role (8)</filename>, <filename>blend-update-menus (8)</filename>,
+ <filename>blend-user (8)</filename></para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>AUTHOR</term>
+ <listitem><para>Andreas Tille <email>tille at debian.org</email>,
+ Cosimo Alfarano <email>kalfa at debian.org</email>.</para></listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+</sect2>
+
+</sect1>
+
+
+<sect1 id="svn">
+ <title>Working with the source repository (<filename>svn</filename> in process of moving to <filename>git</filename>)</title>
+<para>
+ Sometimes it might be interesting for developers to check out the
+ latest code of the Blend tools or a special Blend code for the meta
+ packages. In <xref linkend="communication"/> the directory layout of the
+ <filename>svn</filename>-directory was described. How to derive the
+ Debian packages from this layout?
+<variablelist>
+
+<varlistentry>
+ <term>Checkout</term>
+ <listitem><para>
+ For the Blend tools and this documentation
+<informalexample>
+<programlisting>
+ git clone git+ssh://<varname>username</varname>@git.debian.org/git/blends/blends.git
+</programlisting>
+</informalexample>
+
+ or for the Debian Pure Blend <varname>BLEND-name</varname>
+
+<informalexample>
+ <programlisting>
+ svn checkout svn+ssh://<varname>username</varname>@svn.debian.org/svn/blends/projects/<varname>BLEND-name</varname>/trunk
+</programlisting>
+</informalexample>
+
+ Note: This will be moved to Git (at least) soon after Wheezy release.</para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>Build source package</term>
+ <listitem><para>
+ Change into the created directory and type
+<informalexample>
+ <programlisting>
+ make -f debian/rules get-orig-source
+</programlisting>
+</informalexample>
+
+ This creates a <filename>tar.gz</filename> source archive of the packages
+ you want to build. For your personal comfort you can create a
+ file <filename>Makefile</filename> in your package source directory containing
+
+<informalexample>
+ <programlisting>
+ #!/usr/bin/make -f
+ include /usr/share/blends-dev/Makefile
+</programlisting>
+</informalexample>
+<programlisting>
+ Which enables you to simply say
+ </programlisting>
+<informalexample>
+ <programlisting>
+ make dist
+ </programlisting>
+</informalexample>
+
+ to create the source tarball.
+ </para>
+ </listitem>
+</varlistentry>
+
+<varlistentry>
+ <term>Build Debian packages</term>
+ <listitem><para>
+ Unpack the created source tarball and proceed like you build
+ Debian packages normally.</para>
+ </listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+<para>
+The current Debian Med packages provide a working example how to use
+the tools described below.
+</para>
+</sect1>
+
+ <sect1 id="webpagecreation">
+ <title>How to create tasks and bugs pages of web sentinel</title>
+
+<para>
+In <xref linkend="sentinel"/> the creation of so called tasks
+pages <xref linkend="packageslist"/> and bugs pages <xref linkend="bugs"/> was
+described. These pages are automatically build by a cron job on Alioth
+from the current state of the tasks files in the SVN repository.
+If you have commited changes to the tasks pages and want to see the
+effect immediately the steps to do are as follows:
+</para>
+<para>
+<orderedlist>
+ <listitem><para>Login to <package>alioth.debian.org</package></para></listitem>
+ <listitem><para><filename>cd /var/lib/gforge/chroot/home/groups/blends/webtools/</filename></para></listitem>
+ <listitem><para><filename>./tasks.py <blend-name></filename></para></listitem>
+</orderedlist>
+</para>
+<para>
+To know what a valid <package><blend-name></package> might be have a look
+into
+<filename>/var/lib/gforge/chroot/home/groups/blends/webtools/webconf</filename>.
+Each Blend has an according config file there. Leave out
+the <filename>.conf</filename> extension and you have a
+valid <package><blend-name></package>.
+</para>
+<para>
+In case you are planing some more experimental changes there is
+another host which was kindly sponsored by Frédéric Hébert for Debian
+Med called <package>blends.debian.net</package> which is running a copy of
+UDD and also hosts the latest development snapshot of the Blends web
+tools. Just ask Andreas Tille <email>tille at debian.org</email> in case
+you like a login on this host.
+</para>
+<para>
+The code which builds web and tasks pages is available in Git at
+<filename>git://git.debian.org/git/blends/website.git</filename>. It is
+using the <ulink url="http://genshi.edgewall.org/">Genshi
+templating system</ulink> which enables influencing the layout of the pages
+by editing the templates in the
+<filename>templates</filename> directory.
+You can also influence some parameters of the web pages in the
+configuration files in the <filename>webconf</filename> directory.
+Last but not least you can provide translations for the web pages in
+the <filename>po</filename> directory.
+</para>
+<para>
+Once something on the web pages was changed you can activate the
+changes as follows:
+</para>
+<para>
+<orderedlist>
+ <listitem><para>Login to <package>alioth.debian.org</package> or <package>blends.debian.net</package></para></listitem>
+ <listitem><para><filename>cd /var/lib/gforge/chroot/home/groups/blends/webtools/</filename></para></listitem>
+ <listitem><para><filename>git pull</filename></para></listitem>
+</orderedlist>
+</para>
+<para>
+Please note that the <filename>css</filename> and <filename>js</filename> files which are
+influencing the layout of the automatically created pages are in
+the same area as the static web pages (see below <xref linkend="staticwebpages"/>).
+</para>
+</sect1>
+
+ <sect1 id="staticwebpages">
+ <title>Editing static web pages of Blends on Alioth</title>
+<para>
+A very simple entry page is created for each Blend which is linked
+from the
+<ulink url="http://blends.alioth.debian.org/">list of all Blends</ulink>.
+Most probably the maintainers of a Blend want to enhance this page a
+bit. It is actually intended that this simple template will be
+enhanced as it is done for instance for the
+<ulink url="http://debian-med.alioth.debian.org">Debian Med
+project</ulink> which has a quite complex PHP driven web with a lot of other
+features than just linking to the tasks and bugs pages. Maintainers
+of a Blend should care for this index page which currently is just
+featuring links to the automatically updated pages as well as an image
+which shows the activity of the
+<ulink url="http://people.debian.org/~tille/talks/200808_lightning/liststats.pdf">
+ relevant mailing list</ulink>. Maintaining these static pages is
+not a "service" which is done for you. The maintainers of a Blend
+should care for this!
+</para>
+<para>
+The static pages are maintained in Git at
+<filename>git://git.debian.org/git/blends/website.git</filename> in the
+<filename>websites</filename> directory.
+Once you have changed the content of the pages you can activate
+the changes by doing:
+</para>
+<para>
+<orderedlist>
+ <listitem><para>Login to <package>alioth.debian.org</package> or <package>blends.debian.net</package></para></listitem>
+ <listitem><para><filename>cd /var/lib/gforge/chroot/home/groups/blends/webtools/</filename></para></listitem>
+ <listitem><para><filename>git pull</filename></para></listitem>
+</orderedlist>
+</para>
+</sect1>
+ </appendix>
+
+<!--
+TODOs
+uncomment and fix the manref elements
+ -->
\ No newline at end of file
--
Git repository for blends-gsoc code
More information about the Blends-commit
mailing list