Feature: Ruby (phonetic guide) text - Word2007 Read/Write, HTML 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!

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.885% (-0.04%) from 96.921%
when pulling 09a38f6 on Deadpikle:feature/ruby-text
into 10ae499 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! 😄