yoswink 07/08/24 19:47:03 Added: projectxml.xml Log: Initial draft import. See bug #184875 for details.
Revision Changes Path 1.1 xml/htdocs/doc/en/draft/projectxml.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/draft/projectxml.xml?rev=1.1&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/draft/projectxml.xml?rev=1.1&content-type=text/plain Index: projectxml.xml =================================================================== <?xml version="1.0" encoding="UTF-8"?> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/projectxml.xml,v 1.1 2007/08/24 19:47:03 yoswink Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/draft/projectxml.xml"> <title>Gentoo ProjectXML Guide</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">José Luis Rivero</mail> </author> <abstract> This guide shows you how to create an official GuideXML page for a Gentoo Linux Project. The guide assumes a basic knowledge of the GuideXML format. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1.0</version> <date>2007-07-09</date> <chapter> <title>Introduction</title> <section> <title>What is ProjectXML?</title> <body> <p> ProjectXML is designed to be an easy way to create project pages which follow the Gentoo web style. It uses the same XML style that <uri link="/doc/en/xml-guide.xml">GuideXML doc</uri>. </p> </body> </section> <section> <title>Recommended knowledge</title> <body> <p> 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 <uri link="/doc/en/xml-guide.xml">GuideXML doc</uri>. </p> </body> </section> </chapter> <chapter> <title>Creating a project page</title> <section> <title>General Data</title> <body> <p> To start writing our project page, first of all, we should define the proper doc headers. Just copy and paste the following lines: </p> <pre caption="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"> </pre> <p> 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: <c><name></c>, <c><longname></c>, <c><description></c> and <c><longdescription></c>, although we recommend to use all them to give a complete view of the project. </p> <pre caption="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> </guide> </pre> </body> </section> <section> <title>Defining project goals</title> <body> <p> 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. </p> <note> Like the <c><longdescription></c>, the <c><goals></c> tag <e>must</e> contain one or more paragraphs (<c><p></c>), tables, lists, code samples, admonitions (<c><note></c> /<c><warn></c>/<c><impo></c>). The simplest case is to use a single <c><p></c> element. </note> <pre caption="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> </pre> </body> </section> <section> <title>List of project developers</title> <body> <p> 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. </p> <pre caption="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> </pre> <p> As you can see in the example, the <c>dev</c> tag supports two optional attributes: <c>role</c> is used to name the position of the developer inside the team and <c>description</c>, which allow to set some details about the member. </p> </body> </section> <section> <title>Existing herds</title> <body> <p> Another interesting section to include in the project page is the list of Gentoo herds which belongs to the project. The only data which should be filled is the <c>name</c> attribute. </p> <pre caption="Herd section"> <herd name="herd1" /> <herd name="herd2" /> </pre> <p> ProjectXML will parse the <uri link="/en/metastructure/herds/herds.xml">herds</uri> file and in the final rendered you will see all the nicknames of the devs who belongs to the herd. </p> </body> </section> <section> <title>Project resources</title> <body> <p> 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. </p> <pre caption="Resource links"> <resource link="/gentoo/link.xml"> (omitting http://www.gentoo.org) <resource link="http://www.useful.internet.site/"> </pre> </body> </section> </chapter> <chapter> <title>Tweaking the project page</title> <section> <title>Completing the general information</title> <body> <p> 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. </p> <p> 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. </p> </body> </section> <section> <title>Adding extra content</title> <body> <p> 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. </p> <p> The following sections can be target of adding extra content: <c>goals</c> , <c>devs</c>, <c>resources</c>, <c>subprojects</c> and <c>tasks</c>. All you need is to set the attribute <c>position</c> to the <c>extrachapter</c> tag. The next example show how to add info to developers section: </p> <note> The <c><extrachapter></c> uses a GuideXML chapter structure which may have one <c><title></c> and must have one or more <c><section></c>. Each section may have a <c><title></c> and must have one or more <c><body></c>. Each <c><body></c> must have one ore more paragraphs, code samples, tables, lists, admonitions. </note> <pre caption="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> </pre> <p> Also, you can add one or more extrachapters to the top or the bottom of the whole page. The <c>top</c> extrachapter will be rendered just under the project description and the <c>bottom</c> at the end of the page. </p> <pre caption="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: [EMAIL PROTECTED] </p> </body> </section> </extrachapter> </pre> </body> </section> <section id="subprojects"> <title>Defining Subprojects</title> <body> <p> 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. </p> <p> To determine what kind of subproject tag you need, you should follow the next instructions: </p> <ol> <li> 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 <c>subproject</c> xml tag. </li> <li> 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 <c>extraproject</c> xml tag. </li> <li> If the subproject is planned but it hasn't started yet, the you can use the <c>plannedproject</c> xml tag. </li> </ol> <p> <b>Subprojects</b>: 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: <c>inheritmembers</c> which will add the devs inside dev subproject section to the main page dev section. The second is <c>inheritresources</c> which will make the same with the resource section. </p> <pre caption="Setting a subproject"> <subproject ref="/path/to/subproject.xml" inheritresources="yes" inheritmembers="yes"/> </pre> <p> <b>Extraprojects</b>: extraprojects need a mandatory <c>name</c> of the project and give you the possibility to define the <c>lead</c> and a possible project <c>link</c>. Remember to include a description of the project. </p> <pre caption="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> </pre> <p> <b>Plannedprojects</b>: for future projects the only thing needed is the <c>name</c> of the project and a text description. </p> <pre caption="Setting a planned project"> <plannedproject name="Future ProjectXML"> Description of the future project goes here </plannedproject> </pre> </body> </section> <section> <title>Managing tasks</title> <body> <p> 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. </p> <p> The basic information we need to fill in for a task is: the attributes <c>id</c>,<c>lead</c> and <c>finished</c>. Inside the task element we have to specify more information:the task <c><name></c>, the <c><description></c> and the <c><startdate></c>. </p> <pre caption="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> </pre> <p> There are more elements which can be used to extending the information about tasks: </p> <ul> <li> The <c>longdescription</c> tag, to give a complete overview of the project activity. </li> <li> The <c>enddate</c> tag, if the task is finished to show the period of time it took. </li> <li> One or more <c>dev</c> tags, to show the people involved in the tasks. The tag allow the attributes <c>role</c> and <c>description</c>. </li> <li> One or more <c>reference</c> tags, to include the relevant information links. It can use the classic <c><uri></c>; GuideXML element or contain a one or more <c>bug</c> tags to link to Gentoo Bugzilla. </li> <li> One or more <c>milestone</c> tags, to reflect important development points inside the task. The milestones tags use the attribute <c>finished</c> and need the tags <c>enddate</c> and <c>description</c>. </li> <li> One or more <c>depends</c> tags, to show the dependency between tasks. You need to fill the attribute <c>ref</c> which refers to an other task id. </li> </ul> <pre caption="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> </pre> </body> </section> </chapter> <chapter> <title>Adding your project to the Gentoo full project list</title> <section> <body> <p> Gentoo provides a page with the <uri link="/proj/en/index.xml">full list of projects</uri> 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: </p> <p> If you are writting a subproject page, it will be enough to have it listed as it in the main project page (as described in the <uri link="#subprojects">subprojects section</uri>). </p> <p> If the project is a top level one, then you should add the project to: <path>/gentoo/xml/htdocs/proj/en/metastructure/gentoo.xml</path>: </p> <pre caption="Adding your top level project to gentoo database"> <subproject ref="/proj/en/myproject/index.xml" inheritmembers="no"/> </pre> </body> </section> </chapter> </guide> -- [EMAIL PROTECTED] mailing list
