Gentoo ProjectXML Guide

José Luis Rivero Author

Updated March 27, 2008

1. Introduction

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 GuideXML doc.

Recommended knowledge

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.

2. Creating a project page

General Data

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

<project>
<name>ProjectXML</name>
<longname>A ProjectXML example page</longname>
<date>2007-04-15</date>

<description>
A short project sentence describing the project.
</description>

<longdescription>
<p>
A more elaborated description about the project (edited as GuideXML block).
</p>
</longdescription>
</project>

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.

Note: 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

<goals>
<p>
The intention of the project is to show you how can you build a basic
project page easily using ProjectXML.
</p>
</goals>

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 rendered.

Code Listing 2.4: Developers section

<dev role="Strategic Manager" description="Policy and releng">Dev1</dev>
<dev role="Operational Manager" description="Security">Dev2</dev>
<dev role="member">Dev3</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 the member.

Existing herds

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.

Project resources

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)
<resource link="http://www.useful.internet.site/">

3. 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 some cases.

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

<recruitment>
  <job>
    <summary>First Open Position</summary>
    <details>
      Just an <e>example</e>> of how to write details about this
      first open position
    </details>
    <requirements>
      Needed <b>skills</b> to work in the open position
    </requirements>
    <contact>nick1</contact>
    <contact>nick2</contact>
  </job>
</recruitment>

All posted jobs from projects listed on our project page will appear on our Gentoo Linux Staffing Needs page.

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 section:

Note: 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

<extrachapter position="devs">
<title>Note about developers</title>
<section>
<body>

<p>
The list of devs only include the official gentoo devs but the project
works thanks to many other contributors who are not gentoo devs.
</p>

</body>
</section>
</extrachapter>

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

<extrachapter position="bottom">
<title>How to find us</title>
<section>
<title>Via mail</title>
<body>

<p>
To contact with the Gentoo doc team you just need to subscribe to
our mailing list: gentoo-doc@gentoo.org.
</p>

</body>
</section>
</extrachapter>

Defining Subprojects

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 project page.

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.
</extraproject>

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
</plannedproject>

Managing tasks

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 description.

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>
<startdate>01/01/2007</startdate>
</task>

There are more elements which can be used to extending the information about tasks:

The longdescription tag, to give a complete overview of the project activity.
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 task id.

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>
<longdescription>
A longer description about how to create a complete task.
</longdescription>
<startdate>01/01/2007</startdate>
<enddate>06/04/2007</enddate>
<dev role="designer" description="The only designer">dev1</dev>
<reference><uri link="/path/to/doc.xml">Main guide</uri></reference>
<reference><bug no="145234"/></reference>
<milestone finished="yes">
  <enddate>04/03/2007</enddate>
  <description>Thinking about write the guide</description>
</milestone>
<depends ref="task1"/>
</task>

4. 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: /gentoo/xml/htdocs/proj/en/metastructure/gentoo.xml:

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 are licensed under the Creative Commons - Attribution / Share Alike license.