From 5c66c08bedda2a7e4ac0602ac4b05896e60cf699 Mon Sep 17 00:00:00 2001
From: Luca Di Sera <luca.disera@qt.io>
Date: Wed, 24 May 2023 15:50:43 +0200
Subject: [PATCH] Doc: Add DocBook version of youtube macro
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

QDoc allows code-expanding macros to be defined so that the user can
abstract away common code in a simple to use command.

Furthermore, macros allows for a different expansion based on the
currently generated format so that format-specific requirements can be
satisfied when required.

Due to a certain bug in QDoc, when generating the DocBook format, QDoc
would expand an HTML specific macro definition when a DocBook specific
one was not provided.

As this bug is now being fixed, the DocBook format will lose some of the
output that it was previously generating.

For example, the "\youtube" macro is defined, for HTML, so that a
youtube video can be embedded by reference.

To avoid losing the usage of "\youtube" when generating DocBook, an
equivalent version expansion of the macro is now provided for the
DocBook format.

Change-Id: Id74155f2c30b80b5f4490f8451cd8d00535806d6
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 doc/global/macros-online.qdocconf |  6 ++++++
 doc/global/macros.qdocconf        | 10 ++++++++++
 2 files changed, 16 insertions(+)

diff --git a/doc/global/macros-online.qdocconf b/doc/global/macros-online.qdocconf
index bfc2f98a12c..dafbabff4d2 100644
--- a/doc/global/macros-online.qdocconf
+++ b/doc/global/macros-online.qdocconf
@@ -2,5 +2,11 @@ macro.youtube.HTML = "<div class=\"video\">\n<span class=\"vspan\"></span>\n" \
                      "<iframe src=\"https://www.youtube.com/embed/\1\"" \
                      "frameborder=\"0\" allowfullscreen>\n" \
                      "</iframe></div>\n"
+macro.youtube.DocBook = "<db:mediaobject>\n" \
+                        "<db:videoobject>\n" \
+                        "<db:videodata fileref=\"\1\">\n" \
+                        "</db:videodata>\n" \
+                        "</db:videoobject>\n" \
+                        "</db:mediaobject>\n"
 
 include(htmltabs.qdocconf)
diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf
index 6c64abee93b..7bd00a15105 100644
--- a/doc/global/macros.qdocconf
+++ b/doc/global/macros.qdocconf
@@ -90,6 +90,16 @@ macro.youtube.HTML = "<div class=\"video\">\n" \
                      "<img src=\"images/\1.jpg\"" \
                      "title=\"Click to play in a browser\" /></a>\n" \
                      "</div>\n"
+macro.youtube.DocBook = "<db:mediaobject>\n" \
+                        "<db:videoobject>\n" \
+                        "<db:videodata fileref=\"\1\">\n" \
+                        "</db:videodata>\n" \
+                        "</db:videoobject>\n" \
+                        "<db:imageobject>\n" \
+                        "<db:imagedata fileref=\"images/\1.jpg\">\n" \
+                        "</db:imagedata>\n" \
+                        "</db:imageobject>\n" \
+                        "</db:mediaobject>\n"
 
 macro.excludefromcreator = "\\meta tag broken"