Return-Path: Delivered-To: apmail-cocoon-cvs-archive@www.apache.org Received: (qmail 75069 invoked from network); 22 Dec 2006 08:11:49 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 22 Dec 2006 08:11:49 -0000 Received: (qmail 71326 invoked by uid 500); 22 Dec 2006 08:11:56 -0000 Delivered-To: apmail-cocoon-cvs-archive@cocoon.apache.org Received: (qmail 71196 invoked by uid 500); 22 Dec 2006 08:11:55 -0000 Mailing-List: contact cvs-help@cocoon.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@cocoon.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@cocoon.apache.org Received: (qmail 71182 invoked by uid 99); 22 Dec 2006 08:11:55 -0000 Received: from herse.apache.org (HELO herse.apache.org) (140.211.11.133) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 22 Dec 2006 00:11:55 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 22 Dec 2006 00:11:43 -0800 Received: by eris.apache.org (Postfix, from userid 65534) id A7F611A981D; Fri, 22 Dec 2006 00:10:53 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r489579 [2/4] - in /cocoon/site/site: ./ 2.1/ 2.1/howto/ 2.1/userdocs/ 2.1/userdocs/widgets/ images/ skin/ skin/images/ Date: Fri, 22 Dec 2006 08:10:52 -0000 To: cvs@cocoon.apache.org From: cziegeler@apache.org X-Mailer: svnmailer-1.1.0 Message-Id: <20061222081053.A7F611A981D@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: cocoon/site/site/2.1/howto/howto-author-faq.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.1/howto/howto-author-faq.html?view=auto&rev=489579 ============================================================================== --- cocoon/site/site/2.1/howto/howto-author-faq.html (added) +++ cocoon/site/site/2.1/howto/howto-author-faq.html Fri Dec 22 00:10:50 2006 @@ -0,0 +1,1420 @@ + + + + + + + +How to author an FAQ + + + + + + + + + +
+ +
+apache > cocoon +
+ +
+ + + + + + + +
+
+  + +
+
+ + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+

How to author an FAQ

+ +

Overview

+
+

This How-To describes the steps necessary to write an useful FAQ for the +Cocoon documentation project. FAQs are frequently asked questions. However, for +many, the word has come to mean a lot more. The Cocoon documentation project +needs your help. Writing a Cocoon FAQ is a valuable way to give back to the +community.

+
+ +

Intended Audience

+
+

Cocoon users who are ready to share their knowledge and experiences with the +larger Cocoon community. This includes users who are tired of seeing the same +questions asked repeatedly on the Cocoon users list.

+
+ +

Purpose

+
+

These guidelines are based on successful FAQ 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 and make it +easy for committers to apply it to the cvs.

+
+ +

Prerequisites

+
+

FAQ authors should have:

+
    + +
  • A unique FAQ related to any aspect of Cocoon. Check out existing FAQs to +find a conceptual hole that your FAQ can fill.
    • + +
  • A sufficient ability in English to write the FAQ. If you need a little extra +help with language, consider partnering with another user with more advanced +English writing skills.
    • + +
+
+ +

Steps

+
+

Here's how to proceed.

+ +

1. Obtain an FAQ topic file to edit

+

FAQs source files are organized in sets of XML files based on separate Cocoon +topics. You will find all FAQ files in src/documentation/xdocs/faq/. Select the +faq topic file most related to your question. If you can't find a related topic +for your question, then create a new FAQ file by copying an existing file, +editing it, and saving it with new filename based on the new topic.

+

If you plan to edit an existing file, make sure you are working with the most +recent version. The Cocoon project's cvs stores documentation files in multiple +branches. The HEAD and release branches should be in sync for documentation. +However, should there be some unintentional discrepancy, the HEAD branch is more +likely to contain the most recently updated files. If you have a checked-out +version of the cvs HEAD branch, make sure to run a cvs update before beginning +your work on any specific file. If you don't have the cvs HEAD branch, you can +obtain a list of +all +current FAQ files through browser-based ViewCVS.

+ +

2. Write the Question

+

In one to two sentences, write your question as concisely as possible.

+ +

3. Write the Answer

+

In a few paragraphs or less, answer your question. Provide links to more +detailed information within other Cocoon documentation or elsewhere on the web +if available. If your answer is dependent in any way upon a specific version or +deployment of Cocoon, please describe your environment. If you need more space +to answer the question, consider contributing a different document to provide +more comprehensive treatment of the subject. Such a document could be a How-To, +tutorial, snippet, or guide. See other How-Tos for instructions on writing such +documents.

+ +

4. Review other FAQs

+

If you are working with an existing FAQ file, take some time to review the +other FAQs. Given the rapid pace of change with Cocoon, many individual FAQs +become out-of-date and confusing to new users. If you have the relevant +knowledge, consider updating other FAQs for technical errors. And if you see a +few typos, please consider fixing them too.

+ +

5. Get some feedback

+

Consider ask a few other Cocoon users to proofread your FAQ(s). Or, post a +text version of your FAQ to the cocoon-user list, and ask for comments.

+ +

6. Review your work

+

Consider asking someone proofread your work for embarrassing spelling or +grammatical errors. At least check your document with a spell checker before +submitting it.

+ +

7. Validate your FAQ document

+

Use the most recent version of the FAQ dtd to validate your FAQ content. You +will find it in the src/documentation/xdocs/dtd directory.

+ +

8. Update any related pages

+

If you are contributing a new FAQ file, it will help committers if you also +edit the FAQ main (index.xml) and menu (book.xml) files found at +src/documentation/xdocs/faq/ to include links to your new FAQ file. You can +validate these files with their corresponding dtds as specified in their DOCTYPE +statements. If you have a working copy of the cvs HEAD, make sure you check this +additional work by performing a docs build. To do this, run the appropriate +build script inside the cocoon-2.1 directory, specifying docs as the build +target. A docs build not only validates your files but also checks for broken +links.

+ +

9. Prepare a patch

+

If you are working with an existing FAQ file, prepare a patch before +submitting. If you created a new FAQ file, it is already a patch, at least as +far as Jira is concerned. However, if you are including updated FAQ main +(index.xml) and menu (book.xml) files, you will need to create a patch for these +files before submitting your work. If you don't know how to prepare a patch, +follow the instructions in How to Prepare a Patch. +

+ +

10. Submit via Jira

+

Submit your FAQ file(s) as a patch via Jira. If you don't know how, follow +the instructions in How to Contribute a Patch via Jira. + +

+
+ +

Real World Ideas for FAQs

+
+

A good way to get started writing FAQs is to scour the user list, looking for +commonly asked questions. Or, let's say you have just invested a lot of time +learning and successfully applying a Cocoon-related component or feature in your +work. Perhaps you finally groked the command line features of Cocoon or +successfully configured a sitemap component. Consider sharing this knowledge, +while it is still fresh, with other users. Perhaps you are the author of some +other Cocoon document, for example, a new How-To. Consider adding a FAQ, with a +short description and link, to serve as a gateway to your contribution. Take a +minute to imagine how advanced the Cocoon community would become if each and +every Cocoon user took the time to contribute a single, unique FAQ. Think about +it.

+
+ +

Tips

+
+ +

FAQ dtd

+

The document structure of Cocoon's FAQ page is likely to change soon. Please +note that this How-To page is likely to change as well.

+
+ +

References

+
+

FAQs mean different things to different people. For additional insight and +perspectives, check out the following.

+ +
+ +

Comments

+
+

Care to comment on this How-To? Got another tip? Help keep this How-To +relevant by passing along any useful feedback to the author, +Diana Shannon. +

+
+

+Errors and Improvements? + If you see any errors or potential improvements in this document + please help us: + + View, Edit or comment on + the latest development version (registration required). +

+
+
+
+ +
 
+
+ + + Propchange: cocoon/site/site/2.1/howto/howto-author-faq.html ------------------------------------------------------------------------------ svn:eol-style = native Propchange: cocoon/site/site/2.1/howto/howto-author-faq.html ------------------------------------------------------------------------------ svn:keywords = Id Modified: cocoon/site/site/2.1/index.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.1/index.html?view=diff&rev=489579&r1=489578&r2=489579 ============================================================================== --- cocoon/site/site/2.1/index.html (original) +++ cocoon/site/site/2.1/index.html Fri Dec 22 00:10:50 2006 @@ -1249,7 +1249,7 @@

Where can I find it?

-

To download the latest release (currently 2.1.9) of Apache Cocoon, go to the +

To download the latest release (currently 2.1.10) of Apache Cocoon, go to the download area.

If you are looking for a past generation of Cocoon (no longer supported but Modified: cocoon/site/site/2.1/userdocs/widgets/widget_field.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.1/userdocs/widgets/widget_field.html?view=diff&rev=489579&r1=489578&r2=489579 ============================================================================== --- cocoon/site/site/2.1/userdocs/widgets/widget_field.html (original) +++ cocoon/site/site/2.1/userdocs/widgets/widget_field.html Fri Dec 22 00:10:50 2006 @@ -1269,7 +1269,8 @@

Definition

Configuration example:

-
<fd:field id="..." required="true|false" state="...">
+
<fd:field id="..." required="true|false" state="..."
+          whitespace="trim|trim-start|trim-end|preserve">
   <fd:label>...</fd:label>
   <fd:hint>...</fd:hint>
   <fd:help>...</fd:help>
@@ -1302,6 +1303,13 @@
 

 
The state attribute is optional. See
 Widget States for its purpose.

+
The whitespace attribute is optional. It controls how
+leading and trailing whitespace characters are handled when the widget parses
+the value submitted by the user. Accepted values are: "trim" (removes both
+leading and trailing whitespace), "trim-start" (removes leading whitespace
+only), "trim-end" (removes trailing whitespace only), and "preserve" (leaves
+both leading and trailing whitespace intact). If the whitespace attribute is not
+present, it defaults to "trim".

 
The fd:label element contains the label for this widget.
 This element is optional. It can contain mixed content. For internationalised
 labels, use i18n-tags in combination with Cocoon's I18nTransformer.

@@ -1350,14 +1358,14 @@
 case when you use flowscript. If you don't use flowscript you could store the
 form instance in e.g. the session.
- +

Template

A field widget is inserted in a template using the ft:widget tag:

<ft:widget id="..."/>
- +

Styling (default HTML XSL)

If the field widget does not have a selection list, it will be rendered as Modified: cocoon/site/site/2.1/userdocs/widgets/widget_imagemap.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.1/userdocs/widgets/widget_imagemap.html?view=diff&rev=489579&r1=489578&r2=489579 ============================================================================== --- cocoon/site/site/2.1/userdocs/widgets/widget_imagemap.html (original) +++ cocoon/site/site/2.1/userdocs/widgets/widget_imagemap.html Fri Dec 22 00:10:50 2006 @@ -1215,17 +1215,19 @@ +-->

ImageMap widget

- -

+ +

Concept

-

Concept

It is used to display a server-side image map and it triggers an ImageMap event on the server side when clicked.
It behaves much as an Action widget, but you can bind the source URI of the image using the binding framework "fb:value" element, set the image at runtime using the setImageURI() method, and retrieve the mouse coordinates with getX() and getY() methods.

-

Definition

+
+ +

Definition

+
<fd:imagemap id="map">
     <fd:imageuri>test.gif</fd:imageuri>
     <fd:hint>Click on this map to zoom-in</fd:hint>
@@ -1233,14 +1235,23 @@
         <javascript>onClickMap(event);</javascript>
     </fd:on-action>
 </fd:imagemap>
-

Binding

+
+ +

Binding

+
<fb:value id="map" path="@src"/>
-

Template

+
+ +

Template

+
<ft:widget id="map">
 	<fi:styling xmlns:fi="http://apache.org/cocoon/forms/1.0#instance"
 		border="2"/>
 </ft:widget>
-

Flow

+
+ +

Flow

+

This is another way to set the image URI:

frm.getWidget().lookupWidget("map").setImageURI("test2.gif");

This is the handler of the imagemap event:

Modified: cocoon/site/site/2.1/userdocs/xmlbinding.html URL: http://svn.apache.org/viewvc/cocoon/site/site/2.1/userdocs/xmlbinding.html?view=diff&rev=489579&r1=489578&r2=489579 ============================================================================== --- cocoon/site/site/2.1/userdocs/xmlbinding.html (original) +++ cocoon/site/site/2.1/userdocs/xmlbinding.html Fri Dec 22 00:10:50 2006 @@ -1217,17 +1217,17 @@

Concept

As an alternative for the more flexible binding -framework, there is also a simpler solution when that can be used when there -is a 1-to-1 coupling between the XML and the form.

+framework, there is also a simpler solution that can be used when there is a +1-to-1 coupling between the XML and the form.

The XML format is such that there is one XML element for each widget and the -element gets the widget id as name. Exceptions from this is that the elements in -a repeater get the name "item" and an attribute +element gets the widget id as name. Exceptions from this are that the elements +in a repeater get the name "item" and an attribute "position" with the position of the repeater child, instead of just a number (which is not allowed as element name). Childs of a -MultiValueField are also embeded within an "item" -element. If the Form widget does not have an id it get the name "unknown".

+MultiValueField are also embedded within an "item" +element. If the Form widget does not have an id it gets the name "unknown".

An AggregateField can both be interpreted as one value and as several -widgets. This ambiguity is resolved by chosing to emit the single value rather +widgets. This ambiguity is resolved by choosing to emit the single value rather than the fields as XML. For population of the form both forms are however allowed.

Modified: cocoon/site/site/images/cocoon-logo.gif URL: http://svn.apache.org/viewvc/cocoon/site/site/images/cocoon-logo.gif?view=diff&rev=489579&r1=489578&r2=489579 ============================================================================== Binary files /tmp/tmpiigORd and /tmp/tmpj7sPpY differ