How to modify the color of generated corner images

Understand how corner images are named (the contract)

- The corner images are referenced in some .css files of the - above-named skins; for example, in screen.css of the pelt skin: + The corner images are referenced in some .css files of the above-named + skins; for example, in screen.css of the pelt skin:

/*Example from screen.css of pelt*/ @@ -84,8 +79,8 @@ ...

- The naming follows a contract which is described below. In general, - the naming looks like: + The naming follows a contract which is described below. In general, the + naming looks like:

images/{$name}-{$v-orientation}-{$h-orientation}-{$size}-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor} @@ -98,8 +93,8 @@ (-1{$backgroundColor}-2{$strokeColor}-3{$foregroundColor}) identifies the coloring of each portion of the image. The input parameter for the second part comes from the color profile of - src/documentation/skinconf.xml. The second part is - easily identifiable through the numbering 1-2-3. + src/documentation/skinconf.xml. The second part is easily + identifiable through the numbering 1-2-3.

Let us get into details: @@ -108,80 +103,58 @@

images

Path to the xslt that creates the corner. -
- images/ = {$FORREST_HOME}/main/webapp/skins/common/images/ -

+
images/ = {$FORREST_HOME}/main/webapp/skins/common/images/

{$name}

In the common skin there are two XSLT files ready for use:

- rc.svg.xslt: handles rounded corners +
rc.svg.xslt: handles rounded corners
- dc.svg.xslt: handles diagonal 45-degree corners +
dc.svg.xslt: handles diagonal 45-degree corners

- name = [rc|dc] -
- e.g. rc -

+ name = [rc|dc] +
e.g.rc

{$v-orientation}

Vertical orientation of the corner images (top or bottom). -
- v-orientation = [t|b] -
- e.g. t -

+
v-orientation = [t|b] +
e.g.t

{$h-orientation}

Horizontal orientation of the corner images (left or right). -
- h-orientation = [l|r] -
- e.g. r -

+
h-orientation = [l|r] +
e.g.r

{$size}

Pixels size of the width and height of the corner image. -
- size=x -
- e.g. 5 -

+
size=x +
e.g.5

{$backgroundColor}

Any <color name=""/> element in the skinconf.xml (the value="{$color}" attribute will be applied). -
- e.g. header -

+
e.g.header

{$strokeColor}

Any <color name=""/> element in the skinconf.xml (the value="{$color}" attribute will be applied). -
- e.g. searchbox -

+
e.g.searchbox

{$foregroundColor}

Any <color name=""/> element in the skinconf.xml (the value="{$color}" attribute will be applied). -
- e.g. searchbox -

+
e.g.searchbox

- The first part of this howto explains the html pipeline, so as to - provide the background to enable you to add additional processing - for legacy html documents. If you already know how pipelines work, - then skip to the section about - Customizing the html pipeline. + The first part of this howto explains the html pipeline, so as to provide + the background to enable you to add additional processing for legacy html + documents. If you already know how pipelines work, then skip to the + section about Customizing the html pipeline.

Second Match for '**body-*.html'

- Continue searching downwards for '**body-*.html' in the - sitemap-file or jump directly to the - Second Match for '**body-*.html'. + Continue searching downwards for '**body-*.html' in the sitemap-file or + jump directly to the + Second + Match for '**body-*.html'.

- Looking at the pipeline that handles the request, we see that - the cocoon-protocol is once again invoked -

- ]]> + Looking at the pipeline that handles the request, we see that the + cocoon-protocol is once again invoked +

+ +]]> +

this time as a direct generator of input for our pipeline.

- So once again we ask Forrest to process a request for content. - To know what matcher to look for, let's first expand the variables: + So once again we ask Forrest to process a request for content. To know + what matcher to look for, let's first expand the variables:

- In our example the matcher pattern - **body-*.html is applied to the request-name - mytest/body-mybad.html. - Which means that we have three variables altogether: + In our example the matcher pattern **body-*.html is applied + to the request-name mytest/body-mybad.html. Which means + that we have three variables altogether:

@@ -396,11 +371,15 @@

If we insert that into

- ]]> + +]]> +

we get

- ]]> + +]]> +

Third Call for Content @@ -414,60 +393,57 @@ which is the standard handling for all xml-requests.

- Since our request fulfils none of the secondary criteria in - this pipeline, it falls right through to the map:mount-element - at the end: -

- ]]> + Since our request fulfils none of the secondary criteria in this + pipeline, it falls right through to the map:mount-element at the end: +

+ +]]> +

- which makes Forrest load and process a secondary sitemap, - the file 'forrest.xmap' in the same directory. + which makes Forrest load and process a secondary sitemap, the file + 'forrest.xmap' in the same directory.

- Open the file 'forrest.xmap' and continue the search for a - matching pattern. + Open the file 'forrest.xmap' and continue the search for a matching + pattern.

- Our search leads us to the - - Second Match for '**.xml' - , - a pipeline designed to handle internationalisation if that - feature is configured. Since it is not, all it does is - call the file-resolver-resource with the full pathname of - our file but no extension. + Our search leads us to the + Second Match + for '**.xml' , a pipeline designed to handle internationalisation if + that feature is configured. Since it is not, all it does is call the + file-resolver-resource with the full pathname of our file but no + extension.

- + -]]> +]]> +

Introducing the File-Resolver

- To find out more about the working of the file-resolver, - search for the definition of the + To find out more about the working of the file-resolver, search for the + definition of the - <map:resource name="file-resolver"> - - higher up in the file. + <map:resource name="file-resolver"> higher up in the file.

- Here you will find a pipeline that tests for the existence of - the file with different extensions. '.html' is second in this - list and leads to the processing steps shown below: + Here you will find a pipeline that tests for the existence of the file + with different extensions. '.html' is second in this list and leads to + the processing steps shown below:

html-Default Processing

- The default processing of html-files consists of four - processing steps: + The default processing of html-files consists of four processing steps:

- <map:generate src="{properties:content.xdocs}{uri}.html" type="html"/>
+
<map:generate src="{properties:content.xdocs}{uri}.html" type="html"/> +
Using the html-generator, Forrest reads the html-document from file and uses JTidy to clean up and convert it to xml (which is required for all processing in cocoon pipelines). @@ -476,52 +452,50 @@ elements. We'll deal with those later (see When to customize).
- <map:transform src="{forrest:forrest.stylesheets}/html2document.xsl"/>
+
<map:transform src="{forrest:forrest.stylesheets}/html2document.xsl"/> +
Using the standard stylesheet 'html2document.xsl', this XHTML is transformed into Forrest standard document format.
- <map:transform type="idgen"/>
+
<map:transform type="idgen"/> +
This step generates IDs required for navigation within the page.
- <map:serialize type="xml-document"/>
+
<map:serialize type="xml-document"/> +
Finally the document is serialized as XML and returned to the calling pipeline.

- As a result, we now hand back the content of the html-document - in Forrest standard document format to the calling pipeline + As a result, we now hand back the content of the html-document in + Forrest standard document format to the calling pipeline

- To look at the output of this pipeline you can simply - point you browser to 'http://localhost:8888/mytest/mybad.xml' - (assuming that you are currently running Forrest on your - machine and there is an html-page of that name). + To look at the output of this pipeline you can simply point you browser + to 'http://localhost:8888/mytest/mybad.xml' (assuming that you are + currently running Forrest on your machine and there is an html-page of + that name).

Returning to the '**body-*.html'-Pipeline

On returning into the - '**body-*.html' pipeline, - procesing continues with the next components in this pipeline: + '**body-*.html' + pipeline, procesing continues with the next components in this + pipeline:

- idgen will generate unique IDs for all elements +
idgen will generate unique IDs for all elements that need to be referenced within a page (mainly headlines).
- xinclude would process any xinclude statements +
xinclude would process any xinclude statements in the source. Since HTML does not support this mechanism, nothing happens in our example.
- linkrewriter adjusts links between pages +
linkrewriter adjusts links between pages so that they will still work in the final Forrest output directory structure. It also resolves any special Forrest links.

- To look at the output of this pipeline you can simply - point you browser to 'http://localhost:8888/mytest/body-mybad.html' - (assuming that you are currently running Forrest on your machine - and there is an html-page of that name). + To look at the output of this pipeline you can simply point you browser + to 'http://localhost:8888/mytest/body-mybad.html' (assuming that you are + currently running Forrest on your machine and there is an html-page of + that name).

Returning to the '**/*.html'-Pipeline

- At the end of this pipeline, processing returns the results into - the aggregation section of the - '**/*.html' Pipeline, - merges it with other data, skins and serializes for presentation - in the requesting client. + At the end of this pipeline, processing returns the results into the + aggregation section of the '**/*.html' + Pipeline, merges it with other data, skins and serializes for + presentation in the requesting client.

Customizing the html pipeline

In this last part of this document, we will show how to customize the HTML-pipeline to add your additional steps to the default processing.

When to customize? -

- The html-Pipeline in Forrest is designed to be able to also - integrate legacy html-Pages in a Forrest project. In doing so, - it will fix common markup errors and convert html to Forrest's - intermediate document format. + The html-Pipeline in Forrest is designed to be able to also integrate + legacy html-Pages in a Forrest project. In doing so, it will fix + common markup errors and convert html to Forrest's intermediate + document format.

Due to the nature of html as presentational markup, there is no way - this automated process can identify elements in your pages that - are not required or even unwanted in the Forrest environment. + this automated process can identify elements in your pages that are + not required or even unwanted in the Forrest environment.

A good example are pages from sites where the navigational elements - (menus, tabs etc.) are embedded in the html of each page. - Since Forrest can't know what is an unwanted menu and what belongs - to the page body that you want to keep, you will need to customize - the process to remove elements that are not needed. If you don't, - then you will see the original page from your legacy website, - menu and all, embedded in your new Forrest site. + (menus, tabs etc.) are embedded in the html of each page. Since + Forrest can't know what is an unwanted menu and what belongs to the + page body that you want to keep, you will need to customize the + process to remove elements that are not needed. If you don't, then you + will see the original page from your legacy website, menu and all, + embedded in your new Forrest site.

How to customize?

@@ -594,77 +562,76 @@

This project sitemap is located in the file - 'src/documentation/sitemap.xmap' in your Forrest project directory - and will be created automatically when you seed a new project. - At this point it contains only one + 'src/documentation/sitemap.xmap' in your Forrest project directory and + will be created automatically when you seed a new project. At this + point it contains only one pipeline for handling the '**custom.xml'-pattern as an example.

To add your own custom processing, edit the file and add a new - pipeline to the project sitemap. Since the project sitemap is - loaded into the main sitemap - - right at the top, your pipeline intercepts practically all - of Forrest's standard pipelines. + pipeline to the project sitemap. Since the project sitemap is loaded + into the main sitemap + right + at the top, your pipeline intercepts practically all of Forrest's + standard pipelines.

What to intercept?

Where to intercept standard processing is really a matter of your - choice. A good rule is to replace as little standard handling - as possible so that future changes in the Forrest architecture are - less likely to break your application. + choice. A good rule is to replace as little standard handling as + possible so that future changes in the Forrest architecture are less + likely to break your application.

- In our case all we need to do is add a transformation that - removes all the unwanted elements. The best place to do this - would be right after the generator has converted our document to - xhtml. + In our case all we need to do is add a transformation that removes all + the unwanted elements. The best place to do this would be right after + the generator has converted our document to xhtml.

- However, since we can only replace a complete pipeline, - we'll create a new pipeline that intercepts **.xml for our pages, - copy the steps the original processor is doing and add a - transformation of our own to it. + However, since we can only replace a complete pipeline, we'll create a + new pipeline that intercepts **.xml for our pages, copy the steps the + original processor is doing and add a transformation of our own to it.

Intercept pattern

- Take great care when intercepting very basic pipelines. - Instead of designing our custom pipeline to match the - original **.xml pattern, try to narrow your matcher down to - something that will only match your pages. + Take great care when intercepting very basic pipelines. Instead of + designing our custom pipeline to match the original **.xml pattern, + try to narrow your matcher down to something that will only match your + pages.

- If all your pages are located in a directory called mytest, - then use a matcher like '/mytest/*.xml' to avoid highjacking - the processing for all the other requests. + If all your pages are located in a directory called mytest, then use a + matcher like '/mytest/*.xml' to avoid highjacking the processing for + all the other requests.

- Add a new pipeline in your project sitemap and set the matcher - to '/mytest/*.xml'. + Add a new pipeline in your project sitemap and set the matcher to + '/mytest/*.xml'.

The new pipeline should look like this and does nothing so far.

- + -]]> +]]> +

- Open the 'forrest.xmap', navigate to the file-resolver-section, - copy the four lines for handling *.html files and paste them into - your new pipeline. + Open the 'forrest.xmap', navigate to the file-resolver-section, copy + the four lines for handling *.html files and paste them into your new + pipeline.

- - + @@ -673,24 +640,26 @@ -]]> +]]> +

Your custom pipeline will now behave exactly like the standard - html-handler. Now all that is left to be done is creating the - custom transformation and adding it the pipeline. + html-handler. Now all that is left to be done is creating the custom + transformation and adding it the pipeline.

- Design and test a new XSL-Transformation that removes the - unwanted elements and save it in your project's stylesheet - directory, usually src/documentation/resources/stylesheets - (defined in project.stylesheets-dir of forrest.properties), - which is central storage for all stylesheets in a project. + Design and test a new XSL-Transformation that removes the unwanted + elements and save it in your project's stylesheet directory, usually + src/documentation/resources/stylesheets (defined in + project.stylesheets-dir of forrest.properties), which is central + storage for all stylesheets in a project.

Add the new transformation as a new line, straight after the - generator, and save the changes. + generator, and save the changes.

- + @@ -700,19 +669,18 @@ -]]> +]]> +

- Done! You have just added your own custom-processing. - Don't forget to view the pages to verify that it is working - properly. -

+ Done! You have just added your own custom-processing. Don't forget to + view the pages to verify that it is working properly. +

- Our pipeline does not exactly do what the original pipeline does. - To make things easier, we omitted the internationalization part - in our pipeline. So if you need to create multi-language sites, - make sure that you adjust your pipeline accordingly. + Our pipeline does not exactly do what the original pipeline does. To + make things easier, we omitted the internationalization part in our + pipeline. So if you need to create multi-language sites, make sure + that you adjust your pipeline accordingly. -

Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-editcss.xml Mon Apr 9 20:48:52 2007 @@ -20,63 +20,60 @@

How to customize Forrest CSS WYSIWYG-style - This How-To shows how to use Mozilla - Firebird and the free EditCSS-Plugin to - customize your Forrest design in a - WYSIWYG-way. + + This How-To shows how to use Mozilla Firebird and the free EditCSS-Plugin + to customize your Forrest design in a WYSIWYG-way. +

- -

Users who want to customize the Forrest look - and feel or simply experiment with changing - certain CSS-styles settings to see what - happens.

+ Users who want to customize the Forrest look and feel or simply experiment + with changing certain CSS-styles settings to see what happens. +

A major part of Forrest's look and feel is - controlled by a few CSS style sheets. Since - Forrest allows you to override these settings, - changing the CSS is a quick and easy - alternative to creating (and maintaining) a - whole new skin.

You'll learn how to use free tools to change - and experiment with styles in a WYSIWYG way, so - that you can immediately see what effect - changing a CSS property will have on the - look and feel of your Forrest.

- +

+ A major part of Forrest's look and feel is controlled by a few CSS style + sheets. Since Forrest allows you to override these settings, changing the + CSS is a quick and easy alternative to creating (and maintaining) a whole + new skin. +

+ You'll learn how to use free tools to change and experiment with styles in + a WYSIWYG way, so that you can immediately see what effect changing a CSS + property will have on the look and feel of your Forrest. +

To follow these instructions you will need:

+ To follow these instructions you will need: +

Browser-access to the Forrest-site you want to experiment with. Starting with a new 'forrest seed' site is good for your first attempt. - You can even - experiment with Forrest's core skins CSS. Please send patches if - you enhance something. -

+ You can even experiment with Forrest's core skins CSS. Please send + patches if you enhance something. +

The current version of the free Mozilla Firefox-Browser installed on your system. If you don't already use it, you can download it from http://www.mozilla.org/products/firefox/ -
The Firefox-PlugIn EditCSS. It downloads and installs in just a few seconds from the Install-Link at http://editcss.mozdev.org/ - With standard security settings in - place, Firefox will pop up a line at the top - of the window because this site has by - default no permission to install plugins on - your computer. Click "Edit Options" and - then "Allow" to change that, then click on - the Install-link again. Don't forget to - close and restart Firebird when the - installation is finished.

+ With standard security settings in place, Firefox will pop up a line + at the top of the window because this site has by default no + permission to install plugins on your computer. Click "Edit Options" + and then "Allow" to change that, then click on the Install-link again. + Don't forget to close and restart Firebird when the installation is + finished. +

A basic understanding of CSS and access to a good CSS-reference. Tutorials and Reference can be found at -
Open your Forrest -
Start your Firefox - Browser and open the Forrest you'd like to - work on/play with.
-
The page you have pointed to will show up in - Firefox's main window.
+
+ Start your Firefox Browser and open the Forrest you'd like to work + on/play with. +
+
+ The page you have pointed to will show up in Firefox's main window. +

Open the EditCSS-Sidebar - -
Select - View-Sidebar-EditCSS from Firefox's main - menu to open the EditCSS sidebar.
-
The EditCSS sidebar will show next to the - main window and load all the styles from - the main page.
+
+ Select View-Sidebar-EditCSS from Firefox's main menu to open the EditCSS + sidebar. +
+
+ The EditCSS sidebar will show next to the main window and load all the + styles from the main page. +

Change any CSS -
Change any style you'd - like to experiment with or add new settings - and styles of your choice by simply - editing the text of the sidebar.
-
EditCSS pushes any change you make in the - sidebar right back into the style-settings - of the main window, so that effects will - show right away.
- - On slow systems or when inserting big - changes it might be a good idea to paste - these from the clipboard to avoid a zillion - updates to the main windows for every - character you type. +
+ Change any style you'd like to experiment with or add new settings and + styles of your choice by simply editing the text of the sidebar. +
+
+ EditCSS pushes any change you make in the sidebar right back into the + style-settings of the main window, so that effects will show right away. +
+ + On slow systems or when inserting big changes it might be a good idea to + paste these from the clipboard to avoid a zillion updates to the main + windows for every character you type. +

How to save changes? -
Since it takes a few explanations to apply - the changes to your Forrest, I've made - this the topic of yet another HowTo called - "Howto change and extend Forrest-CSS"
+
+ Since it takes a few explanations to apply the changes to your Forrest, + I've made this the topic of yet another HowTo called "Howto change and + extend Forrest-CSS" +

- -
Please provide feedback about this document via - the mailing - lists.
+
+ Please provide feedback about this document via the + mailing lists. +
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrest-from-maven.xml Mon Apr 9 20:48:52 2007 @@ -20,58 +20,56 @@
How to run Forrest from within Maven - - This How-To describes how to run Forrest from within - Maven. - + + This How-To describes how to run Forrest from within Maven. +
- -
Users who want to run Forrest from within Maven.
+
+ Users who want to run Forrest from within Maven. +
- -
One may want to generate their project's documentation and/or website - using Forrest in lieu of Maven's site plugin.
+
+ One may want to generate their project's documentation and/or website + using Forrest in lieu of Maven's site plugin. +
-
- Understand how to add goals to maven.xml.
- -
The procedure outlined below describes how to add a goal to your - project's maven.xml that will invoke Forrest's site - target.
- +
+ The procedure outlined below describes how to add a goal to your project's + maven.xml that will invoke Forrest's site target. +

Set the FORREST_HOME environment variable - -
Make sure the FORREST_HOME environment variable points to your - Forrest home directory (i.e. the directory that contains - forrest.build.xml) (e.g. C:\opt\apache-forrest-0.7)
+
+ Make sure the FORREST_HOME environment variable points to your Forrest + home directory (i.e. the directory that contains + forrest.build.xml) (e.g. C:\opt\apache-forrest-0.7) +

-
Initialize an Ant environment property at the top of maven.xml - -
Paste the following line at the top of your maven.xml:
- +
+ Paste the following line at the top of your maven.xml: +
<property environment="env" />
-
Add forrest goal to maven.xml - -
Paste the following goal into your project's maven.xml:
- +
+ Paste the following goal into your project's maven.xml: +
<goal name="forrest" description="runs Forrest"> <property name="forrest.home" location="${env.FORREST_HOME}" /> @@ -91,22 +89,26 @@ </java> </goal> - -
It is necessary to fork a separate java process because Maven 1.0 - embeds Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The - goal makes use of the copy of Ant 1.6 that is bundled with Forrest, so - it's not even necessary to have Ant 1.6 installed separately.
+
+ It is necessary to fork a separate java process because Maven 1.0 embeds + Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The goal + makes use of the copy of Ant 1.6 that is bundled with Forrest, so it's + not even necessary to have Ant 1.6 installed separately. +

-
Alternative file - -
Under $FORREST_HOME/tools/targets/maven.xml
+
+ Under $FORREST_HOME/tools/targets/maven.xml +

- -
Please provide feedback about this document via the mailing lists.
+
+ Please provide feedback about this document via the + mailing lists. + +
Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-forrestbot.xml Mon Apr 9 20:48:52 2007 @@ -16,48 +16,47 @@ limitations under the License. --> -
-
- How to deploy your site with the forrestbot via a cron job - - This How-To describes the deployment of a forrest documentation with the help of the forrestbot. - This deployment task will then be automated via a cron tab. - - -
- +
+ How to deploy your site with the forrestbot via a cron job + + This How-To describes the deployment of a forrest documentation with the + help of the forrestbot. This deployment task will then be automated via a + cron tab. + + +

- Users who need to deploy a forrest documentation on a regular basis and want to automate this task. + Users who need to deploy a forrest documentation on a regular basis and + want to automate this task.
-
- If you are administrate a forrest documentation and have to deploy it on a regular basis - the process is sometimes quite time consuming. One feature of forrest is the forrestbot. - This bot can build the documentation and later on deploy it to a server of your choice. - You will learn how to use this forrestbot and how to mae programmed deployments. + If you are administrate a forrest documentation and have to deploy it on a + regular basis the process is sometimes quite time consuming. One feature + of forrest is the forrestbot. This bot can build the documentation and + later on deploy it to a server of your choice. You will learn how to use + this forrestbot and how to mae programmed deployments.
-
- Understand how the forrestbot works in following the Forrestbot document.
- -
- Create your project's main sitemap.xmap -
- In the Forrestbot document you have seen an example - of a buildfile for a cvs source. We will now use a local source. -
- - +
+ Create your project's main sitemap.xmap +
+ In the Forrestbot document you have + seen an example of a buildfile for a cvs source. We will now use a local + source. +
+ + @@ -73,12 +72,9 @@ ]]> - -
- - + +
-
Please provide feedback about this document via the Modified: forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml URL: http://svn.apache.org/viewvc/forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml?view=diff&rev=527010&r1=527009&r2=527010 ============================================================================== --- forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml (original) +++ forrest/trunk/site-author/content/xdocs/docs_0_70/howto/howto-howto.xml Mon Apr 9 20:48:52 2007 @@ -20,161 +20,159 @@
How to write a How-To - 0.3 - - This How-To describes the steps necessary to write a How-To - document. Writing documentation is a valuable way to give back to the - community. - + + This How-To describes the steps necessary to write a How-To document. + Writing documentation is a valuable way to give back to the community. +
- -
Users who are ready to share their knowledge and experiences with the - community.
+
+ Users who are ready to share their knowledge and experiences with the + community. +
- -
These guidelines are based on successful how-to document structures - used by other open source projects with diverse author groups. Following - these tried and true guidelines will help to insure the effectiveness of - your work.
+
+ These guidelines are based on successful how-to document structures used + by other open source projects with diverse author groups. Following these + tried and true guidelines will help to insure the effectiveness of your + work. +
-
-
How-To authors should have:
- +
+ How-To authors should have: +
- A unique How-To topic, related to using Forrest, which fulfills a specific need. Check out existing How-Tos to find a niche for your work. Consider posting your idea for the How-To to user mailing list, to make sure another author's draft is not already in process.
- A sufficient ability in English to write the FAQ. However, we would rather that you just make a start, as the community can help to fine-tune the document.
- Copy this template document "howto-howto.xml" to be modified with your own content as necessary.
- An understanding of the How-To document structure. Just use this template document and you will be safe. Make sure you run 'forrest validate-xdocs' before contributing your document.
- - See the DTD documentation - which explains the document structure. + + See the DTD documentation which explains + the document structure. +
- -
Here is how to proceed.
- +
+ Here is how to proceed. +

Write the Overview - -
An overview helps potential readers to determine quickly if a - particular How-To matches their interests or needs. In a few sentences, - summarize the main points of your How-To. Make sure to include any - critical definitions which will help readers evaluate the utility of - your How-To. Consider writing the overview last, after you have - completed all other sections.
+
+ An overview helps potential readers to determine quickly if a particular + How-To matches their interests or needs. In a few sentences, summarize + the main points of your How-To. Make sure to include any critical + definitions which will help readers evaluate the utility of your How-To. + Consider writing the overview last, after you have completed all other + sections. +

-
Describe your Intended Audience - -
If your How-To is targetted at a specific audience, describe it here. - For example, potential readers will have different levels of skill using - Forrest. They will also bring different areas of expertise and - backgrounds to their How-To learning experience. When you clarify your - target audience up front, you will save all other readers time and - confusion.
+
+ If your How-To is targetted at a specific audience, describe it here. + For example, potential readers will have different levels of skill using + Forrest. They will also bring different areas of expertise and + backgrounds to their How-To learning experience. When you clarify your + target audience up front, you will save all other readers time and + confusion. +

-
State the Purpose - -
State the purpose of your How-To. Explain how the reader will benefit - by reading it. Give your reader an incentive or two to continue.
+
+ State the purpose of your How-To. Explain how the reader will benefit by + reading it. Give your reader an incentive or two to continue. +

-
List any Prerequisites - -
Inform your reader about any required knowledge, configuration, or - resources they may need before stepping through your How-To. Assist them - in this preparation by linking to other useful resources on the Forrest - site or the web. Helping your readers to prepare increases the - likelihood that they will continue reading your How-To.
+
+ Inform your reader about any required knowledge, configuration, or + resources they may need before stepping through your How-To. Assist them + in this preparation by linking to other useful resources on the Forrest + site or the web. Helping your readers to prepare increases the + likelihood that they will continue reading your How-To. +

-
Describe the Steps of your How-To - -
In a precise, step-by-step approach, walk your reader through the - process. Make sure your reader can reproduce your intended result by - following your exact steps. Make the learning process efficient by - supplying sample code snippets or configuration details as - necessary.
+
+ In a precise, step-by-step approach, walk your reader through the + process. Make sure your reader can reproduce your intended result by + following your exact steps. Make the learning process efficient by + supplying sample code snippets or configuration details as necessary. +

-
Extend the Learning - -
Provide your reader with a few real-world examples of how the - techniques or capabilities gained from your How-To could be applied. - Reward the reader for successfully completing the How-To with a few - ideas about how it will pay off.
+
+ Provide your reader with a few real-world examples of how the techniques + or capabilities gained from your How-To could be applied. Reward the + reader for successfully completing the How-To with a few ideas about how + it will pay off. +

-
Summarize the Entire Process - -
In a few sentences, remind the reader what they have just learned. - This helps to reinforce the main points of your How-To.
+
+ In a few sentences, remind the reader what they have just learned. This + helps to reinforce the main points of your How-To. +

-
Additional Tips or FAQs - -
In some cases, step-by-step instructions simply aren't enough. Use - this section to pass on any other tips or frequently asked questions. - Anticipating the needs of your readers will increase the overall success - of your writing effort.
+
+ In some cases, step-by-step instructions simply aren't enough. Use this + section to pass on any other tips or frequently asked questions. + Anticipating the needs of your readers will increase the overall success + of your writing effort. +

-
References - -
Remember to acknowledge any third-party resources or individuals who - contributed to the development of your How-To. Consider providing links - for those motivated readers who want to learn more.
+
+ Remember to acknowledge any third-party resources or individuals who + contributed to the development of your How-To. Consider providing links + for those motivated readers who want to learn more. +

-
Submit via the project issue tracker - -
Create an attachment for your How-To document, and submit it via the - project issue tracker.
+
+ Create an attachment for your How-To document, and submit it via the + project issue tracker. +

-
Get some feedback - -
When the committers have added your document then it will be - available for everyone to to build upon and enhance. Feedback will - happen via the mailing lists.
+
+ When the committers have added your document then it will be available + for everyone to to build upon and enhance. Feedback will happen via the + mailing lists. +

- -
Solutions can be extended to cover many different problem domains. A - nearly unlimited number of potential How-To topics, from simple to - complex, are available right now, limited only by your imagination.
+
+ Solutions can be extended to cover many different problem domains. A + nearly unlimited number of potential How-To topics, from simple to + complex, are available right now, limited only by your imagination. +
- Frequently Asked Questions @@ -182,51 +180,51 @@ What is the difference between a How-To and a tutorial? - -
The goal of a How-To is to help the reader to accomplish a specific - task with clear and consise instructions. While tutorials may contain - How-To-like instructions and content, they also include additional - background and conceptual content to help teach their readers higher - order concepts along the way. How-Tos are concerned about filling an - immediate, short-term need. Tutorials often provide long-term - knowledge which can be applied across a range of needs.
+
+ The goal of a How-To is to help the reader to accomplish a specific + task with clear and consise instructions. While tutorials may + contain How-To-like instructions and content, they also include + additional background and conceptual content to help teach their + readers higher order concepts along the way. How-Tos are concerned + about filling an immediate, short-term need. Tutorials often provide + long-term knowledge which can be applied across a range of needs. +
- Style issues What spelling convention should I follow? - -
Use whatever spelling convention (American, British, etc.) that is - most intuitive to you.
+
+ Use whatever spelling convention (American, British, etc.) that is + most intuitive to you. +
-
How-To dtd - -
The document structure is likely to change soon. Please note that - this HOWTO page is likely to change as well.
+
+ The document structure is likely to change soon. Please note that this + HOWTO page is likely to change as well. +

-
-
This is not the first, nor will it be the last, How-To on writing - How-Tos. For other ideas and opinions on the matter, check out the - following sources.
- +
+ This is not the first, nor will it be the last, How-To on writing How-Tos. + For other ideas and opinions on the matter, check out the following + sources. +
- Joel D. Canfield's How to Write a How-To on evolt.org.
- The Linux Documentation Project's HOWTO index page provides many excellent How-To documents to inspire your