Doc: Add section headers and fix existing ones in Embedded Linux info

Broke content up, as this is a large page to help with future linking
to specific sections, and to make it easier to scan and search.

Change-Id: I2b84636c08981e034ae1c45bb7a3ecb55c88083a
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
(cherry picked from commit 1cbdc3943a7575a574b019c7047e298714d54787)
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 28 insertions, 7 deletions

diff --git a/doc/src/platforms/emb-linux.qdoc b/doc/src/platforms/emb-linux.qdoc
index cbfe3411..e8d77f9a 100644
--- a/doc/src/platforms/emb-linux.qdoc
+++ b/doc/src/platforms/emb-linux.qdoc
@@ -7,6 +7,8 @@
   \brief Provides information about Embedded Linux support in Qt.
   \ingroup supportedplatform
 
+  \section1 Platform Plugins for Embedded Linux Devices
+
   On Embedded Linux systems, there are multiple platform plugins that you can
   use: EGLFS, LinuxFB, DirectFB, or Wayland. However, the availability of these
   plugins depend on how Qt is configured.
@@ -24,8 +26,6 @@
   See \l{Configure an Embedded Linux Device} for an overview of configuring Qt
   for cross-compilation using an Embedded Linux toolchain.
 
-  \section1 Platform Plugins for Embedded Linux Devices
-
   \target embedded eglfs
   \section2 EGLFS
 
@@ -70,6 +70,7 @@
   Furthermore, APIs designed for desktop platforms or environments with a
   windowing system, such as \l{Drag and Drop}, are not supported on EGLFS.
 
+  \section3 Environment Variables Used by EGLFS
   If necessary, \c eglfs can be configured using the following environment
   variables:
 
@@ -179,6 +180,8 @@
           configuration.
   \endtable
 
+  \section3 Logging
+
   In addition to \c {QT_QPA_EGLFS_DEBUG}, \c eglfs also supports Qt's modern
   categorized logging system. The following logging categories are available:
 
@@ -247,6 +250,8 @@
   applicable since properties like physical and logical screen sizes are all
   queried automatically.
 
+  \section3 Specifying Additional Settings
+
   The \c linuxfb plugin allows you to specify additional settings via the
   \c QT_QPA_PLATFORM environment variable or \c -platform command-line option.
   For example, \c {QT_QPA_PLATFORM=linuxfb:fb=/dev/fb1} specifies that the
@@ -317,6 +322,8 @@
   Launching it with the \c{-platform eglfs --multiscreen --timeout} arguments
   shows a rotating Qt logo on each connected screen for a few seconds.
 
+  \section3 Custom Configuration
+
   The KMS/DRM backend also supports custom configurations via a JSON file. To
   enable this, set the \c QT_QPA_EGLFS_KMS_CONFIG environment variable to the
   name of the file. You can also embed this file into the application via the Qt
@@ -374,6 +381,8 @@
   disconnected. \c off is similar, but it changes the mode and turns off the
   display.
 
+  \section3 Default Behavior
+
   By default, all screens reported by the DRM layer are treated as one big virtual
   desktop. The mouse cursor implementation takes this into account and moves
   across the screens as expected. Although not recommended, you can disable the
@@ -437,6 +446,8 @@
   cursor's behavior may be unexpected with non-linear layouts. Touch should
   present no issues however.
 
+  \section3 Automatic Physic Screen Size Querying
+
   In some cases the automatic querying of the physical screen size via DRM may
   fail. Normally the \c QT_QPA_EGLFS_PHYSICAL_WIDTH and
   \c QT_QPA_EGLFS_PHYSICAL_HEIGHT environment variable would be used to provide the
@@ -449,6 +460,8 @@
   not knowing about multiple screens and relying solely on the first screen's
   values.
 
+  \section3 Active Outputs and QScreen Instances
+
   Each active output from the \c outputs array corresponds to one QScreen
   instance reported from QGuiApplication::screens(). By default, the primary screen
   that QGuiApplication::primaryScreen() reports is the screen that is registered
@@ -478,6 +491,8 @@
   windows, and moving windows between screens, should be avoided and may not
   function as expected.
 
+  \section3 A Common Use Case
+
   The most common and best supported use case for a multi-screen setup is to
   open a dedicated QQuickWindow or QQuickView for each screen. With the default
   \c threaded render loop of the Qt Quick scenegraph, each of these windows will
@@ -514,7 +529,9 @@
 
   \section2 Advanced eglfs_kms Features
 
-  As of Qt 5.11, screen cloning (mirroring) is supported. This is enabled via
+  \section3 Cloning (Mirroring)
+
+  Screen cloning (mirroring) is supported. This is enabled via
   the \c clones property:
 
   \badcode
@@ -538,7 +555,9 @@
   - DP1 in the example - must ever perform a QOpenGLContext::swapBuffers() operation.
   It's up to the configuration and the application to ensure these.
 
-  As of Qt 5.11, headless mode via DRM render nodes is supported. This allows
+  \section3 Headless Mode Using DRM Render
+
+  Headless mode via DRM render nodes is supported. This allows
   performing GPU compute (OpenGL compute shaders, OpenCL) or off-screen OpenGL
   rendering without needing DRM master privileges. In this mode, applications can
   function even when there is already another process outputting to the screen.
@@ -586,6 +605,8 @@
      ctx.doneCurrent();
   \endcode
 
+  \section3 DRM API Selection
+
   KMS/DRM can be used with two different DRM APIs which are \e legacy and \e atomic.
   The main benefit of DRM atomic API is to allow several DRM plane updates
   within the same renderloop, whereas legacy API would require one plane update
@@ -610,7 +631,7 @@
     }
   \endcode
 
-  \section2 eglfs with eglfs_kms_egldevice backend
+  \section2 EGLFS With an eglfs_kms_egldevice Backend
 
   This backend, typically used on Tegra devices, is similar to the KMS/DRM
   backend mentioned above, except that it relies on the EGLDevice and EGLStream
@@ -700,7 +721,7 @@
   systems where multiple input backends are available, set the environment
   variable \c QT_QPA_EGLFS_NO_LIBINPUT to \c 1.
 
-  \section2 eglfs with other backends
+  \section2 EGLFS with other backends
 
   Other backends, that are typically based on targeting the framebuffer or a
   composition API directly via the vendor's EGL implementation, usually provide
@@ -715,7 +736,7 @@
   kernel parameters may also be available as well to control the used
   framebuffer. Refer to the embedded board's documentation.
 
-  \section2 Video Memory
+  \section1 Video Memory
 
   Systems with a fixed amount of dedicated video memory may need extra care
   before running Qt application based on Qt Quick or classes like