Gentoo ProjectXML Guide
What is ProjectXML?
ProjectXML is designed to be an easy way to create project pages which
follow the Gentoo web style. It uses the same XML style as
ProjectXML is designed to be very easy to use so you don't need a special
knowledge. The only recommended read before touching a project page is the
official GuideXML doc.
Creating a project page
To start writing our project page, first of all, we should define the proper
doc headers. Just copy and paste the following lines:
Code Listing 2.1: ProjectXML doc headers
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/project.xsl" type="text/xsl"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
<!DOCTYPE project SYSTEM "/dtd/project.dtd">
First part in our doc is the general data section which cover the basic
information of the project. Also, in this section we'll find the only
mandatory tags we need to set in order to create a valid page:
<name>, <longname>, <description> and
<longdescription>, although we recommend to use all them to give
a complete view of the project.
Code Listing 2.2: Basic doc information example
<longname>A ProjectXML example page</longname>
A short project sentence describing the project.
A more elaborated description about the project (edited as GuideXML block).
Defining project goals
In order to reflect the final objective of the project, ProjectXML use
the tag goals to include a description about what's the purpose of
your work. Just a single sentence could be enough.
Like the <longdescription>, the <goals> tag
must contain one or more paragraphs (<p>), tables, lists,
code samples, admonitions (<note>
/<warn>/<impo>). The simplest case is to use a
single <p> element.
Code Listing 2.3: Goals section
The intention of the project is to show you how can you build a basic
project page easily using ProjectXML.
List of project developers
ProjectXML allow you to include a list of Gentoo developers who are involved
in the project. You only need to write the developer nickname inside the tag
and it will automatically be completed with the full real name when the page is
Code Listing 2.4: Developers section
<dev role="Strategic Manager" description="Policy and releng">Dev1</dev>
<dev role="Operational Manager" description="Security">Dev2</dev>
As you can see in the example, the dev tag supports two optional
attributes: role is used to name the position of the developer inside
the team and description, which allow to set some details about
Another interesting section to include in the project page is the list of
Gentoo herds which belong to the project. The only data which should be filled
is the name attribute.
Code Listing 2.5: Herd section
<herd name="herd1" />
<herd name="herd2" />
ProjectXML will parse the herds file and in the final
rendered you will see all the nicknames of the devs who belongs to the herd.
It's also possible to include some resources links inside the project doc
page. This links usually point to Gentoo documentation, external docs or
useful Internet sites.
Code Listing 2.6: Resource links
<resource link="/gentoo/link.xml"> (omitting http://www.gentoo.org)
Tweaking the project page
Completing the general information
Although the previous sections cover the basic information to create a
project, there are other chapters which could be quite useful to use in
The information below, will show you how you can add extra information
to the chapters saw in the previous section, how to create subprojects
inside your project page or how to reflect tasks and its status.
Including a recruitment section
ProjectXML allows to include a section which shows the open project jobs or
opportunities to collaborate. All you have to do is to include the
<recruitment> tag just after the </goals>. For
every position you should include a <job> tag. Inside, we find
<summary>, <details>, <requirements> and
one or more <contact> tags. Let's see an example of using this:
Code Listing 3.1: Including a recruitment section
<summary>First Open Position</summary>
Just an <e>example</e>> of how to write details about this
first open position
Needed <b>skills</b> to work in the open position
All posted jobs from projects listed on our project page will appear on our
Gentoo Linux Staffing Needs
Adding extra content
If you think that the previous basic sections are a little empty or want
to clarify some of them with a sentence or a paragraph, you can add some
extra chapters which will be render just below the section you want.
The following sections can be target of adding extra content: goals
,devs, resources, subprojects, tasks and
recruitment. All you need is to set the attribute position to the
extrachapter tag. The next example show how to add info to developers
The <extrachapter> uses a GuideXML chapter structure which may
have one <title> and must have one or more
<section>. Each section may have a <title> and must
have one or more <body>. Each <body> must have one
ore more paragraphs, code samples, tables, lists, admonitions.
Code Listing 3.2: Adding content to devs section
<title>Note about developers</title>
The list of devs only include the official gentoo devs but the project
works thanks to many other contributors who are not gentoo devs.
Also, you can add one or more extrachapters to the top or the bottom of
the whole page. The top extrachapter will be rendered just under
the project description and the bottom at the end of the page.
Code Listing 3.3: Adding a contact section to the bottom of the page
<title>How to find us</title>
To contact with the Gentoo doc team you just need to subscribe to
our mailing list: firstname.lastname@example.org.
If the projects is composed from one or more subprojects, ProjectXML
allow you to specify them in order to be show or linked from the main
To determine what kind of subproject tag you need, you should follow
the next instructions:
If the subproject has its own ProjectXML page, the basic data can
be extracted from there and a link to the subproject added to the page.
You should use the subproject xml tag.
If the subproject don't have its own page and you want to keep the
information in the main projects page, then you should use
the extraproject xml tag.
If the subproject is planned but it hasn't started yet, the you can
use the plannedproject xml tag.
Subprojects: it's quite easy to set a subproject, just need to provide
the path where the subproject page is allocated. It also admit a couple of
possible attributes: inheritmembers which will add the devs inside dev
subproject section to the main page dev section. The second is
inheritresources which will make the same with the resource section.
Code Listing 3.4: Setting a subproject
<subproject ref="/path/to/subproject.xml" inheritresources="yes" inheritmembers="yes"/>
Extraprojects: extraprojects need a mandatory name of the project
and give you the possibility to define the lead and a possible project
link. Remember to include a description of the project.
Code Listing 3.5: Setting an extraprojects
<extraproject name="First extraproject" lead="myself">
Here goes the description of the extraproject. GuideXML tags are
allowed if you need to use them.
Plannedprojects: for future projects the only thing needed is the
name of the project and a text description.
Code Listing 3.6: Setting a planned project
<plannedproject name="Future ProjectXML">
Description of the future project goes here
If the project has planned some tasks to accomplish the work, they can be
reflected in the page. The tasks can be quite simple or can give a lot
of details of what people is working on give info about the status and
The basic information we need to fill in for a task is: the attributes
id,lead and finished. Inside the task element we have to
specify more information:the task <name>, the
<description> and the <startdate>.
Code Listing 3.7: Defining a basic task
<task id="basictask" lead="devnick" finished="no">
<name>Defining a basic task</name>
<description>How to create a basic task</description>
There are more elements which can be used to extending the information
The longdescription tag, to give a complete overview of the
The enddate tag, if the task is finished to show the period of
time it took.
One or more dev tags, to show the people involved in the tasks. The
tag allow the attributes role and description.
One or more reference tags, to include the relevant information
links. It can use the classic <uri>; GuideXML element or
contain a one or more bug tags to link to Gentoo Bugzilla.
One or more milestone tags, to reflect important development
points inside the task. The milestones tags use the attribute
finished and need the tags enddate and description.
One or more depends tags, to show the dependency between tasks.
You need to fill the attribute ref which refers to an other
Code Listing 3.8: Defining a complete task
<task id="basictask" lead="devnick" finished="no">
<name>Defining a complete task</name>
<description>How to create a complete task</description>
A longer description about how to create a complete task.
<dev role="designer" description="The only designer">dev1</dev>
<reference><uri link="/path/to/doc.xml">Main guide</uri></reference>
<description>Thinking about write the guide</description>
Adding your project to the Gentoo full project list
Gentoo provides a page with the full list of
projects belongs to the distribution. It shows all the top level projects
and its own subprojects. All the current projects should be listed there, so
here is what you have to do to add your project there:
If you are writing a subproject page, it will be enough to have it listed as
it in the main project page (as described in the subprojects section).
If the project is a top level one, then you should add the project to:
Code Listing 4.1: Adding your top level project to gentoo database
<subproject ref="/proj/en/myproject/index.xml" inheritmembers="no"/>
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.