blob: 2a4ec11bd853d8b5215bc6255bbda7b61ca421ba [file] [log] [blame]
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Apache Traffic Server 6.2\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2016-06-30 14:07+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.2.0\n"
#: ../../../developer-guide/documentation/plugins.en.rst:23
msgid "Documenting Plugins"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:25
msgid ""
"Plugins can provide tremendously useful functionality for users of |TS|, "
"but it does them little good if there are no instructions on how to use the "
"plugins properly. In the interest of encouraging useful documentation on "
"all the features available to those deploying |TS| in their infrastructure, "
"this section lays out a series of guidelines and offers a basic template "
"for adding new entries to the :ref:`admin-plugins` chapter of the :ref:"
"`admin-guide`."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:33
msgid "Structure"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:35
msgid ""
"Ideally, every plugin will provide documentation covering the following "
"general topics (preferably in top-level sections named to match):"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:39
msgid "Introduction"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:41
msgid ""
"A brief section in which the plugin's core functionality is explained in a "
"quickly digestable paragraph or two. For the sake of brevity, this section "
"should omit discussion of configuration details in favor of providing a "
"more 10,000 foot view of the plugin features."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:47
msgid "Purpose"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:49
msgid ""
"Why would someone want to use this particular plugin? What problems does it "
"solve, or what features not attainable otherwise (through core "
"functionality or other plugins) does it provide to an administrator or "
"user? While not exactly a product pitch, this is the section in which the "
"case for using the plugin at all should be made."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:56
msgid "Dependencies"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:58
msgid ""
"If the plugin has external dependencies, they should be listed in full, "
"with the exception of items already required by a bare-bones |TS| build. If "
"the plugin has no unusual or non-standard dependencies, this section may be "
"safely omitted."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:63
msgid ""
"For example, there is no need to list a C++ compiler as a requirement, but "
"if the plugin requires OpenCL and a specific brand of GPU expansion card to "
"perform some wacky image transformations on cached objects - that really "
"should be disclosed."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:68
msgid ""
"If any of the dependencies are optional, that should be noted as well as "
"the functionality that may be missing should the dependency not be present."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:72
msgid "Installation"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:74
msgid ""
"Detailed instructions on how to install the plugin if it is not built by "
"default with |TS| or requires any additional libraries, services, or "
"applications outside of |TS| to be present."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:78
msgid ""
"If the plugin is marked stable and included by default in |TS| builds, then "
"it may not be necessary to include any installation steps beyond noting "
"that it is part of the default |TS|."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:83
msgid "Configuration"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:85
msgid ""
"Detailed instructions on how and where to provide configuration data for "
"the plugin's features. It is important to use |RST| references for all "
"mentions of |TS| configuration variables, as well as their containing "
"configuration files."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:89
msgid ""
"If configurations are generated by scripts included with the plugin source "
"code, those scripts should be mentioned and their usage should be shown."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:93
msgid "Caveats (or Limitations)"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:95
msgid ""
"Notes about any peculiarities with the plugin, incompatibilities or strange "
"behaviors when used in conjunction with other features, or special "
"considerations for its deployment that might affect an administrator's use "
"of the plugin or their infrastructure's architecture."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:100
msgid ""
"If the plugin contains known limitations (perhaps it only works with some "
"protocols, can understand only some media types, or is especially non-"
"performant under specific configurations) they should be noted. If "
"possible, workarounds for these limitations should be suggested, or if none "
"are available that should be noted."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:107
msgid "Examples"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:109
msgid ""
"Every plugin should aim to have at least one, complete example of its usage "
"beginning with its basic installation, showing a complete (and ideally "
"working) configuration, as well as sample output from |TS| in which the "
"plugin's effects may be observed."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:115
msgid "Further Reading"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:117
msgid ""
"Consolidated list of references to outside materials and documents which "
"may be relevant to the plugin, such as RFCs and white papers. If the plugin "
"is related to external projects, or has been the subject of benchmarks or "
"articles, those may be useful to list as well."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:123
msgid "Additional Sections"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:125
msgid ""
"Not all plugins will fit perfectly within that list of sections. Some may "
"require additional details, or such extended discussion that it is best to "
"break the plugin's documentation down a bit further. In general, it is "
"recommended to place these additional documentation sections in between "
"*Configuration* and *Caveats* or *Limitations*."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:131
msgid ""
"This ordering permits a quick scanning of the plugin's purpose, basic "
"method of installation, and initial overview of its configuration before "
"becoming mired down in dissertation length details of every possible "
"configuration, warning, and trade-off that may affect deployments."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:136
msgid ""
"In cases where the array of configuration possibilities is extensive, it is "
"recommended that the initial *Configuration* section describe the most "
"common configuration scenario(s), while noting that there are many other "
"possibilities that will be covered in the sections that follow. This, it is "
"hoped, will get the usual case out of the way quickly for most |TS| "
"administrators while limiting the paralysis of choice they may face "
"otherwise."
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:144
msgid "Documentation Template"
msgstr ""
#: ../../../developer-guide/documentation/plugins.en.rst:146
msgid ""
"For the convenience of plugin developers, this manual includes a :ref:"
"`plugin documentation template <developer-doc-plugin-template>` which you "
"may use as a base. The template includes placeholders, with markup, for "
"common features of the documentation which may be relevant for your plugin. "
"Developers are very strongly encouraged to use this template whenever "
"possible, as a means of producing and maintaining a consistent format for "
"plugin documentation."
msgstr ""