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.
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
developormasterbranches 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.jpgcould be updated withsystem-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-pdftool should produce apdffile 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-pdfonly 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 inpdf.
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.adocPDF output can be generated as well:
asciidoctor-pdf -a allow-uri-read -D ~/temp/8.8.15 -o adminguide-8.8.15.pdf index.adocFor 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/imagesWhen 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.
|
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.adocfile contains version information for the release, including all translations. There should be no locale-specificsettings.adocfiles. -
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
imagesfolder to be used by all locales, except in the case of translated images. -
Each locale may have its own
imagesfolder, 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 Masterimagesfolder, 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
imagesdirset bysettings.adocshould be left as-is, pointing at the Masterimagesfolder.en_us Master Translations +----+ +--------+ | | | | adminguide | | | +---+---------+ | | +----+ | +--------+ | | | | +---+ images | | | | +----+ | +------+------+ +--------+ | | | | | | +--------------+ ja_jp | | | | | +-------------+ | +----+ +---- settings.adoc +--------+ | | | | +-------------------------+ ja_jp | | | | | +---+---------+ | | | en_us sources | ja_jp sources | | +--+- index.adoc +--+- index.adoc +- ... +- ...
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.
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.adocPDF 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_jpVisit 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.
© 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