From commits-return-543-apmail-sis-commits-archive=sis.apache.org@sis.apache.org Tue Sep 25 08:29:47 2012 Return-Path: X-Original-To: apmail-sis-commits-archive@www.apache.org Delivered-To: apmail-sis-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 425F5DC29 for ; Tue, 25 Sep 2012 08:29:47 +0000 (UTC) Received: (qmail 95348 invoked by uid 500); 25 Sep 2012 08:29:47 -0000 Delivered-To: apmail-sis-commits-archive@sis.apache.org Received: (qmail 95252 invoked by uid 500); 25 Sep 2012 08:29:43 -0000 Mailing-List: contact commits-help@sis.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: sis-dev@sis.apache.org Delivered-To: mailing list commits@sis.apache.org Received: (qmail 95208 invoked by uid 99); 25 Sep 2012 08:29:42 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Sep 2012 08:29:42 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Sep 2012 08:29:38 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id B92DE23889C5 for ; Tue, 25 Sep 2012 08:28:54 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1389753 - in /sis/trunk: sis-build-helper/pom.xml sis-build-helper/src/site/ sis-build-helper/src/site/apt/ sis-build-helper/src/site/apt/index.apt sis-utility/src/main/java/org/apache/sis/resources/package-info.java Date: Tue, 25 Sep 2012 08:28:54 -0000 To: commits@sis.apache.org From: desruisseaux@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20120925082854.B92DE23889C5@eris.apache.org> Author: desruisseaux Date: Tue Sep 25 08:28:53 2012 New Revision: 1389753 URL: http://svn.apache.org/viewvc?rev=1389753&view=rev Log: Added documentation. Added: sis/trunk/sis-build-helper/src/site/ sis/trunk/sis-build-helper/src/site/apt/ sis/trunk/sis-build-helper/src/site/apt/index.apt Modified: sis/trunk/sis-build-helper/pom.xml sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java Modified: sis/trunk/sis-build-helper/pom.xml URL: http://svn.apache.org/viewvc/sis/trunk/sis-build-helper/pom.xml?rev=1389753&r1=1389752&r2=1389753&view=diff ============================================================================== --- sis/trunk/sis-build-helper/pom.xml (original) +++ sis/trunk/sis-build-helper/pom.xml Tue Sep 25 08:28:53 2012 @@ -53,11 +53,14 @@ =========================================================== --> sis-build-helper maven-plugin - Build helper + Apache SIS build helper - Compiles internationalization files. They are Java properties files transformed - into UTF files. Their values are made compliant with the java.text.MessageFormat - syntax, and a set of programmatic constants are generated for the keys. + +Define Maven Mojos and Javadoc taglets for generating resource files + or formatting the Javadoc. While any project could use it, this module + is primarily for internal use by Apache SIS and may change in any + future version. Added: sis/trunk/sis-build-helper/src/site/apt/index.apt URL: http://svn.apache.org/viewvc/sis/trunk/sis-build-helper/src/site/apt/index.apt?rev=1389753&view=auto ============================================================================== --- sis/trunk/sis-build-helper/src/site/apt/index.apt (added) +++ sis/trunk/sis-build-helper/src/site/apt/index.apt Tue Sep 25 08:28:53 2012 @@ -0,0 +1,77 @@ + ------------------------------ + Index + ------------------------------ + +Building Apache SIS + + The <<>> module defines Maven Mojos and Javadoc taglets for generating + resource files or formatting the Javadoc. While any project could use it, this module is + primarily for internal use by Apache SIS and may change in any future version. + + +* Javadoc taglets + + This module provides the following javadoc taglets: + + * <<<@module>>> - replaced in the generated javadoc by a link to the module where the + class is defined. + + * <<<{@section}>>> - an inline taglet for the title of a new section in the javadoc. + + * <<<{@note}>>> - an inline taglet for a remark that readers can safely ignore. + Notes appear in indented paragraphs with a smaller font. + + * <<<{preformat}>>> - an inline taglet for pre-formatted text. The first word inside + the taglet shall be one of <<>>, <<>>, <<>>, <<>>, <<>>, + <<>> or <<>>. + + +* Localized resources compiler + + Localized resources are provided in <<<*.properties>>> files as specified by the + <<>> standard class. However SIS does not use + those resources files directly. Instead <<<*.properties>>> files are transformed + into binary files having the same filename but the <<<.utf>>> extension. + This conversion is done for efficiency, for convenience (the compiler applies + the <<>> rule itself), + and for compile-time safety. + + In addition to generating the <<<*.utf>>> files, the resource compiler may modify + the <<<*.java>>> files having the same name than the resource files. + For example given a set of <<>> files (one for each supported language), + the compiler will generate the corresponding <<>> files, then look for a + <<>> source file. If such source file is found and contains a public static + inner class named <<>>, then the compiler will rewrite the constants declared in that + inner class with the list of keys found in the <<>> files. + + The resource compiler is executed at Maven build time when the <<>> file of a module + contains the following declaration. Note that current implementation looks only for resources + in the <<>> package; all other packages are ignored. + ++----------------------------------------------------- + + + + org.apache.sis + sis-build-helper + ${project.version} + + + + compile-resources + + + + + + ++----------------------------------------------------- + + The resources compilation is part of the build process and does not need to be run explicitly. + However, if necessary the resources compiler can be invoked alone by the following command line + in the module containing the resources to recompile. This is sometime useful for regenerating + the constants in the <<>> inner class. + ++----------------------------------------------------- +mvn org.apache.sis:sis-build-helper:compile-resources ++----------------------------------------------------- Modified: sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java URL: http://svn.apache.org/viewvc/sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java?rev=1389753&r1=1389752&r2=1389753&view=diff ============================================================================== --- sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java (original) +++ sis/trunk/sis-utility/src/main/java/org/apache/sis/resources/package-info.java Tue Sep 25 08:28:53 2012 @@ -16,16 +16,36 @@ */ /** - * Localized resources for SIS. + * Localized resources for SIS. While anyone could use the resources provided in this package, + * those resources are primarily for internal SIS usage and may change in any future version. * - * Do not use! + *

Apache SIS resources are provided in binary files having the "{@code .utf}" extension. + * The resource keys are numeric constants declared in the {@code Keys} static inner classes. + * Values are strings which may optionally have slots for one or more parameters, identified + * by the "{n}" characters sequences where n + * is the parameter number (first parameter is "{0}"). + * If, and only if, a string value has slots for at least one parameter, then:

* - * This package is for internal use by SIS only. Classes in this package - * may change in incompatible ways in any future version without notice. + *
    + *
  • the key name ends with the {@code '_'} character followed by the expected number of parameters;
    • + *
  • the value string will be compliant with the {@link java.text.MessageFormat} syntax.
    • + *
+ * + *

Apache SIS developers can add resources by editing the {@code *.properties} file + * in the source code directory, then run the localized resources compiler provided in the + * sis-build-helper module. + * Developers shall not apply the {@code MessageFormat} rules for using quotes, + * since the resources compiler will apply itself the doubled single quotes when + * necessary. This avoid the unfortunate confusion documented in the warning section of + * {@link java.text.MessageFormat} javadoc.

* * @author Martin Desruisseaux (Geomatys) * @since 0.3 (derived from geotk-1.2) * @version 0.3 * @module + * + * @see java.util.ResourceBundle + * @see java.text.MessageFormat + * @see sis-build-helper module */ package org.apache.sis.resources;