From 6cfd7944bf501539e8f72445955405629a10f183 Mon Sep 17 00:00:00 2001
From: Thibaut Cuvelier <cuvelier.thibaut@gmail.com>
Date: Wed, 25 Dec 2024 23:15:29 +0100
Subject: [PATCH] Implement \tabs for DocBook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The existing implementation only works for online HTML and the
workaround generates nonsensical DocBook that not a single processor
could parse.

This implementation is not ideal, but gives enough information for
processors to do their job (i.e. the tab title and contents are uniquely
linked, the tabs in a group are related). Unaware processors still
render useful information to the user thanks to links.

The ideal presentation would use a container such as `formalgroup` for
the tabs, but there is no notion of tab in DocBook.

The missing part in this patch is allowing all uses of tabs with DocBook; they are still guarded by `\if defined(onlinedocs)`.

For instance, this change updates `porting-to-ios.xml` from:

```xml
<db:listitem…>
<db:para>If your application uses imports or plugins that depend on special Qt modules, these Qt modules should be added to your build configuration file. For example, if your application uses the Qt Multimedia import in QML, you should add the following to your .pro or CMakeLists.txt file: </db:para>
<db:section xml:id="using-cmake">
<db:title>Using CMake</db:title>
<db:programlisting language="cpp" role="bad">find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(my_project PRIVATE Qt6::Multimedia)
</db:programlisting>
</db:section>
<db:section xml:id="using-qmake">
<db:title>Using qmake</db:title>
<db:programlisting language="cpp" role="bad">QT += multimedia
</db:programlisting>
<db:para>In Qt for iOS, everything is compiled statically and placed into the application bundle. The applications are &quot;sandboxed&quot; inside their bundles and cannot make use of shared object files. Because of this, also the plugins used by the Qt modules need to be statically linked. To do this, define the required plugins using the <db:link xlink:href="qmake-variable-reference.xml#qtplugin">QTPLUGIN</db:link> variable.</db:para>
</db:section>
```

to:

```xml
<db:listitem…>
<db:para>If your application uses imports or plugins that depend on special Qt modules, these Qt modules should be added to your build configuration file. For example, if your application uses the Qt Multimedia import in QML, you should add the following to your .pro or CMakeLists.txt file: </db:para>
<db:bridgehead xml:id="tab-cmake" renderas="sect5" role="tabbed checked tab-group_build-ios-app" xlink:href="#tab-cmake_contents">CMake</db:bridgehead>
<db:bridgehead xml:id="tab-qmake" renderas="sect5" role="tabbed checked tab-group_build-ios-app" xlink:href="#tab-qmake_contents">qake</db:bridgehead>
<db:sidebar xml:id="tab-cmake_contents">
<db:programlisting language="cpp" role="bad">find_package(Qt6 REQUIRED COMPONENTS Multimedia)
  target_link_libraries(my_project PRIVATE Qt6::Multimedia)
</db:programlisting>
</db:sidebar>
<db:sidebar xml:id="tab-qmake_contents">
<db:programlisting language="cpp" role="bad">QT += multimedia
</db:programlisting>
</db:sidebar>
```

Change-Id: I63f3e8d03a5f4ee52e7c67971d14d4497dd78cb8
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 doc/global/htmltabs.qdocconf | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/doc/global/htmltabs.qdocconf b/doc/global/htmltabs.qdocconf
index 0b07b6737ec..f8fa075bd8c 100644
--- a/doc/global/htmltabs.qdocconf
+++ b/doc/global/htmltabs.qdocconf
@@ -13,9 +13,10 @@
 
 # The {checked} argument ensures that the tab is selected
 # by default when the HTML page is loaded. For the other
-# tabs that are not selected, pass and empty argument {}.
+# tabs that are not selected, pass an empty argument {}.
 #
-# Note that these macros work with the online template only.
+# Note that these macros work with the online template and
+# DocBook only.
 #
 # Example:
 # \if defined(onlinedocs)
@@ -41,6 +42,10 @@ macro.tab.HTML = "<input type=\"radio\" name=\"tabs_\1\" id=\"\2\" \4/><label fo
 macro.tabcontent = "\\div {class=\"tabcontent \1\"}"
 macro.endtabcontent = "\\enddiv"
 
+macro.tab.DocBook = "<db:bridgehead xml:id="\2" renderas="sect5" role="tabbed \4 tab-group_\1" xlink:href="#\2_contents">\3</db:bridgehead>"
+macro.tabcontent.DocBook = "<db:sidebar xml:id="\2_contents">"
+macro.endtabcontent.DocBook = "</db:sidebar>"
+
 HTML.extraimages += template/style/htmltabs.css
 
 HTML.headerstyles += \