diff options
| author | Paul Wicking <paul.wicking@qt.io> | 2023-09-29 11:57:19 +0200 |
|---|---|---|
| committer | Paul Wicking <paul.wicking@qt.io> | 2023-09-30 17:51:38 +0000 |
| commit | 9e451480c8ac40f0de9697d038f56c5af1aec5a9 (patch) | |
| tree | e2fb24b52c76c5a584bcb873798203d0f1df5c33 | |
| parent | 6dabfd4312d1744bdf567b58b0516baa4dc10713 (diff) | |
QDoc: Stop encoding `*/` and `\..\.` in HtmlGenerator
In the late 2000s, Java bindings for Qt were released as the project
"qt-jambi". This was discontinued at the end of that decade and spun
off as an open source project, QtJambi, currently maintained by Omix
Visualization (https://github.com/OmixVisualization/qtjambi).
When generating HTML output, QDoc replaces certain characters that are
reserved in HMTL with their HTML entity counterparts. This is done in
the `HtmlGenerator::protect()` method. However, the method also contains
a special case that replaces certain characters that /aren't/ reserved
in HTML, with their HEX counterparts without leading `0`. The sparse
documentation for this special case suggests it is there to satisfy the
Javadoc generator.
The special case is intended to apply to the sequence `*/`, and to a
full stop (`.`) if two full stops occur with any one character between
them. Going by the code comment, the intention of the latter is to
escape the last full stop in the abbreviations of the latin expressions
`id est` (`i.e.`) and `exempli gratia` (`e.g.`).
The implementation is rather naive; for the `*/` sequence, the check
is buggy (off-by-one error in the check for the characters `*` and `/`).
For the spaced dot pair, the implementation fails to take into account
its impact on e.g. ellipses or `6.6.6`.
The existence of this special case for the Javadoc generator may suggest
that QDoc featured a Javadoc generator in the past, which is something
it certainly doesn't feature now. It may also suggest that output from
QDoc was used as input to Javadoc in some form or another. Since QDoc
with Qt 5.15, QDoc features a generator for DocBook, which is more
suitable for use as input to some other generation tool than HTML is.
This patch removes the special case branch. This may cause QDoc to
generate `.` instead of `.` in its HTML output in multiple
locations. This is to be expected.
Change-Id: I45734c11ad5891016dd19b211d54f218c2def3a1
Reviewed-by: Luca Di Sera <luca.disera@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 2e06a8546ffbb8fb05817930553f83b35d0a0d55)
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 660c7e29f7fafcee034073db2ebceececd20c352)
9 files changed, 14 insertions, 20 deletions
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp index b8b413abd..a94a6b479 100644 --- a/src/qdoc/htmlgenerator.cpp +++ b/src/qdoc/htmlgenerator.cpp @@ -3352,12 +3352,6 @@ QString HtmlGenerator::protect(const QString &string) APPEND("—"); } else if (ch == QLatin1Char('"')) { APPEND("""); - } else if ((ch == QLatin1Char('*') && i + 1 < n && string.at(i) == QLatin1Char('/')) - || (ch == QLatin1Char('.') && i > 2 && string.at(i - 2) == QLatin1Char('.'))) { - // we escape '*/' and the last dot in 'e.g.' and 'i.e.' for the Javadoc generator - APPEND("&#x"); - html += QString::number(ch.unicode(), 16); - html += QLatin1Char(';'); } else { if (!html.isEmpty()) html += ch; diff --git a/tests/auto/qdoc/generatedoutput/expected_output/ignoresince/testqdoc-test.html b/tests/auto/qdoc/generatedoutput/expected_output/ignoresince/testqdoc-test.html index 62e5a0e13..56cb1db42 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/ignoresince/testqdoc-test.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/ignoresince/testqdoc-test.html @@ -107,7 +107,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@inlineFunction --> <!-- $$$methodWithEmDashInItsDocs[overload1]$$$methodWithEmDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEmDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEmDashInItsDocs</span>()</h3> -<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> +<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> <p>-----------------------------------------------------------------------</p> <p>People can still add a bunch of dashes, though, without QDoc replacing them all with a series of em dashes.</p> <p>—You can also start a new paragraph with an em dash, if you want to.</p> @@ -115,7 +115,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@methodWithEmDashInItsDocs --> <!-- $$$methodWithEnDashInItsDocs[overload1]$$$methodWithEnDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEnDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEnDashInItsDocs</span>()</h3> -<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> +<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> <pre class="cpp" translate="no"><span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">42</span>; i <span class="operator">></span> <span class="number">0</span>; <span class="operator">-</span><span class="operator">-</span>i) <span class="comment">// Do something cool during countdown.</span></pre> <p>...as it would be silly if this would output –i instead of <code translate="no">--i</code>.</p> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html index 2f0715651..9640ea174 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html @@ -31,7 +31,7 @@ <pre class="cpp plain" translate="no">This is bad code</pre> <p>This text should have a line break riiiiight <br /> noooow.</p> -<p><b>All your text belong to bold</b> ...And this is an examble of only <b>bold</b> being, well, bold.</p> +<p><b>All your text belong to bold</b> ...And this is an examble of only <b>bold</b> being, well, bold.</p> <pre class="cpp" translate="no"> ...</pre> <p>And if I knew qmltext, I guess this is where that would go. </p> <p class="figCaption">This a caption</p> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocmanuallikefileoutput.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocmanuallikefileoutput.html index 80ed5a0f7..e4b120bd0 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocmanuallikefileoutput.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocmanuallikefileoutput.html @@ -19,7 +19,7 @@ <h1 class="title">Document Navigation</h1> <!-- $$$qdoctests-qdocmanuallikefileoutput.html-description --> <div class="descr" id="details"> -<p>The navigation commands...</p> +<p>The navigation commands...</p> <blockquote> <table border="0" cellpadding="0" cellspacing="5" width="100%"> <tr> @@ -56,7 +56,7 @@ <span class="operator"><</span><span class="operator">/</span>head<span class="operator">></span></pre> <h2 id="commands">Commands</h2> <span id="previouspage-command"></span><h3 id="previouspage">\previouspage</h3> -<p>The \previouspage command...</p> +<p>The \previouspage command...</p> </div> <!-- @@@qdoctests-qdocmanuallikefileoutput.html --> </body> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html index a8d0799d4..42298f5ef 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/scopedenum/testqdoc-test.html @@ -127,7 +127,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@inlineFunction --> <!-- $$$methodWithEmDashInItsDocs[overload1]$$$methodWithEmDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEmDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEmDashInItsDocs</span>()</h3> -<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> +<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> <p>-----------------------------------------------------------------------</p> <p>People can still add a bunch of dashes, though, without QDoc replacing them all with a series of em dashes.</p> <p>—You can also start a new paragraph with an em dash, if you want to.</p> @@ -135,7 +135,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@methodWithEmDashInItsDocs --> <!-- $$$methodWithEnDashInItsDocs[overload1]$$$methodWithEnDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEnDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEnDashInItsDocs</span>()</h3> -<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> +<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> <pre class="cpp" translate="no"><span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">42</span>; i <span class="operator">></span> <span class="number">0</span>; <span class="operator">-</span><span class="operator">-</span>i) <span class="comment">// Do something cool during countdown.</span></pre> <p>...as it would be silly if this would output –i instead of <code translate="no">--i</code>.</p> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/space.html b/tests/auto/qdoc/generatedoutput/expected_output/space.html index d9007e9ff..60e389382 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/space.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/space.html @@ -3,7 +3,7 @@ <head> <meta charset="utf-8"> <!-- space.cpp --> - <meta name="description" content="A namespace...in space."> + <meta name="description" content="A namespace...in space."> <title>Space Namespace | UsingDirective</title> </head> <body> @@ -18,7 +18,7 @@ <div class="sidebar-content" id="sidebar-content"></div></div> <h1 class="title" translate="no">Space Namespace</h1> <!-- $$$Space-brief --> -<p>A namespace...in space. <a href="#details">More...</a></p> +<p>A namespace...in space. <a href="#details">More...</a></p> <!-- @@@Space --> <div class="table"><table class="alignedsummary" translate="no"> <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <Space></span></td></tr> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/template/testqdoc-test.html b/tests/auto/qdoc/generatedoutput/expected_output/template/testqdoc-test.html index cbe201447..3f73cfc72 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/template/testqdoc-test.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/template/testqdoc-test.html @@ -118,7 +118,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@inlineFunction --> <!-- $$$methodWithEmDashInItsDocs[overload1]$$$methodWithEmDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEmDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEmDashInItsDocs</span>()</h3> -<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> +<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> <p>-----------------------------------------------------------------------</p> <p>People can still add a bunch of dashes, though, without QDoc replacing them all with a series of em dashes.</p> <p>—You can also start a new paragraph with an em dash, if you want to.</p> @@ -126,7 +126,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@methodWithEmDashInItsDocs --> <!-- $$$methodWithEnDashInItsDocs[overload1]$$$methodWithEnDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEnDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEnDashInItsDocs</span>()</h3> -<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> +<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> <pre class="cpp" translate="no"><span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">42</span>; i <span class="operator">></span> <span class="number">0</span>; <span class="operator">-</span><span class="operator">-</span>i) <span class="comment">// Do something cool during countdown.</span></pre> <p>...as it would be silly if this would output –i instead of <code translate="no">--i</code>.</p> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-test.html b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-test.html index 81e2782cb..dff03025b 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-test.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/testqdoc-test.html @@ -107,7 +107,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@inlineFunction --> <!-- $$$methodWithEmDashInItsDocs[overload1]$$$methodWithEmDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEmDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEmDashInItsDocs</span>()</h3> -<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> +<p>This method has em dashes in its documentation—as you'll find represented by <code translate="no">---</code> in the sources—here and there. The important bit to note is that when passed e.g. to the \c command, the three hyphens are processed as input to the command and not replaced by an em dash.</p> <p>-----------------------------------------------------------------------</p> <p>People can still add a bunch of dashes, though, without QDoc replacing them all with a series of em dashes.</p> <p>—You can also start a new paragraph with an em dash, if you want to.</p> @@ -115,7 +115,7 @@ target_link_libraries(mytarget PRIVATE Qt6::QDocTest)</td></tr> <!-- @@@methodWithEmDashInItsDocs --> <!-- $$$methodWithEnDashInItsDocs[overload1]$$$methodWithEnDashInItsDocs --> <h3 class="fn" translate="no" id="methodWithEnDashInItsDocs"><span class="type">void</span> Test::<span class="name">methodWithEnDashInItsDocs</span>()</h3> -<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> +<p>This method has en dashes in its documentation – as you'll find represented by <code translate="no">--</code> in the sources – here and there. The important bit to note is that when passed e.g. to the \c command, the two hyphens are processed as input to the command and not replaced by an en dash. This also applies to code blocks, where otherwise, the decrement operator would get completely borked:</p> <pre class="cpp" translate="no"><span class="keyword">for</span> (<span class="type">int</span> i <span class="operator">=</span> <span class="number">42</span>; i <span class="operator">></span> <span class="number">0</span>; <span class="operator">-</span><span class="operator">-</span>i) <span class="comment">// Do something cool during countdown.</span></pre> <p>...as it would be silly if this would output –i instead of <code translate="no">--i</code>.</p> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput-exhaustive.html b/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput-exhaustive.html index d034691da..7838144f6 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput-exhaustive.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput-exhaustive.html @@ -40,7 +40,7 @@ <pre class="cpp plain" translate="no">This is bad code</pre> <p>This text should have a line break riiiiight <br /> noooow.</p> -<p><b>All your text belong to bold</b> ...And this is an examble of only <b>bold</b> being, well, bold.</p> +<p><b>All your text belong to bold</b> ...And this is an examble of only <b>bold</b> being, well, bold.</p> <pre class="cpp" translate="no"> ...</pre> <p>And if I knew qmltext, I guess this is where that would go. </p> <p class="figCaption">This a caption</p> |