Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

XML fragment fixup for refsect1 #208

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

XML fragment fixup for refsect1 #208

wants to merge 2 commits into from

Conversation

alfsb
Copy link
Member

@alfsb alfsb commented Dec 14, 2024

This PR changes the fix up for refsect1 to <title>_</title><simpara>%failed xi:xinclude%</simpara>. As this cannot be parsed as an XML document, code is also changed to support fix ups that are XML fragments.

This PR, php/doc-it#55 and doc-en patch below fixes doc-it building.

diff --git a/reference/gmp/gmp/construct.xml b/reference/gmp/gmp/construct.xml
index df2e9e0893..cdc32f70bb 100644
--- a/reference/gmp/gmp/construct.xml
+++ b/reference/gmp/gmp/construct.xml
@@ -18,9 +18,7 @@
  </refsect1>
 
  <refsect1 role="parameters">
-  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.gmp-init')/db:refsect1[@role='parameters']/*)">
-   <xi:fallback/>
-  </xi:include>
+  <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.gmp-init')/db:refsect1[@role='parameters']/*)"/>
  </refsect1>
 
  <refsect1 role="seealso">

Two notes:

  1. This is a small-scale example of the effects of removing <xi:fallback> from sources, as the automatic fixups can push/keep translations into building state.
  2. I think I found a bug on PhD, while developing this.

The fixup <title></title><simpara>%failed xi:xinclude%</simpara> (empty title) is saved on .manual.xml as:

<refsect1 role="parameters">
 <title/><simpara>%failed xi:xinclude%</simpara>
</refsect1

and is rendered by php phd/render.php --format bigxhtml as:

<div class="refsect1 parameters" id="refsect1-function.bcdivmod-parameters">
  <h3 class="title"><p class="simpara">%failed xi:xinclude%</p></h3>
</div>

Instead of:

<div class="refsect1 parameters" id="refsect1-function.bcdivmod-parameters">
  <h3 class="title"></h3>
  <p class="simpara">%failed xi:xinclude%</p>
</div>

In other words, empty <title> causes their siblings to be rendered inside the title, instead of around it.

To workaround this, and to avoid rendering %failed xi:xinclude% as big as titles, I placed an _ inside de title.

I'm not so certain about %failed xi:xinclude%/_. Another alternative was to keep these elements empty, so XInclude failures does not inject warnings in rendered manuals, and would like comments about this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant