Doc: update description of qmake SUBDIRS variable

You can specify a relative path to a .pro file in any directory.

Fixed a capitalization issue and a grammar issue and changed the
visible text in a link target.

Task-number: QTBUG-14139
Change-Id: Ib476bd400c46645709950c582492edcaaba9d7ed
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@digia.com>
(cherry picked from qtbase/31e665c7cd9b2edb25fa695bed9c528c95ad0c64)

2 files changed, 14 insertions, 9 deletions

diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc
index 70548aa..49d7bd8 100644
--- a/doc/src/development/qmake-manual.qdoc
+++ b/doc/src/development/qmake-manual.qdoc
@@ -3223,20 +3223,24 @@
     \target SUBDIRS
     \section1 SUBDIRS
 
-    This variable, when used with the \l{#TEMPLATE}{\c subdirs template}
-    contains the names of all subdirectories or project files that contain
-    parts of the project that need be built. Each subdirectory specified
+    This variable, when used with the \c subdirs \l{#TEMPLATE}{template}
+    specifies the names of all subdirectories or project files that contain
+    parts of the project that need to be built. Each subdirectory specified
     using this variable must contain its own project file.
 
+    It is recommended that the project file in each subdirectory has the same
+    base name as the subdirectory itself, because that makes it possible to omit
+    the file name. For example, if the subdirectory is called \c myapp, the
+    project file in that directory should be called \c myapp.pro.
+
+    Alternatively, you can specify a relative path to a .pro file in any
+    directory. It is strongly recommended that you specify only paths in the
+    current project's parent directory or its subdirectories.
+
     For example:
 
     \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 50
 
-    It is essential that the project file in each subdirectory has the same
-    name as the subdirectory itself, so that \l{qmake Manual#qmake}{\c qmake}
-    can find it. For example, if the subdirectory is called \c myapp then the
-    project file in that directory should be called \c myapp.pro.
-
     If you need to ensure that the subdirectories are built in the order in
     which they are specified, update the \l{#CONFIG}{CONFIG} variable to
     include the \c ordered option:
diff --git a/doc/src/snippets/code/doc_src_qmake-manual.pro b/doc/src/snippets/code/doc_src_qmake-manual.pro
index ebe401d..b26a609 100644
--- a/doc/src/snippets/code/doc_src_qmake-manual.pro
+++ b/doc/src/snippets/code/doc_src_qmake-manual.pro
@@ -327,7 +327,8 @@ SOURCES = myclass.cpp \
 
 #! [50]
 SUBDIRS = kernel \
-          tools
+          tools \
+          myapp
 #! [50]