mazz.i18n.ant
Class Helpdoc

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      mazz.i18n.ant.Helpdoc

public class Helpdoc
extends org.apache.tools.ant.ProjectComponent

Inner element of the I18NAntTask ant task that defines how to generate the help documentation for all the I18N messages. Each I18N message will correspond to a single help document item (the item's text is defined by a template containing replacement strings). For each resource bundle that gets generated, a corresponding help document will be created in the output directory. Example usage:

 <helpdoc
     outputdir="${build.dir}/help"
     append="false"
     outputfileext=".html"
     templateitem="${template.dir}/my-help-template.html"
     templateheader="${template.dir}/my-help-header.html"
     templatefooter="${template.dir}/my-help-footer.html"
     templatecharset="UTF-8" />
 

The only required attribute is "outputdir". See the setter methods in this class for a description of these attributes.

Version:

$Revision$

Author:

John Mazzitelli

Field Summary

static java.lang.String	TEMPLATE_BUNDLE The template replacement string for the resource bundle name.
static java.lang.String	TEMPLATE_HELP The template replacement string for the message help text.
static java.lang.String	TEMPLATE_KEY The template replacement string for the resource bundle key.
static java.lang.String	TEMPLATE_MESSAGE The template replacement string for the resource bundle value.

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Constructor Summary

Helpdoc()
No-arg constructor for Helpdoc required by the ANT framework.

Method Summary

boolean	getAppend() If true, the help documentation will be appended to the help document files located in the output directory.
boolean	getHelpmessagesonly() If true, only those I18N Messages that have help descriptions associated with them will have their help doc items output; others will be ignored.
java.lang.String	getOutputdir() Returns the output directory where the contents of the help documents will be written.
java.lang.String	getOutputfileext() Returns the file extension that will be appended to the end of all help doc output files.
java.lang.String	getTemplatecharset() Returns the charset that all the template files' contents can be decoded as.
java.lang.String	getTemplatefooter() Returns the template footer file whose contents define what the end of each help document will look like.
java.lang.String	getTemplatefooterContents() Returns the contents of the template footer file.
java.lang.String	getTemplateheader() Returns the template header file whose contents define what the beginning of each help document will look like.
java.lang.String	getTemplateheaderContents() Returns the contents of the template header file.
java.lang.String	getTemplateitem() Returns the template item file whose contents define what each item of a help document will look like.
java.lang.String	getTemplateitemContents() Returns the contents of the template item file.
void	setAppend(boolean append) If true, the help documentation will be appended to the help document files located in the output directory.
void	setHelpmessagesonly(boolean helpMessagesOnly) If true, only those I18N Messages that have help descriptions associated with them will have their help doc items output; others will be ignored.
void	setOutputdir(java.lang.String out) The output directory where the contents of the help documents will be written.
void	setOutputfileext(java.lang.String ext) Sets the file extension that will be appended to the end of all help doc output files.
void	setTemplatecharset(java.lang.String charset) Sets the charset that all the template files' contents can be decoded as.
void	setTemplatefooter(java.lang.String template) Sets the template footer file whose contents define what the end of each help document will look like.
void	setTemplateheader(java.lang.String template) Sets the template header file whose contents define what the beginning of each help document will look like.
void	setTemplateitem(java.lang.String template) The template item file whose contents define what each item of a help document will look like.
java.lang.String	toString()

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, log, log, setProject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TEMPLATE_BUNDLE

public static final java.lang.String TEMPLATE_BUNDLE

The template replacement string for the resource bundle name. When this replacement string is found in the template contents, it will be replaced with the resource bundle base name.

See Also:

Constant Field Values

TEMPLATE_KEY

public static final java.lang.String TEMPLATE_KEY

The template replacement string for the resource bundle key. When this replacement string is found in the template contents, it will be replaced with the resource bundle key.

See Also:

Constant Field Values

TEMPLATE_MESSAGE

public static final java.lang.String TEMPLATE_MESSAGE

The template replacement string for the resource bundle value. When this replacement string is found in the template contents, it will be replaced with the resource bundle value string (i.e. the actual message text).

See Also:

Constant Field Values

TEMPLATE_HELP

public static final java.lang.String TEMPLATE_HELP

The template replacement string for the message help text. When this replacement string is found in the template contents, it will be replaced with the help description for the message (if one exists).

See Also:

Constant Field Values

Constructor Detail

Helpdoc

public Helpdoc()

No-arg constructor for Helpdoc required by the ANT framework.

Method Detail

getOutputdir

public java.lang.String getOutputdir()

Returns the output directory where the contents of the help documents will be written.

Returns:

output directory path

setOutputdir

public void setOutputdir(java.lang.String out)

The output directory where the contents of the help documents will be written.

Parameters:

out - output directory path

getAppend

public boolean getAppend()

If true, the help documentation will be appended to the help document files located in the output directory. If false, and an output file already exists, it will be overwritten. The default is false.

Be careful if you use true here; if you do, you probably will want to define empty header and footer template files since appending to a help document will append to the very end of the file, which is after the header and footer contents have been output (which means this may end up generating a badly formatted help document).

Returns:

append

setAppend

public void setAppend(boolean append)

If true, the help documentation will be appended to the help document files located in the output directory. If false, and an output file already exists, it will be overwritten.

Be careful if you use true here; if you do, you probably will want to define empty header and footer template files since appending to a help document will append to the very end of the file, which is after the header and footer contents have been output (which means this may end up generating a badly formatted help document).

Parameters:

append -

getTemplateitem

public java.lang.String getTemplateitem()

Returns the template item file whose contents define what each item of a help document will look like.

Returns:

path to the file containing the help doc item template

setTemplateitem

public void setTemplateitem(java.lang.String template)

The template item file whose contents define what each item of a help document will look like.

Parameters:

template - the path to the file containing the help doc item template

getTemplateheader

public java.lang.String getTemplateheader()

Returns the template header file whose contents define what the beginning of each help document will look like. There is one help document for each resource bundle generated.

Returns:

path to the file containing the help doc header template

setTemplateheader

public void setTemplateheader(java.lang.String template)

Sets the template header file whose contents define what the beginning of each help document will look like. There is one help document for each resource bundle generated.

Parameters:

template - the path to the file containing the help doc header template

getTemplatefooter

public java.lang.String getTemplatefooter()

Returns the template footer file whose contents define what the end of each help document will look like. There is one help document for each resource bundle generated.

Returns:

path to the file containing the help doc footer template

setTemplatefooter

public void setTemplatefooter(java.lang.String template)

Sets the template footer file whose contents define what the end of each help document will look like. There is one help document for each resource bundle generated.

Parameters:

template - the path to the file containing the help doc footer template

getTemplatecharset

public java.lang.String getTemplatecharset()

Returns the charset that all the template files' contents can be decoded as. If null, the default charset should be used.

Returns:

the template file charset (item, header and footer)

setTemplatecharset

public void setTemplatecharset(java.lang.String charset)

Sets the charset that all the template files' contents can be decoded as. If null, the default charset is assumed.

Parameters:

charset - the charset of the template files (item, header and footer)

getOutputfileext

public java.lang.String getOutputfileext()

Returns the file extension that will be appended to the end of all help doc output files. An example would be ".txt" or ".html". If this was never set, the default is ".html".

Returns:

the output file extension

setOutputfileext

public void setOutputfileext(java.lang.String ext)

Sets the file extension that will be appended to the end of all help doc output files. An example would be ".txt" or ".html". The default is ".html".

Parameters:

ext - the file extension for all output files

getHelpmessagesonly

public boolean getHelpmessagesonly()

If true, only those I18N Messages that have help descriptions associated with them will have their help doc items output; others will be ignored. If false, all messages will have help doc items output for them.

Returns:

flag

setHelpmessagesonly

public void setHelpmessagesonly(boolean helpMessagesOnly)

If true, only those I18N Messages that have help descriptions associated with them will have their help doc items output; others will be ignored. If false, all messages will have help doc items output for them.

Parameters:

helpMessagesOnly -

getTemplateitemContents

public java.lang.String getTemplateitemContents()
                                         throws java.lang.Exception

Returns the contents of the template item file. If the template item file was not specified, a default template will be returned.

Returns:

contents of the template item file

Throws:

java.lang.Exception - if failed to read the file

getTemplateheaderContents

public java.lang.String getTemplateheaderContents()
                                           throws java.lang.Exception

Returns the contents of the template header file. If the template header file was not specified, a default template will be returned.

Returns:

contents of the template header file

Throws:

java.lang.Exception - if failed to read the file

getTemplatefooterContents

public java.lang.String getTemplatefooterContents()
                                           throws java.lang.Exception

Returns the contents of the template footer file. If the template footer file was not specified, a default template will be returned.

Returns:

contents of the template footer file

Throws:

java.lang.Exception - if failed to read the file

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()