Merge pull request #744 from zanata/update-docs

Update docs
zanata · Mar 25, 2015 · a330cb1 · a330cb1
2 parents 333016f + c002cb3
commit a330cb1
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 20 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -1,31 +1,22 @@
 Zanata Server
 =============
-
-TBD
-
-Features
---------
-
-- TBD
+Please visit [About|Zanata](http://zanata.org/about/)
 
 Installation
 ------------
 
-<!-- For installation instructions please see the [Installation Section](installation) -->
+[Installation section](configuration/installation.md)
 
 Contribute
 ----------
 
-- Issue Tracker: http://bugzilla.redhat.com
-- Source Code: github.com/zanata/zanata-server
+- [Issue Tracker](http://bugzilla.redhat.com/buglist.cgi?product=Zanata)
+- [Source Code on GitHub](http://github.com/zanata)
 
 Support
 -------
-
-If you are having issues, please let us know.
-We have a mailing list located at: zanata-users@redhat.com
+For help and support options, see [Help|Zanata](http://zanata.org/help/)
 
 License
 -------
-
-<!-- The project is licensed under the BSD license. -->
+Zanata is Free software, licensed under the [LGPL](http://www.gnu.org/licenses/lgpl-2.1.html).
diff --git a/docs/user-guide/client-command-hook.md b/docs/user-guide/client-command-hook.md
@@ -0,0 +1,38 @@
+Custom commands can be specified in zanata.xml. Custom commands can be almost any command that can run on the command line, and can be configured to run before or after a Zanata client command. This feature was added in version 3.3.0 of the CLI client and the Maven Plugin, and cannot be used in earlier versions.
+
+To specify one or more custom commands:
+
+ 1. Add a `<hooks>` element in zanata.xml within the `<config>` element.
+ 1. For each Zanata command that will have custom commands attached, add a `<hook>` element that specifies the command as an attribute.
+ 1. For each custom command to run before a Zanata command, add a `<before>` element with the command as its body.
+ 1. For each custom command to run after a Zanata command, add an `<after>` element with the command as its body.
+
+For example, the following elements within the top-level <config> element will generate a .pot file from a man page before push, clean up the generated file after push, and will generate a translated German man page after pull then remove all downloaded .po files.
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<config xmlns="http://zanata.org/namespace/config/">
+
+...
+
+  <hooks>
+    <hook command="push">
+        <before>po4a-gettextize -f man -m manpage.1 -p manpage.pot</before>
+        <after>rm -f manpage.pot</after>
+    </hook>
+    <hook command="pull">
+        <after>po4a-translate -f man -m manpage.1 -p trans/de/manpage.po -l manpage.de.1 --keep 1</after>
+        <after>rm -rf trans</after>
+    </hook>
+  </hooks>
+
+...
+
+</config>
+```
+
+Multiple commands of the same type (i.e. "before" or "after") within a hook will be run in the order that they are specified in zanata.xml. e.g. when running pull with the above config, po4a will always run before rm. If any of these commands fails, the whole operation is aborted. e.g. when running push, if po4a fails then push and rm will not be run, and if push fails then rm will not be run.
+
+Note that some commands (such as 'cd') do not work as custom commands. The ranges of commands that work and that do not work as custom commands have not yet been thoroughly investigated.
+
+The return value of each custom command is displayed after the command is run. A return value of 0 usually indicates success, and any other number usually indicates an error. Console output from custom commands is not yet displayed or logged.
diff --git a/docs/user-guide/client-configuration.md b/docs/user-guide/client-configuration.md
@@ -1,5 +1,3 @@
-# Common configuration files for Flies clients
-
 # Introduction
 
 In general, Zanata clients should get their configuration from user config, project config and command line args (or similar).
@@ -84,6 +82,4 @@ URLs in project configuration should be matched against the [servers] defined in
 
 ## Command line or other mechanism (eg Maven properties)
 
-The client should also provide the ability to override user/project configuration values, perhaps with command line arguments or GUI options, etc.
-
-See ZanataMavenIntegration for the Maven configuration properties and example pom.xml.
+The client should also provide the ability to override user/project configuration values, perhaps with command line arguments or GUI options, etc.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -27,6 +27,7 @@ pages:
 - ['user-guide/keyboard-shortcuts.md', 'User Guide', 'Keyboard Shortcuts']
 - ['user-guide/project-types.md', 'User Guide', 'Project Types']
 - ['user-guide/client-configuration.md', 'User Guide', 'Client Configuration']
+- ['user-guide/client-command-hook.md', 'User Guide', 'Client Command Hook']
 - ['user-guide/user-profile.md', 'User Guide', 'User Profile Page']
 - ['user-guide/merge-translations.md', 'User Guide', 'Merge translations']
 ## Project