How to fix the EPUB documentation

_Hello._ I'm starting to learn Godot and decided to read the documentation on the latest release, but I've run into an issue where my preferred EPUB reader wasn't able to open the file. Since I work with .epub files on a regular basis, I decided to check it out in Sigil and found some issues. I'm not technically inclined enough to go through with a pull request, but I hope the following explanation will help someone fix these issues once and for all.

**Issue #1 - First Warning**

Upon opening GodotEngine.epub in Sigil, the following warning appears:

Warning: This EPUB had HTML files that were not well formed or are missing a DOCTYPE, HTML, head or body elements.
They were automatically fixed based on your Preference setting to Clean on Open.

This performs many small fixes, like separating "/head""body" tags onto two different lines, removing spaces between " and />, replacing " entities with " characters inside "p" tags, etc., are included in that automatic fix. Most importantly, this makes the 404.xhtml file appear in the Book Browser. We'll get back to this file a bit later, for now, just know that this automatic fix is what reveals it.

For more detailed information on the changes:
1. Go to Edit -> Preferences -> General Settings, uncheck "Mend Not Well Formed HTML Code on: Open". Leave the checkmark "on: Save".
2. Open the file that wasn't fixed, go to Checkpoints -> Create Checkpoint for Epub.
3. Save, press Yes to automatically mend the files.
4. Go to Checkpoints -> Compare Epub Against Previous Checkpoints. You will see a window where you can check which files were edited, the changes will be highlighted, the design is intuitive.
5. Create another Checkpoint before making changes manually.

---

**Issue #2 - Diagnostics**

After dealing with the automatic fixes, the first thing that needs to be done is running diagnostics. Sigil has a built-in tool to check if the EPUB file is well-formed, you can find it in Tools -> Well-Formed Check EPUB. After running the check, it shows 4 types of errors:

1. Missing or multiple "xml declaration header". (100+ counts)
2. Can not nest a "p" tag inside another "p" tag. (1 count)
3. Attribute "content" has unmatched quotes on attribute value. (11 counts)
4. illegal character in text. (6 counts, but it's part of a different issue)

It's possible to solve most of these problems by going to Tools -> Reformat HTML -> Mend All HTML Files, but it's not perfect and no one wants to do it every time an update comes out, so I will explain what these problems are, how they are fixed, and what long-term solutions I can see being implemented

---

1. After the automatic fix, only a handful of files that were affected by it have "?xml version="1.0" encoding="utf-8"?" XML declaration at the top. With EPUB 3, it's not a critical part, but it is recommended to include it to prevent compatibility issues, so it should be present at the beginning of each XHTML file. That is one problem that Mend All can solve perfectly

---

2. A problem that Mend All can _technically_ fix. html5_shell_classref.xhtml has a "p" tag inside of another "p" tag in the following segment:

```html

file (string|ArrayBuffer()) -- <<

tag was here >> The file to preload.

If a string the file will be loaded from that path.

If an ArrayBuffer or a view on one, the buffer will used as the content of the file.

<<

tag was here >>

```

The automatic solution adds a closing "/p" and an opening "p" tags to counter the existing ones, but removing the two tags causing the issue is a cleaner solution

---

3. A problem that Mend All solves fully, but that shouldn't be an issue in the first place. To show you an example of an error:

``

Sigil flags this line as an issue because, unlike HTML, which treats most characters inside an attribute value as text, XHTML used in EPUBs has stricter rules. < and & **must** be replaced with entities, > isn't enforced, but it's best to replace it with an entity as well to avoid potential issues.

`List of entities: < -> < or < , > -> > or > , & -> & or & (each with ; at the end)

"Script Editor's File > Run menu option" -> "Script Editor's File > Run menu option"

The real issue comes from the fact that an entity can be cut off by the "&quo..." and end up corrupting the file again, because & is a massive problem. I see two possible long-term solutions: either designing custom descriptions for EPUB or removing this part completely, as it's invisible outside of the file data

---

**4. or Issue #3 - 404.xhtml**

Finally, the "illegal character in text" warning points towards the 404.xhtml file that was mentioned at the beginning. It is likely the culprit responsible for many EPUB Readers identifying the whole .epub as corrupted. Thankfully, it's not essential, has no references anywhere in the documentation, and as such can be safely deleted.

There are two reasons why this file is an issue:

1 - It has code that contains multiple counts of > inside the "script" tag, but more importantly, it has &&, which XHTML can't parse

2 - The fact that 404.xhtml doesn't show in Book Browser before automatic fixing means that when forming the .epub, it encounters some kind of problem

The best solution is to exclude this file entirely from the EPUB version of the documentation

---

**Issue #4 - Images**

I question the necessity for some of the images to be so high quality, animated with 32 or 24 bits per pixel. For example:

_images/tree_sway.gif (13.5 mb, 32bpp)
_images/scene.gif (7 mb, 32bpp)
_images/introduction_usagi_shima.png (3.5 mb, 24 bpp for an image with 8 colors)

With 20 other images ranging 1 to 2.5 mb. It's beautiful, but it might be over the top

---

At the end, please allow me to express my sincere gratitude to everyone working on Godot and helping aspiring game developers realize their dreams,

_Best regards._

P.s. I'm sorry if something sounds weird or makes little sense, I've spent too much time getting distracted with Godot and not enough time collecting my thoughts

Edit: Tags and entities kept on disappearing