You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by rg...@apache.org on 2006/05/10 09:48:48 UTC
svn commit: r405667 - in
/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo: ./
resources/stylesheets/ src/documentation/content/xdocs/
Author: rgardler
Date: Wed May 10 00:48:45 2006
New Revision: 405667
URL: http://svn.apache.org/viewcvs?rev=405667&view=rev
Log:
Use Case support, see http://localhost:8888/docs/developer/useCases.xml
Added:
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl (with props)
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml (with props)
Modified:
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml
forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml
Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/input.xmap Wed May 10 00:48:45 2006
@@ -41,7 +41,6 @@
<map:generate type="file" src="{lm:project.descriptor.{1}}" />
<map:serialize type="xml-document"/>
</map:match>
-
<map:match type="regexp" pattern="^(.*?)([^/]*)changes.xml$">
<map:generate type="file" src="{lm:project.status}" />
@@ -107,6 +106,29 @@
<map:serialize type="xml-document"/>
</map:match>
+ <!-- =============================================================== -->
+ <!-- Use Case Pipelines -->
+ <!-- =============================================================== -->
+
+ <map:match pattern="docs/**/useCases.source.xml">
+ <map:generate type="file" src="{lm:project.useCases}" />
+ <map:serialize type="xml"/>
+ </map:match>
+
+ <map:match pattern="docs/user/useCases.xml">
+ <map:generate type="file" src="{lm:project.useCases}" />
+ <map:transform src="{lm:projectInfo.transform.useCase.document}">
+ <map:parameter name="includeImplementationNotes" value="false"/>
+ </map:transform>
+ <map:serialize type="xml-document"/>
+ </map:match>
+
+ <map:match pattern="docs/developer/useCases.xml">
+ <map:generate type="file" src="{lm:project.useCases}" />
+ <map:transform src="{lm:projectInfo.transform.useCase.document}"/>
+ <map:serialize type="xml-document"/>
+ </map:match>
+
<!-- ================================================================ -->
<!-- HTML indexes -->
<!-- ================================================================ -->
@@ -163,8 +185,8 @@
<!--
Create a snippet for inclusion in site.xml that provides a link to
- all known programming languages for projects specified in
- locationmap-projects.xml file.
+ all known projects specified in
+ locationmap.xml file.
-->
<map:match pattern="projectDetails/descriptorIndex.xml">
<map:generate type="file" src="{project:content}/locationmap.xml" />
Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/locationmap.xml Wed May 10 00:48:45 2006
@@ -35,7 +35,11 @@
<locator>
<match pattern="project.status">
<location src="{project:status}" />
- </match>
+ </match>
+
+ <match pattern="project.useCases">
+ <location src="{project:content.xdocs}/useCases.xml" />
+ </match>
<match pattern="projectInfo.transform.*.*">
<location src="resources/stylesheets/{1}-to-{2}.xsl"/>
Added: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl?rev=405667&view=auto
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl (added)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl Wed May 10 00:48:45 2006
@@ -0,0 +1,174 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2002-2005 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+ <xsl:param name="includeImplementationNotes">true</xsl:param>
+ <xsl:param name="includeStepsSummary">true</xsl:param>
+
+ <xsl:template match="/">
+ <xsl:apply-templates select="//useCases"/>
+ </xsl:template>
+
+ <xsl:template match="useCases">
+ <document>
+ <header>
+ <title>
+ <xsl:choose>
+ <xsl:when test="title">
+ <xsl:value-of select="title"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:text>Use Cases</xsl:text>
+ </xsl:otherwise>
+ </xsl:choose>
+ </title>
+ </header>
+ <body>
+ <xsl:apply-templates select="useCase"/>
+ </body>
+ </document>
+ </xsl:template>
+
+ <xsl:template match="useCase">
+ <section>
+ <xsl:apply-templates/>
+ </section>
+ </xsl:template>
+
+ <xsl:template match="steps">
+
+ <xsl:if test="$includeStepsSummary='true'">
+ <section>
+ <title>Summary</title>
+ <ol class="steps">
+ <xsl:apply-templates mode="stepIndex"/>
+ </ol>
+ </section>
+ </xsl:if>
+ <section>
+ <title>Details</title>
+ <table>
+ <tr>
+ <th>Step</th>
+ <th>Description</th>
+ <th>Result</th>
+ <th>Status</th>
+ </tr>
+ <xsl:apply-templates mode="userDocs"/>
+ </table>
+ </section>
+
+ <xsl:if test="$includeImplementationNotes='true'">
+ <section>
+ <title>Implementation Notes</title>
+ <table>
+ <tr>
+ <th>Step</th>
+ <th>Notes</th>
+ </tr>
+ <xsl:apply-templates mode="devDocs"/>
+ </table>
+ </section>
+ </xsl:if>
+ </xsl:template>
+
+ <xsl:template match="step" mode="stepIndex">
+ <li>
+ <strong><xsl:value-of select="title"/></strong>
+ <xsl:if test="@required='false'">
+ <xsl:text> (Optional)</xsl:text>
+ </xsl:if>
+ </li>
+ </xsl:template>
+
+ <xsl:template match="step" mode="userDocs">
+ <tr>
+ <td>
+ <xsl:number format="1.1.1.1.1.1.1" count="step" level="single"/><xsl:text>. </xsl:text><xsl:value-of select="title"/>
+ <xsl:if test="@required='false'">
+ <br/><xsl:text>(Optional)</xsl:text>
+ </xsl:if>
+ </td>
+ <td><xsl:apply-templates select="description"/></td>
+ <td><xsl:apply-templates select="result"/></td>
+ <td>
+ <xsl:choose>
+ <xsl:when test="not(fixme)">Implemented</xsl:when>
+ <xsl:when test="fixme[@priority='Blocker']"><warning>Not Implemented</warning></xsl:when>
+ <xsl:otherwise>
+ Implemented with fixmes:-<br/>
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:if test="fixme[@priority='Blocker']">
+ Blockers: <xsl:value-of select="count(fixme[@priority='Blocker'])"/> <br/>
+ </xsl:if>
+ <xsl:if test="fixme[@priority='High']">
+ High: <xsl:value-of select="count(fixme[@priority='High'])"/> <br/>
+ </xsl:if>
+ <xsl:if test="fixme[@priority='Low']">
+ Low: <xsl:value-of select="count(fixme[@priority='Low'])"/> <br/>
+ </xsl:if>
+ <xsl:if test="fixme[@priority='Enhancements']">
+ Enhancements: <xsl:value-of select="count(fixme[@priority='Enhancement'])"/> <br/>
+ </xsl:if>
+ </td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="step" mode="devDocs">
+ <tr>
+ <td><xsl:number format="1.1.1.1.1.1.1" count="step" level="single"/><xsl:text>. </xsl:text><xsl:value-of select="title"/></td>
+ <td>
+ <xsl:apply-templates select="implementation/description"/><br/>
+ <xsl:apply-templates select="fixme[@priority='Blocker']"/>
+ <xsl:apply-templates select="fixme[@priority='High']"/>
+ <xsl:apply-templates select="fixme[@priority='Low']"/>
+ <xsl:apply-templates select="fixme[@priority='Enhancement']"/>
+ </td>
+ </tr>
+ </xsl:template>
+
+ <xsl:template match="description">
+ <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="result">
+ <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="implementation">
+ <xsl:apply-templates select="description"/>
+ </xsl:template>
+
+ <xsl:template match="fixme">
+ <fixme>
+ <xsl:attribute name="author"><xsl:value-of select="@priority"/></xsl:attribute>
+ <xsl:value-of select="."/>
+ </fixme>
+ </xsl:template>
+
+ <xsl:template match="@*|*|text()|processing-instruction()|comment()">
+ <xsl:copy>
+ <xsl:apply-templates select="@*|*|text()|processing-instruction()|comment()"/>
+ </xsl:copy>
+ </xsl:template>
+
+</xsl:stylesheet>
Propchange: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/resources/stylesheets/useCase-to-document.xsl
------------------------------------------------------------------------------
svn:eol-style = native
Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/index.xml Wed May 10 00:48:45 2006
@@ -103,6 +103,31 @@
</section>
</section>
+
+ <section>
+ <title>Use Cases</title>
+ <p>Projects can manage a document describing various use cases for the
+ application. These use cases can then be used to generate useful developer
+ and user documentation, as well as helping to track the implementation
+ status of features.</p>
+
+ <p>Some of the uses of this feature are:</p>
+
+ <ul>
+ <li>during design - what needs to be done</li>
+ <li>during development - what needs to be done/has been done</li>
+ <li>during use - user documentation of common activities</li>
+ <li>during maintenance - how something was implemented</li>
+ </ul>
+
+ <p>To see some examples take a look at:</p>
+
+ <ul>
+ <li><a href="docs/user/useCases.xml">User Docs</a> for the Use Case features of this plugin</li>
+ <li><a href="docs/developer/useCases.xml">Developer Docs</a> for the Use Case features of this plugin</li>
+ </ul>
+ </section>
+
<section>
<title>Project Details</title>
<p>Project details are generated from a project descriptor file.
Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/site.xml Wed May 10 00:48:45 2006
@@ -47,6 +47,16 @@
<forrestPlugins label="Plugins Index" href="site:forrest/plugins" description="Index of Forrest Plugins"/>
</about>
+ <docs label="Documentation" href="docs/">
+ <user label="User" href="user/">
+ <useCases label="Use Cases" href="useCases.html"/>
+ </user>
+ <developer label="Developer" href="developer/">
+ <useCases label="Use Cases" href="useCases.html"/>
+ <!-- In development: <featureMatrix label="Feature Matrix" href="featureMatrix/useCases.html"/> -->
+ </developer>
+ </docs>
+
<projects label="Projects" href="projectDetails/">
<navIndexes label="Navigation Indexes">
<xi:include href="cocoon://projectDetails/index.siteSnippet.xml"/>
Added: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml?rev=405667&view=auto
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml (added)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml Wed May 10 00:48:45 2006
@@ -0,0 +1,376 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2006 The Apache Software Foundation or its licensors,
+ as applicable.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<useCases>
+ <title>Uses Cases for org.apache.forrest.plugin.input.projectInfo</title>
+
+ <useCase>
+ <title>Write Use Case Documentation</title>
+ <description>
+ <p>Write semi-structured use case documents so that they can be reused in a variety of ways.
+ This use case describews a process for writing such documents. This document is derived from
+ such a <a href="useCases.source.xml">source document</a>.</p>
+
+ <section>
+ <title>Justification</title>
+
+ <p>A use case describes a unit of work. It is typically used in the design
+ stages of a software project. It is very useful for describing what an applicaiton must
+ do and what patchs through the system can be taken.</p>
+
+ <p>By bringing this information together in a semi-structured document we can use it in many
+ different ways. For example:</p>
+
+ <ul>
+ <li>Requirements Documentation</li>
+ <li>Developer Documentation</li>
+ <li>User Documentaiton</li>
+ <li>Functionality Matrices</li>
+ <li>Task Lists</li>
+ </ul>
+ </section>
+
+ </description>
+
+ <steps>
+ <step>
+ <title>Create/open a Use Case file</title>
+ <description>In your favourite XML editor either create a new file
+ or open an existing use case file. The default location of these files
+ within a Forrest content object is <code>/content/documentation/xdocs/useCases.xml</code>
+ </description>
+ <result>You have either a blank use case document or an existing one ready for editing.</result>
+
+ <fixme priority="High">Create a DTD for use case descriptions.</fixme>
+ </step>
+
+ <step>
+ <title>Create a new use case</title>
+ <description>
+ <p>A use case is enclosed within a <code>useCase</code> element.
+ Each use case should be given a brief <code>title</code> to describe it.</p>
+
+ </description>
+
+ <result>You have the container for your new use case.</result>
+
+ <fixme priority="High">Allow use cases to be split over several files.</fixme>
+ </step>
+
+ <step>
+ <title>Describe the overall objective of the use case</title>
+ <description>
+ <p>Each use case should be described in terms of:</p>
+ <ul>
+ <li>The objective</li>
+ <li>The expected results</li>
+ <li>The justification</li>
+ </ul>
+ <p>This information should be placed in the <code>description</code> element
+ of your use case. This node allows any XDoc markup and therefore you are
+ reasonably free to use whatever formatting or images are needed to convey the
+ important details most efficiently.</p>
+ </description>
+
+ <result>You have a use case that is described sufficiently well for an average user of the end system
+ to understand its purpose.</result>
+ </step>
+
+ <step>
+ <title>Define each step in the Use Case</title>
+ <description>
+ <p>Each use case will be subdivided into one or more steps that must be carried out
+ in order to complete the task. Each of these steps is defined within a <code>step</code>
+ element which are chilren of a <code>steps</code> element.</p>
+ </description>
+ </step>
+
+ <step>
+ <title>Descripbe the step</title>
+ <description>
+ <p>Each step has a title and a description. The description should provide enough information
+ for a user to complete the task and for a developer to implement support for the user in that
+ task.</p>
+
+ <p>In addition each step can be described as required or optional. By default a step is assumed
+ be required. To set it to optional add a <code>required="false"</code> attribute to the
+ <code>step</code> element.</p>
+ </description>
+
+ <result>A user will be able to follow instructions on how to carry out the step.</result>
+ </step>
+
+ <step>
+ <title>Describe the expected results</title>
+ <description>
+ <p>Provide, within a <code>result</code> a brief description of the expected results from
+ this step. This should summarise what state the application will be in once this use case
+ has been performed.</p>
+ </description>
+ <result>You will have provided enough information to allow developers to test the functionality and
+ users to identify when a step has been succesfully completed.</result>
+ </step>
+
+ <step required="false">
+ <title>Add "fixme" notes</title>
+ <description>
+ <p>A fixme note is enclosed within a <code>fixme</code> element. It describes something that
+ remains to be done within this step. Each fixme has a priority attribute which can take one of
+ of the followin values:</p>
+
+ <ul>
+ <li>Enhancement - a nice to have ehancment that may or may not be implemented.</li>
+ <li>Low - this is considered an important addition to the use case, but everything works without it.</li>
+ <li>High - this is an important addition. Everything works without it, but having this implmeneted would
+ improve the application considerably.</li>
+ <li>Major - this is nor preventing work that utilises the use case, but it is considered a requirement
+ for the next release since it adds key functionlaity.</li>
+ <li>Blocker - this is preventing the correct operation of this use case and must be implmeneted ASAP</li>
+ </ul>
+
+ <p>Although this step is optional, it is good practice to allways add a
+ <code><fixme priority="blocker">Not yet implemented</fixme></code>
+ element to all new steps. This is becuase these nodes will be used to build a
+ functionality matrix later on.</p>
+ </description>
+
+ <result>Users will be able to understand to what degree a step is implemented and developers will be able to
+ see what remains to be done.</result>
+
+ <fixme priority="enhancement">All fixmes to link to an issue tracker entry</fixme>
+ </step>
+
+ <step required="false">
+ <title>Add alternatives</title>
+ <description>
+ <p>Sometimes there will be alternative paths through each step. These can be described in an
+ <code>alternatives</code> element that allows free-form XDoc content. However, please be
+ careful, if an alternative is more than a simple variation you may want to consider a
+ whole new use case for the alternative.</p>
+ </description>
+
+ <result>Minor variations in the path through a use case will be documented for your users.</result>
+ </step>
+
+ <step required="false">
+ <title>Write Implementation Notes</title>
+ <description>
+ <p>Developer implementation notes for each of the steps should be added either when writing the
+ initial use case or later during the development phases of the use case. These notes are for technical readers
+ and are intended to help those who come after the initial author to get a starting point when inspecting how
+ a feature is implemented. It is not intended that these notes will contain full implementation details, only an
+ overview should be provided.</p>
+ </description>
+
+ <result>A technical reader will be able to gain a baisc understanding of how each step is implemented in the
+ application.</result>
+ </step>
+ </steps>
+ </useCase>
+
+ <useCase status="In Progress" owner="open">
+ <title>Generate Use Case Documentation for Developers</title>
+
+ <description>
+ <p>Generate a complete list of all use cases for a project in a format useful to
+ developers of the application. This list is to include:</p>
+
+ <ul>
+ <li>a description of the use case</li>
+ <li>a summary of each of the steps involved</li>
+ <li>full details of each of the steps</li>
+ <li>a description of the expected outcome of each step</li>
+ <li>details of common alternatives in each step</li>
+ <li>implementation notes for each step</li>
+ </ul>
+
+ <section>
+ <title>Justification</title>
+ <p>A use case describes a unit of work. It is typically used in the design
+ stages of a software project, however, they can often be useful in creating
+ user documentaiton. Especially when they describe user interface functionality.</p>
+
+ <warning>Unfortunately this use case document does not currently cover all functions
+ of the plugin since this functionlaity was added after many other features. Whilst you
+ are exploring this feature, why not add a use case to the plugin and submit a patch
+ so that those coming after you can enjoy more complete documentation.</warning>
+ </section>
+ </description>
+
+ <steps>
+ <step>
+ <title>Make HTTP request</title>
+ <description>
+ <p>
+ Request
+ http://localhost:8888/docs/developer/useCases.xml
+ </p>
+ </description>
+ <result>
+ <p>
+ An XDoc is created that describes the use cases
+ </p>
+ </result>
+
+ <fixme priority="High">Make the summary optional - already added
+ $includeImplementationNotes parameter to stylesheet. Need to pass value form sitemap.</fixme>
+
+ <alternatives>
+ <p>Depending on what plugins are available within your running instance of Forrest you will
+ be able to request different output formats as per the usual Forrest usage. For example requesting
+ a http://localhost:8888/docs/developer/useCases.html will generate the HTML document, whilst
+ http://localhost:8888/docs/developer/useCases.pdf will generate the PDF document (as long
+ as you have the relevant plugins installed).</p>
+ </alternatives>
+
+ <implementation>
+ <description>
+ <p>The source document for use cases is, by default, called <code>useCases.xml</code> and is
+ located in the root of the projects xdocs directory.</p>
+
+ <p>The URL space <code>docs/**/useCases.xml</code> is reserved for the projectInfo plugin. A request to
+ /docs/developer/useCases.xml results in the useCases.xml file being translated into an XDoc as per
+ the usual forrest processing. See the input.xmap file fo this plugin,</p>
+ </description>
+ </implementation>
+ </step>
+ </steps>
+ </useCase>
+
+ <useCase status="In Progress" owner="open">
+ <title>Generate Use Case Documentation for Users</title>
+
+ <description>
+ <p>Generate a complete list of all use cases for a project. This list is to include:</p>
+
+ <ul>
+ <li>a description of the use case</li>
+ <li>a summary of each of the steps involved</li>
+ <li>full details of each of the steps</li>
+ <li>a description of the expected outcome of each step</li>
+ <li>details of common alternatives in each step</li>
+ </ul>
+
+ <section>
+ <title>Justification</title>
+ <p>A use case describes a unit of work. It is typically used in the design
+ stages of a software project, however, they can often be useful in creating
+ user documentaiton. Especially when they describe user interface functionality.</p>
+
+ <warning>Unfortunately the use case document does not currently cover all functions
+ of the plugin since this functionlaity was added after many other features. Whilst you
+ are exploring this feature, why not add a use case to the plugin and submit a patch
+ so that those coming after you can enjoy more complete documentation.</warning>
+ </section>
+ </description>
+
+ <steps>
+ <step>
+ <title>Make HTTP request</title>
+ <description>
+ <p>
+ Request
+ http://localhost:8888/docs/user/useCases.xml
+ </p>
+ </description>
+ <result>
+ <p>
+ An XDoc is created that describes the use cases
+ </p>
+ </result>
+
+ <fixme priority="High">Enable the retrieval of a specific use case rather than all at once.</fixme>
+ <fixme priority="Low">Make the summary optional - there is a switch in the XSL for this, just need to pass a property
+ from the XMAP</fixme>
+
+ <alternatives>
+ <p>Depending on what plugins are available within your running instance of Forrest you will
+ be able to request different output formats as per the usual Forrest usage. For example requesting
+ a http://localhost:8888/docs/user/useCases.html will generate the HTML document, whilst
+ http://localhost:8888/docs/user/useCases.pdf will generate the PDF document (as long
+ as you have the relevant plugins installed).</p>
+ </alternatives>
+
+ <implementation>
+ <description>
+ <p>The source document for use cases is, by default, called <code>useCases.xml</code> and is
+ located in the root of the projects xdocs directory.</p>
+
+ <p>The URL space <code>docs/**/useCases.xml</code> is reserved for the projectInfo plugin. A request to
+ /docs/user/useCases.xml results in the useCases.xml file being translated into an XDoc as per
+ the usual forrest processing, see input.xmap for more details.</p>
+ </description>
+ </implementation>
+ </step>
+ </steps>
+ </useCase>
+
+ <useCase status="In Progress">
+ <title>Generate a Functionality Matrix</title>
+ <description>
+ <p>If a use case document is correcly marked up with <code>fixme</code> elements it is possible
+ to create a functionality matrix for each use case. This will show how complete the implementation
+ of a use case is.</p>
+
+ <p>A table can be created which shows each of the steps in a use case, each step can be given a
+ count for the bumber of fixme items outstanding on each of the steps. Furthermore, since each
+ <code>fixme</code> is given a priority we can clearly indicate which use cases are operational an
+ hich are not.</p>
+ </description>
+
+ <steps>
+ <step>
+ <title>Make HTTP request</title>
+ <description>
+ <p>
+ Request
+ http://localhost:8888/docs/developer/featureMatrix/useCases.xml
+ </p>
+ </description>
+ <result>
+ <p>
+ An XDoc is created that lists the steps in each use case and identifies the status
+ of each use case.
+ </p>
+ </result>
+
+ <fixme priority="Blocker">Not Implemented Yet - although the user and dev use case documents
+ do show the status of each step in the details table and implementation notes.</fixme>
+
+ <alternatives>
+ <p>Depending on what plugins are available within your running instance of Forrest you will
+ be able to request different output formats as per the usual Forrest usage. For example requesting
+ a http://localhost:8888/docs/developer/featureMatrix/useCases.html will generate the HTML document, whilst
+ http://localhost:8888/docs/developer/featureMatrix/useCases.pdf will generate the PDF document (as long
+ as you have the relevant plugins installed).</p>
+ </alternatives>
+
+ <implementation>
+ <description>
+ <p>The source document for use cases is, by default, called <code>useCases.xml</code> and is
+ located in the root of the projects xdocs directory.</p>
+
+ <p>The URL space <code>docs/**/useCases.xml</code> is reserved for the projectInfo plugin. A request to
+ /docs/developer/featureMatrix/useCases.xml results in the useCases.xml file being translated into an XDoc as per
+ the usual forrest processing. See the input.xmap file fo this plugin,</p>
+ </description>
+ </implementation>
+ </step>
+ </steps>
+ </useCase>
+</useCases>
+
Propchange: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/src/documentation/content/xdocs/useCases.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml
URL: http://svn.apache.org/viewcvs/forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml?rev=405667&r1=405666&r2=405667&view=diff
==============================================================================
--- forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml (original)
+++ forrest/trunk/plugins/org.apache.forrest.plugin.input.projectInfo/status.xml Wed May 10 00:48:45 2006
@@ -46,6 +46,12 @@
displaying information about one or more projects.</p>
</notes>
<action type="add" context="code" dev="RDG" importance="high">
+ Add support for Use Case documentation. This can be used to generate various different
+ types of user an developer documentation, such as step by step user instructions, or
+ developer implementation notes. See <a href = "http://localhost:8888/docs/developer/useCases.html">
+ http://localhost:8888/docs/developer/useCases.html</a> for more information.
+ </action>
+ <action type="add" context="code" dev="RDG" importance="high">
Use locationmap for resolution of resources and files. Resources are exposed via
{lm:projectInfo.*}
</action>