Giter VIP home page Giter VIP logo

adminguide's Introduction

Zimbra 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

CC BY-SA 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

adminguide's People

Contributors

abyshukla avatar dawoodshaikh avatar gaylebillat avatar gordyt avatar grishick avatar ilyusha avatar jeastman avatar jorgedlcruz avatar mamishoho avatar michaelmedellin avatar mogsdad avatar mss avatar plobbes avatar shardool-gore avatar stefan0xc avatar tmclane avatar ykomiyam avatar zxcine avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.