Feature: Ruby (phonetic guide) text - Word2007 Read/Write, HTML Read/Write, RTF write, ODT basic write

[Deadpikle]

Description

Right now, PHPWord does not support ruby text elements (phonetic guides) at all. You can see some documentation (of a sort) on this type of element here: https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.wordprocessing.ruby?view=openxml-3.0.1 and some how-to-use here

A ruby (phonetic guide) element allows you to do things like this:

This PR adds both reading and writing support for ruby elements to Word2007 files. Basic text support has been checked along with Titles. Other elements may or may not be supported at this time (in other words, I didn't test literally every element with ruby); as long as the code eventually gets into readRunChild, the ruby should be read properly.

Please note: This is my first contribution to this repository. I may have missed something when trying to match current style guidelines, etc. Please correct me and point me in the right direction if needed. Thank you!

(Update: This PR now supports reading/writing HTML as well as writing support for RTF and basic writing support for ODT.)

Checklist:

• My CI is 🟢
• I have covered by unit tests my new code (check build/coverage for coverage report)
• I have updated the documentation to describe the changes
• I have updated the changelog

[coveralls]

coverage: 96.823% (-0.09%) from 96.917%
when pulling ec18c81 on Deadpikle:feature/ruby-text
into a4468f2 on PHPOffice:master.

[Progi1984]

It's a wonderful good job.

Could you add a Sample for this new feature ?

Do you only need in Word2007 ? (not in another formats ?)

[Deadpikle]

Could you add a Sample for this new feature ?

I've added a new sample - Sample_46_RubyPhoneticGuide. I also added the getters for Ruby and the unit tests for that class.

Do you only need in Word2007 ? (not in another formats ?)

I only need Word2007 writing personally, but I went ahead and added HTML writing support, too, since I might need that later and to demonstrate how that works. (Reading should be possible, I think, but looking at the code in PhpWord/Shared/Html.php, not sure how to do it quite right with the styles...basically, the core text in <ruby> goes into the base text TextRun, and the text inside <rt>, which is inside the <ruby> tag goes to the ruby text TextRun, with applicable styles along the way. That's all.)

ODT documents seem to support ruby text (see below file for sample), but the <style> is written in an interesting way, and I'm not sure how to handle that. A future PR by someone else could address ODT reading/writing. It's probably pretty straightforward at this point, but I'm not sure how to do it, so I'll let someone else tackle it.

PhoneticGuide.odt

For PDF output, mpdf does not support <ruby> tags, and I'm not sure if it has a graceful fallback or not. dompdf converts it to the format {base text} ({ruby text}), which is the default for browsers that don't support ruby out of the box (see documentation: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/rp), so dompdf at least handles it gracefully.

If someone wanted RTF output (another format I am unfamiliar with), my guess is that writing ruby text in the {base text} ({ruby text}) format would be the way to go.

Again, I'll let someone else in another PR or worker handle those since I am not needing them and no one else has ever even asked for ruby support in this lib. :) Someone else who is more familiar with reading/writing ODT as well as writing PDF/RTF can probably handle things faster than I can at this point, anyway.

Thank you for your time and managing this lib, etc! 😄

[Deadpikle]

I went ahead and updated the PR to add:

• HTML reading support.
• RTF writing (writes in format base text (ruby text)).
• Basic ODT writing (writes in format base text (ruby text)); this does NOT take advantage of native ODT handling at this time, and this is noted in the code.
• Added support for TextRun::getText when a child element is a Ruby element (writes string in format base text (ruby text)).

I am not planning on sneaking in native ODT support later 😅 Someone else can do that if they ever need it in the future. At least for now, ODT files now don't totally ignore ruby elements, which is an improvement to before. So this PR is ready to go.

EDIT: Have used this PR in my intended project now and it works just as expected. Am able to write a full, 10+ page doc with ruby text and formatting, no problem, and then print that Word doc to PDF via Word itself. Sometimes Word gets upset if you choose the wrong font, but that's a Word problem, not this lib.

[Progi1984]

One last comment and it will be ok.

[Deadpikle]

Tests have been added. Thanks again.

[Progi1984]

Thank you for your wonderful contribution, @Deadpikle 🎉