Add description of the external tool specification files.

doc/api/api.pro

@@ -43,6 +43,7 @@ equals(QMAKE_DIR_SEP, /) {   # unix, mingw+msys
 HELP_FILES     = $$PWD/qtcreator-dev.qdocconf
 HELP_DEP_FILES = $$PWD/qtcreator-api.qdoc \
                  $$PWD/coding-style.qdoc \
+                 $$PWD/external-tool-spec.qdoc \
                  $$PWD/qtcreator-dev.qdoc \
                  $$PWD/qtcreator-dev.qdocconf
 

doc/api/external-tool-spec.qdoc

+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (info@qt.nokia.com)
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+****************************************************************************/
+
+/*!
+    \page external-tool-spec.html
+    \title External Tool Specification Files
+
+    \section1 Description
+
+    File that describes a tool that can be run from the \gui { Tools > External } menu.
+    It specifies the name, the binary to run, what parameters the binary should get
+    and what should happen with the tool's output.
+
+    \section1 File Name
+
+    \c {<yourtoolname>.xml}
+
+    \section1 Location
+
+    User specific tools are located in \c {$HOME/.config/Nokia/qtcreator/externaltools}
+    on Mac and Linux, and in \c {%APPDATA%\Nokia\qtcreator\externaltools} on Windows.
+
+    System wide tools are located in \c {<Qt Creator install>/share/qtcreator/externaltools}
+    on Windows and Linux, and in \c {Qt Creator.app/Contents/Resources/externaltools} on Mac.
+
+    \section1 File Format
+
+    External tool specifications are XML files with the following structure.
+
+    \section2 Main Tag
+
+    The root tag is \c externaltool. It has a mandatory attribute \c id.
+
+    \table
+    \header
+        \o Tag
+        \o Meaning
+    \row
+        \o externaltool
+        \o Root element in a external tool's xml file.
+    \endtable
+    \table
+    \header
+        \o Attribute
+        \o Meaning
+    \row
+        \o id
+        \o This is a string that is used as an identifier for the external tool.
+           There can be no two tools with the same id. Required.
+    \endtable
+
+    \section2 Description Tags
+
+    It is mandatory that you give your tool a description, display name and category.
+    All three can optionally be translated into different languages by adding multiple
+    \c description, \c displayname and \c category tags with different language attributes.
+
+    \table
+    \header
+        \o Tag
+        \o Meaning
+    \row
+        \o description
+        \o Short, one-line description of what the tool is for. Required.
+    \row
+        \o displayname
+        \o Name to show in the menu item for the tool. Required.
+    \row
+        \o category
+        \o Name of the category to show the tool in.
+           This is the name of the sub menu under the \c { Tools > External } menu which
+           will contain this tool. E.g. a value of \c "Text" for the category will
+           put the tool's menu item in the \c { Tools > External > Text } menu. Required.
+    \endtable
+    \table
+    \header
+        \o Attribute
+        \o Meaning
+    \row
+        \o xml:lang
+        \o Language code (e.g. \c "en" or \c "de") of the lanugage that is used for
+           the description, display name, or category. Optional.
+    \endtable
+
+    \section2 Executable Specification Tag
+
+    It is mandatory to add a \c executable tag under the root tag, that specifies what to run,
+    the parameters given to the process, and what to do with the output.
+
+    \table
+    \header
+        \o Tag
+        \o Meaning
+    \row
+        \o executable
+        \o Encloses subtags that specify what to run and which parameters to use. Required.
+    \endtable
+    \table
+    \header
+        \o Attribute
+        \o Meaning
+    \row
+        \o output
+        \o Specifies what to do with the tool's standard output stream.
+           See \l{Output Behavior Flags} below. Defaults to \c ShowInPane. Optional.
+    \row
+        \o error
+        \o Specifies what to do with the tool's standard error stream.
+           See \l{Output Behavior Flags} below. Defaults to \c ShowInPane. Optional.
+    \row
+        \o modifiesdocument
+        \o Spefifies if Qt Creator should expect a change of the current document.
+           If this flag is set, Qt Creator asks for saving the current document
+           before running the tool (if the current document was modified),
+           and silently reloads the current document after the tool has finished.
+           \c "yes" or \c "no" (defaults to \c "no"). Optional.
+    \endtable
+
+    The \c executable tag allows the following subtags, it is only required to specify at least
+    one \c path. All subtags can contain special \l{Qt Creator Variables}.
+
+    \table
+    \header
+        \o Subtag
+        \o Meaning
+    \row
+        \o path
+        \o File path to the executable to run, including the executable's file name.
+           If only the executable name is given without a path, it is looked for in the
+           system's PATH environment variable. Can be specified multiple times,
+           Qt Creator then tries to resolve them in the given order and runs the first
+           one that is found. Required.
+    \row
+        \o arguments
+        \o Command line arguments for the executable. This string is in the form
+           (with respect to e.g. quoting and argument splitting) how it would
+           be specified on the command line of the platform the tool runs on. Optional.
+    \row
+        \o workingdirectory
+        \o The working directory that should be set for the executable. Optional.
+    \row
+        \o input
+        \o A potentially multiline string that is passed to the tool via standard input stream.
+    \endtable
+
+    \section1 Example
+
+    \code
+<?xml version="1.0" encoding="UTF-8"?>
+<externaltool id="sort">
+    <description>Sorts the selected text</description>
+    <description xml:lang="de">Sortiert den ausgewählten Text</description>
+    <displayname>Sort Selection</displayname>
+    <displayname xml:lang="de">Auswahl Sortieren</displayname>
+    <category>Text</category>
+    <category xml:lang="de">Text</category>
+    <executable output="replaceselection" error="ignore">
+        <path>sort</path>
+        <input>%{CurrentDocument:Selection}</input>
+        <workingdirectory>%{CurrentDocument:Path}</workingdirectory>
+    </executable>
+</externaltool>
+    \endcode
+*/

doc/api/qtcreator-dev.qdoc

@@ -243,6 +243,7 @@
                 \o  \l{External Tool Specification Files}
                 \o  \l{Custom Wizard Specification Files}
                 \o  \l{http://kate-editor.org/2005/03/24/writing-a-syntax-highlighting-file/}{Highlight Definition Files}
+                \o  \l{Qt Creator Variables}
                 \o  \l{User Interface Text Guidelines}
                 \o  \l{Qt Creator Coding Rules}
                 \o  \l{Qt Creator API Reference}