Doc: sharing project settings

Change-Id: Ibd1b35244346a9c868fe0a2b011085c234a6c4e1
Reviewed-by: Leandro T. C. Melo <leandro.melo@nokia.com>

1 files changed, 91 insertions, 0 deletions

diff --git a/doc/src/projects/creator-projects-settings-sharing.qdoc b/doc/src/projects/creator-projects-settings-sharing.qdoc
new file mode 100644
index 0000000000..d74446e568
--- /dev/null
+++ b/doc/src/projects/creator-projects-settings-sharing.qdoc
@@ -0,0 +1,91 @@
+/****************************************************************************
+**
+** 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 info@qt.nokia.com.
+**
+****************************************************************************/
+
+// **********************************************************************
+// NOTE: the sections are not ordered by their logical order to avoid
+// reshuffling the file each time the index order changes (i.e., often).
+// Run the fixnavi.pl script to adjust the links to the index order.
+// **********************************************************************
+
+/*!
+    \contentspage index.html
+    \previouspage creator-build-dependencies.html
+    \page creator-sharing-project-settings.html
+    \nextpage creator-developing-meego.html
+
+    \title Sharing Project Settings
+
+    \QC stores user-specific project settings in a .pro.user file. You can
+    share these settings between several projects as a .pro.shared file. It
+    has the same XML structure as a .pro.user file, but only contains the
+    settings to share.
+
+    \section1 Creating Shared Settings File
+
+    The easiest way to create a .pro.shared file is to copy settings from the
+    .pro.user file. Typically, you would share some of the values in the
+    \c ProjectExplorer.Project.EditorSettings section.
+
+    \note You must always specify the
+    \c ProjectExplorer.Project.Updater.FileVersion variable and use the same
+    value for it as in the .pro.user file.
+
+    You can then deliver the .pro.shared file to other developers or copy it to
+    other development PCs.
+
+    The following is an example of a pro.shared file:
+
+    \code
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE QtCreatorProject>
+    <qtcreator>
+        <data>
+            <variable>ProjectExplorer.Project.EditorSettings</variable>
+            <valuemap type="QVariantMap">
+                <value type="bool" key="EditorConfiguration.SpacesForTabs">true</value>
+                <value type="bool" key="EditorConfiguration.AutoSpacesForTabs">false</value>
+                <value type="int" key="EditorConfiguration.TabSize">14</value>
+                <value type="int" key="EditorConfiguration.IndentSize">4</value>
+            </valuemap>
+            </data>
+        <data>
+            <variable>ProjectExplorer.Project.Updater.FileVersion</variable>
+            <value type="int">10</value>
+        </data>
+    </qtcreator>
+    \endcode
+
+    \section1 Updating Shared Settings
+
+    The first time \QC loads the project after you added pro.shared settings,
+    it overwrites the pro.user settings with them. If you open the project for
+    the first time and \QC has not created a .pro.user file, the settings in the
+    .pro.shared file take effect immediately.
+
+    If you receive a .pro.shared file and do not want to use a particular
+    setting in it, you can change it. \QC marks it a \e sticky setting. The next
+    time you open a project, the setting is not updated. \QC tracks sticky
+    settings in the .pro.user file and removes the mark if the values in the
+    pro.user and pro.shared files eventually become identical. This is to avoid
+    a permanent sticky setting that was created just because you wanted to try
+    something out.
+
+*/