Zimbra Administration Guide

This repository contains the code necessary to build the Zimbra Administration Guide.

This guide is for system administrators responsible for installing, maintaining, and supporting the server deployment of Zimbra.

Images in the Documentation

Any images to be included in the documentation must have their source files stored in the images folder, with the following guidelines:

• Assign a meaningful name: The name of an image should indicate what the content of the image is.

• Do not replace images: Once an image source file has been merged to develop or master branches of the repository, the image is considered immutable. If an update or new version of an image is required, then it should be added as a new image with a version number in its name, so it is clear for translators that images have changed. For example, system-overview.jpg could be updated with system-overview-v2.jpg, with corresponding changes to the file(s) that include the image so they include the new version.

• Images must render in html & pdf output: The asciidoctor-pdf tool should produce a pdf file with your image intact. If an image does not render, your PR will be rejected.

• Take care with SVG fonts: If you’re using fonts in your SVG, and you want those fonts to be preserved, those fonts must be defined in the Asciidoctor PDF theme file.

• Use "pure" SVGs: The SVG renderrer used by asciidoctor-pdf only supports "pure" SVGs, not the SVG/HTML/CSS hybrid that are sometimes targeted for web viewing. If your image editor supports export of SVG files without the additional info, use that. Test your images - a hybrid SVG will render as a black rectangle in pdf.

Building the Documentation

The Zimbra Administration Guide is written using AsciiDoc. Specifically, it is intended to be processed with Asciidoctor.

As a prerequisite to building the documentation, you will need to have already installed and configured Asciidoctor. Check the Installation Quick Start in the Asciidoctor User Manual for information on how to get started.

Once you have Asciidoctor installed and working, you can build the documentation into HTML files like so:

asciidoctor -b html5 -D ~/temp/8.8.15 -o adminguide-8.8.15.html index.adoc

PDF output can be generated as well:

asciidoctor-pdf -a allow-uri-read -D ~/temp/8.8.15 -o adminguide-8.8.15.pdf index.adoc

For Zimbra 9 you need to pass a variable to asciidoctor or asciidoctor-pdf, by including -a z9. This will control variable substitutions in settings.adoc and throughout much of the documentation.

These commands assume you have a "temp" directory to receive the asciidoctor output, and are generating output for version 8.8.15…​ adjust according to your situation. Each section of the document is contained in its own file. You may use the index.adoc file to generate the entire document.

To accompany the HTML output, the images/ folder must also be copied to the output destination:

cp -r ./images ~/temp/8.8.15/images

When publishing the output (gh-pages branch) the "latest" link needs to be updated to point at the new version:

ln -nsf 8.8.15 latest

Important

Windows users need to launch Command Prompt with administrator privileges and use the command mklink.

mklink /D latest 8.8.15

Tip	The above command does not overwrite the existing symlink, hence first rename it.

Finally, the index.html file in the root folder needs to be updated to include appropriate links for the new version’s documents. Use your favorite text editor to complete this task before committing and pushing the updated gh-pages branch to the repo.

Localization and translations

Source organization

Note	The Best Practice for managing translations would be to replace translatable strings in the English adoc files with localized strings from language-specific po files. Until that is in place, translated adoc source and images are stored in locale-specific folders.

The source repo structure is shown below, and has the following characteristics:

• The top level folder, adminguide, contains the US English (en_us) documentation source, which is informally designated as the "Master" documentation. This is where all primary information is authored and updated.

• The Master settings.adoc file contains version information for the release, including all translations. There should be no locale-specific settings.adoc files.

• Each locale has its own folder under the "Master", named using the ISO-639 Language Code + ISO-3166 Country Code to name it. For example, the Japanese translation appears under ja_jp.

• There is a Master images folder to be used by all locales, except in the case of translated images.

• Each locale may have its own images folder, named using the Language Code + Country Code just like the source folder. Images take up a lot of space, so translations must not copy all the ones in the Master images folder, rather they should be used as-is where feasible.

• If any images require translation for a locale, then the translated image should be added to the locale’s images folder. Where translated images are to be embedded, the path to the image will need to explicitly indicate the locale, e.g., image::ja_jp/images/<image-name.jpg>.

• The value for imagesdir set by settings.adoc should be left as-is, pointing at the Master images folder.

   en_us Master                     Translations
           +----+
  +--------+    |
  |             |
  | adminguide  |
  |             |
  +---+---------+
      |
      |            +----+
      |   +--------+    |
      |   |             |
      +---+   images    |
      |   |             |                +----+
      |   +------+------+       +--------+    |
      |          |              |             |
      |          +--------------+    ja_jp    |
      |                         |             |
      |                         +-------------+
      |                                  +----+
      +---- settings.adoc       +--------+    |
      |                         |             |
      +-------------------------+    ja_jp    |
      |                         |             |
      |                         +---+---------+
      |                             |
      |     en_us sources           |     ja_jp sources
      |                             |
      +--+- index.adoc              +--+- index.adoc
         +-    ...                     +-    ...

Published doc organization

The documentation output is "published" by being pushed to the gh-pages branch, which is automatically hosted as a public website by GitHub.io. Each published release-version of the Zimbra Administration Guide appears in its own release folder.

Translations of documentation are published under the release-version folders, in a structure that is similar to the source organization. For example, consider two versions of the Zimbra Administration Guide with Japanese translations:

         +----+
+--------+    |
|             |
|      /      |
|             |
+--+----------+
   |                     en_us Master                     Translations
   +--+- index.html              +----+
   |  +- style.css      +--------+    |
   |                    |             |
   +--------------------+   8.8.12    |
   |                    |             |
   |                    +---+---------+
   |                        |
   |                        |            +----+
   |                        |   +--------+    |
   |                        |   |             |
   |                        +---+   images    |
   |                        |   |             |                +----+
   |                        |   +-----+-------+       +--------+    |
   |                        |         |               |             |
   |                        |         +---------------+    ja_jp    |
   |                        |                         |             |
   |                        |                         +-------------+
   |                        |
   |                        |                                  +----+
   |                        |                         +--------+    |
   |                        |                         |             |
   |                        +-------------------------+    ja_jp    |
   |                        |                         |             |
   |                        |                         +-------------+
   |                        |                             |
   |                        |     en_us docs              |     ja_jp docs
   |                        |                             |
   |                        +--+- adminguide-8.8.12.html  +--+- adminguide-8.8.12-ja_jp.html
   |                           +- adminguide-8.8.12.pdf      +- adminguide-8.8.12-ja_jp.pdf
   |
   |                             +----+
   |                    +--------+    |
   |                    |             |
   +--------------------+   8.8.15    |
                        |             |
                        +---+---------+
                            |
                            |            +----+
                            |   +--------+    |
                            |   |             |
                            +---+   images    |
                            |   |             |                +----+
                            |   +-----+-------+       +--------+    |
                            |         |               |             |
                            |         +---------------+    ja_jp    |
                            |                         |             |
                            |                         +-------------+
                            |
                            |                                  +----+
                            |                         +--------+    |
                            |                         |             |
                            +-------------------------+    ja_jp    |
                            |                         |             |
                            |                         +-------------+
                            |                             |
                            |     en_us docs              |     ja_jp docs
                            |                             |
                            +--+- adminguide-8.8.15.html  +--+- adminguide-8.8.15-ja_jp.html
                               +- adminguide-8.8.15.pdf      +- adminguide-8.8.15-ja_jp.pdf

This structure ensures that the relative path to images is the same in both source and published folders, yet the published versions for each release are collected together.

Building translations

Here is an example of building the Japanese documentation:

asciidoctor -b html5 -D ~/temp/8.8.15/ja_jp -o adminguide-8.8.15-ja_jp.html ja_jp/index.adoc

PDF output can be generated as well:

asciidoctor-pdf -a allow-uri-read -D ~/temp/8.8.15/ja_jp -o adminguide-8.8.15-ja_jp.pdf index.adoc

Note	The asciidoctor-pdf tool does not support all languages yet, so the PDF output is optional.

The localized images/ folder must also be copied to the output destination:

cp -r ./images/ja_jp ~/temp/8.8.15/images/ja_jp

Additional Information

Visit www.zimbra.com to join the community and to be a part of building the best open source messaging solution. We appreciate your feedback and suggestions.

Join the Zimbra Forums, to participate and learn more about Zimbra.

For additional product information check the Zimbra Wiki.

License

Synacor, Inc., 2019

© 2016-2019 by Synacor, Inc.

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License unless another license agreement between you and Synacor, Inc. provides otherwise. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/4.0 or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

Synacor, Inc.
40 La Riviere Drive, Suite 300
Buffalo, New York 14202

https://www.synacor.com