From 255cc2c1a353e843aa95ee5a00e6136b949e76b0 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 8 Jul 2014 12:01:03 +0200 Subject: Doc: add example documentation Add initial topic skeletons. The contents will be modified in subsequent patches. Change-Id: I33ca4180c7070d5ae2ca20a59f75608289d76344 Reviewed-by: Jerome Pasion --- .../installerfw-examples-configuring.qdocinc | 22 +++++++++ .../installerfw-examples-generating.qdocinc | 5 ++ .../installerfw-examples-packaging.qdocinc | 15 ++++++ doc/installerfw-examples.qdoc | 33 +++++++++++++ doc/installerfw.qdoc | 1 + doc/installerfw.qdocconf | 7 +-- .../changeuserinterface/changeuserinterface.pro | 1 + examples/componenterror/componenterror.pro | 1 + examples/doc/changeuserinterface.qdoc | 57 ++++++++++++++++++++++ examples/doc/componenterror.qdoc | 40 +++++++++++++++ examples/doc/dynamicpage.qdoc | 40 +++++++++++++++ examples/doc/modifyextract.qdoc | 40 +++++++++++++++ examples/doc/openreadme.qdoc | 41 ++++++++++++++++ examples/doc/quit_installer.qdoc | 40 +++++++++++++++ examples/doc/registerfileextension.qdoc | 40 +++++++++++++++ examples/doc/startmenu.qdoc | 40 +++++++++++++++ examples/dynamicpage/dynamicpage.pro | 1 + examples/licenseagreement/licenseagreement.pro | 1 + examples/modifyextract/modifyextract.pro | 1 + examples/openreadme/openreadme.pro | 1 + examples/quit_installer/quit_installer.pro | 1 + .../registerfileextension.pro | 1 + examples/startmenu/startmenu.pro | 1 + 23 files changed, 427 insertions(+), 3 deletions(-) create mode 100644 doc/includes/installerfw-examples-configuring.qdocinc create mode 100644 doc/includes/installerfw-examples-generating.qdocinc create mode 100644 doc/includes/installerfw-examples-packaging.qdocinc create mode 100644 doc/installerfw-examples.qdoc create mode 100644 examples/changeuserinterface/changeuserinterface.pro create mode 100644 examples/componenterror/componenterror.pro create mode 100644 examples/doc/changeuserinterface.qdoc create mode 100644 examples/doc/componenterror.qdoc create mode 100644 examples/doc/dynamicpage.qdoc create mode 100644 examples/doc/modifyextract.qdoc create mode 100644 examples/doc/openreadme.qdoc create mode 100644 examples/doc/quit_installer.qdoc create mode 100644 examples/doc/registerfileextension.qdoc create mode 100644 examples/doc/startmenu.qdoc create mode 100644 examples/dynamicpage/dynamicpage.pro create mode 100644 examples/licenseagreement/licenseagreement.pro create mode 100644 examples/modifyextract/modifyextract.pro create mode 100644 examples/openreadme/openreadme.pro create mode 100644 examples/quit_installer/quit_installer.pro create mode 100644 examples/registerfileextension/registerfileextension.pro create mode 100644 examples/startmenu/startmenu.pro diff --git a/doc/includes/installerfw-examples-configuring.qdocinc b/doc/includes/installerfw-examples-configuring.qdocinc new file mode 100644 index 000000000..681e3b9d7 --- /dev/null +++ b/doc/includes/installerfw-examples-configuring.qdocinc @@ -0,0 +1,22 @@ + \section1 Configuring the Example Installer + + The installer configuration file, config.xml, in the \c config directory + specifies the text and default values used in the installer: + + \list + \li The \c section specifies the application name that is added + to the page name and introduction text. + \li The \c section specifies the version number of the + repository format, and must be set to \c 1.0.0. + \li The \c section specifies the installer name displayed on the + title bar. + \li The \c <Publisher> section specifies the publisher of the software + (as shown in the Windows Control Panel, for example). + \li The \c <StartMenuDir> section specifies the name of the default + program group for the product in the Windows \gui Start menu. + \li The \c <TargetDir> section specifies that the default target + directory displayed to users is \c InstallationDirectory in the home + directory of the current user (because the predefined variable + \c @HomeDir@ is used as a part of the value). For more information, + see \l{Predefined Variables}. + \endlist diff --git a/doc/includes/installerfw-examples-generating.qdocinc b/doc/includes/installerfw-examples-generating.qdocinc new file mode 100644 index 000000000..e019bd788 --- /dev/null +++ b/doc/includes/installerfw-examples-generating.qdocinc @@ -0,0 +1,5 @@ + \section1 Generating the Example Installer + + \code + binarycreator --offline-only -c config/config.xml -p packages installer + \endcode diff --git a/doc/includes/installerfw-examples-packaging.qdocinc b/doc/includes/installerfw-examples-packaging.qdocinc new file mode 100644 index 000000000..ec7e82b29 --- /dev/null +++ b/doc/includes/installerfw-examples-packaging.qdocinc @@ -0,0 +1,15 @@ + \section1 Creating the Example Package Information File + + The installer package information file, package.xml, in the \c meta + directory specifies the components that are available for installation: + + \list + \li The \c <DisplayName> section specifies the human-readable name of + the component. + \li The \c <Description> section specifies the human-readable + description of the component. + \li The \c <ReleaseDate> section specifies the date when this component + version was released. + \li The \c <Script> section specifies the file name of the JavaScript + file that is loaded. + \endlist diff --git a/doc/installerfw-examples.qdoc b/doc/installerfw-examples.qdoc new file mode 100644 index 000000000..2c6795b0f --- /dev/null +++ b/doc/installerfw-examples.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group qtifwexamples + \title Qt Installer Framework Examples + \brief Illustrate how to customize installers. + +*/ diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc index 9842c7eb8..9b23c171d 100644 --- a/doc/installerfw.qdoc +++ b/doc/installerfw.qdoc @@ -66,6 +66,7 @@ \li \l{Promoting Updates} \li \l{Customizing Installers} \endlist + \li \l{Qt Installer Framework Examples} \li \l{Reference} \list \li \l{Configuration File} diff --git a/doc/installerfw.qdocconf b/doc/installerfw.qdocconf index 30786fa4a..3a7c6419f 100644 --- a/doc/installerfw.qdocconf +++ b/doc/installerfw.qdocconf @@ -8,13 +8,14 @@ project = "Qt Installer Framework" description = "Qt Installer Framework Manual" headerdirs = ../src/libs/installer -sourcedirs = ../src/libs/installer +sourcedirs = ../src/libs/installer \ + includes imagedirs = $SRCDIR/images $SRCDIR/templates/images outputdir = $OUTDIR -exampledirs = $SRCDIR $SRCDIR/examples +exampledirs = $SRCDIR ../examples -sources.fileextensions = "*.qdoc *.cpp" +sources.fileextensions = "*.qdoc *.qdocinc *.cpp" indexes = $QT_INSTALL_DOCS/qtwidgets/qtwidgets.index diff --git a/examples/changeuserinterface/changeuserinterface.pro b/examples/changeuserinterface/changeuserinterface.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/changeuserinterface/changeuserinterface.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/componenterror/componenterror.pro b/examples/componenterror/componenterror.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/componenterror/componenterror.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/doc/changeuserinterface.qdoc b/examples/doc/changeuserinterface.qdoc new file mode 100644 index 000000000..872177b18 --- /dev/null +++ b/examples/doc/changeuserinterface.qdoc @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example changeuserinterface + \ingroup qtifwexamples + \title Change Installer UI Example + + \brief Changing the installer UI by using a component script. + + \e {Change Installer UI} demonstrates how to add a license page to the + installer by using a component script. + + \note Do not use component scripts for translations. + + \include installerfw-examples-configuring.qdocinc + + \quotefile changeuserinterface/config/config.xml + + \include installerfw-examples-packaging.qdocinc + + \list + \li The \c <Version> section specifies the version number of the + component. + \li The \c <Licenses> section specifies the \c name of the license + agreement to be accepted by the end user and the filename of the + \c file that contains the license. + \endlist + + \quotefile changeuserinterface/packages/org.qtproject.ifw.example.changeuserinterface/meta/package.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/componenterror.qdoc b/examples/doc/componenterror.qdoc new file mode 100644 index 000000000..b0530701e --- /dev/null +++ b/examples/doc/componenterror.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example componenterror + \ingroup qtifwexamples + \title Component Error Installer Example + + \brief Reacting to errors in components. + + \include installerfw-examples-configuring.qdocinc + + \quotefile componenterror/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/dynamicpage.qdoc b/examples/doc/dynamicpage.qdoc new file mode 100644 index 000000000..4aba1e743 --- /dev/null +++ b/examples/doc/dynamicpage.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dynamicpage + \ingroup qtifwexamples + \title Dynamic Page Installer Example + + \brief Building an installer by using a script and dynamic pages. + + \include installerfw-examples-configuring.qdocinc + + \quotefile dynamicpage/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/modifyextract.qdoc b/examples/doc/modifyextract.qdoc new file mode 100644 index 000000000..fd5b5ebe5 --- /dev/null +++ b/examples/doc/modifyextract.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example modifyextract + \ingroup qtifwexamples + \title Modify Extract Installer Example + + \brief Using the extract archive hook to modify the target path. + + \include installerfw-examples-configuring.qdocinc + + \quotefile modifyextract/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/openreadme.qdoc b/examples/doc/openreadme.qdoc new file mode 100644 index 000000000..165caf4e2 --- /dev/null +++ b/examples/doc/openreadme.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example openreadme + \ingroup qtifwexamples + \title Open ReadMe Example + + \brief Adding a check box for opening the readme file to the final + installer page. + + \include installerfw-examples-configuring.qdocinc + + \quotefile openreadme/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/quit_installer.qdoc b/examples/doc/quit_installer.qdoc new file mode 100644 index 000000000..bb1655ad2 --- /dev/null +++ b/examples/doc/quit_installer.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example quit_installer + \ingroup qtifwexamples + \title Quit Installer Example + + \brief Quitting an installer by using a script. + + \include installerfw-examples-configuring.qdocinc + + \quotefile quit_installer/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/registerfileextension.qdoc b/examples/doc/registerfileextension.qdoc new file mode 100644 index 000000000..6b9c41e68 --- /dev/null +++ b/examples/doc/registerfileextension.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example registerfileextension + \ingroup qtifwexamples + \title Register File Extension Example + + \brief Registering a filename extension on Windows. + + \include installerfw-examples-configuring.qdocinc + + \quotefile registerfileextension/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/doc/startmenu.qdoc b/examples/doc/startmenu.qdoc new file mode 100644 index 000000000..1c9c98e49 --- /dev/null +++ b/examples/doc/startmenu.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt Installer Framework. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** 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. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example startmenu + \ingroup qtifwexamples + \title Start Menu Shortcut Example + + \brief Adding an entry to the Windows Start menu. + + \include installerfw-examples-configuring.qdocinc + + \quotefile startmenu/config/config.xml + + \include installerfw-examples-generating.qdocinc +*/ diff --git a/examples/dynamicpage/dynamicpage.pro b/examples/dynamicpage/dynamicpage.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/dynamicpage/dynamicpage.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/licenseagreement/licenseagreement.pro b/examples/licenseagreement/licenseagreement.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/licenseagreement/licenseagreement.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/modifyextract/modifyextract.pro b/examples/modifyextract/modifyextract.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/modifyextract/modifyextract.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/openreadme/openreadme.pro b/examples/openreadme/openreadme.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/openreadme/openreadme.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/quit_installer/quit_installer.pro b/examples/quit_installer/quit_installer.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/quit_installer/quit_installer.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/registerfileextension/registerfileextension.pro b/examples/registerfileextension/registerfileextension.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/registerfileextension/registerfileextension.pro @@ -0,0 +1 @@ +OTHER_FILES = diff --git a/examples/startmenu/startmenu.pro b/examples/startmenu/startmenu.pro new file mode 100644 index 000000000..d723fcfcb --- /dev/null +++ b/examples/startmenu/startmenu.pro @@ -0,0 +1 @@ +OTHER_FILES = -- cgit v1.2.3