Query about GitHub and User Guide correction

[DiapDealer]

I'm pretty baffled to tell you the truth. If there were settings for git that were set incorrectly, it might make sense if every file in the epub showed changes. But the relative randomness of the altered files makes no sense to me.

I can see from your diff that most of the files whose changes can't be explained (except for the toc.ncx) are simply having newlines added to the end of them. But what I can't figure out is what process is touching these files that would cause that to happen in the first place.

[KevinH]

No idea either. Maybe ... did he do a full github clone or just download the github zip, or src release zip?

Maybe try a git pull and see if his git clone is missing any files?

Very strange!

[philja]

Originally Posted by KevinH

No idea either. Maybe ... did he do a full github clone or just download the github zip, or src release zip?

Maybe try a git pull and see if his git clone is missing any files?

Very strange!

I'm the first to admit I'm not a GitHub or git mastermind, but I did try to inform myself how to fork and clone. I could still have made some bobo.

I didn't just download the zip. I used the cli to git clone the url copied from GitHub.

I don't regularly use Mend or Prettify when working on my epubs. If the epub was in good shape before the editing, I normally just use F7 and then rely on epubcheck after edits.

In the case of this relatively small edit of the user guide, I followed the recommendations in the README file which, on first go, I misinterpreted and applied the M&P to all files. After Kevin's remarks, on the second attempt, I applied M&P only to the two xhtml files I edited.

Since I knew exactly where I wanted to make the edits, I only opened the two xhtml files concerned. There was no change to the structure of the epub, no need to rebuild the TOCs and, in retrospect, probably no need to use M&P at all.

When I've a little more time, I'll try again from scratch.

[KevinH]

Sounds like you did everything correctly. So I have no idea why ncx changes so much without regeneration.

Won't be able to test anything for the next 2 weeks or so.

[DiapDealer]

Quick thought: have you modified the default pretty-print.xml file (used to tweak how Prettify changes things)? It still shouldn't change files you didn't use M&P on, but it got me thinking about how huge the changes were when you initially used M&P on everything. When I use M&P on the current user guide xhtml; nothing gets modified.

[philja]

Originally Posted by DiapDealer

Quick thought: have you modified the default pretty-print.xml file (used to tweak how Prettify changes things)? It still shouldn't change files you didn't use M&P on, but it got me thinking about how huge the changes were when you initially used M&P on everything. When I use M&P on the current user guide xhtml; nothing gets modified.

No, sorry. I haven't knowingly modified anything in Pretty Print. I just checked the prettyprint.xml file, which is dated 08/06/2026 (which on my machine is 8 June 2026). I've never looked inside that file before, and as I said above, I normally never use Mend or Prettify on a valid epub which I edit.

[DiapDealer]

Did you commit your changes before you generated the diff that you uploaded, or were the changes still unstaged?

[philja]

I think I'm getting a little closer to the source of the problem.

Here is a quote from the README file from the github website
:

- Do your editing (saving changes to a local temporary epub somewhere if you must). Remember to use "Mend and Prettify" after you're done, and always make sure the epub validates with no errors. Then when ready, save the contents back to the "src" directory of your local, cloned repository using the [FolderOut Sigil plugin](https://www.mobileread.com/forums/sh...d.php?t=293649).

In my first two attempts, I had taken the suggestion 'saving changes to a local temporary epub somewhere if you must' in the order in which it was written.

For this 3rd attempt, using a fresh clone, I ignored that save, ignored the prettify (because my edits respected the original layouts) and went straight for the F7, Epubcheck, FolderOut.

Results in the screenshots attached.

You see only 3 files changed (+ the content.opf file).

So it looks as though it was the action of saving myself a temp.epub before the FolderOut action which caused the unwanted stuff. Does that sound reasonable?

[DiapDealer]

I tried saving the epub myself to see if it made a difference in my testing--and it didn't. The only question is where did you save the epub to before? Hopefully not in the repository (not that it should really matter).

I clearly need to give the instructions a bit of TLC. For changes that are simple enough to finish in one quick session, there really is no need to save the epub when working on changes to the guide. The only real reason to save would be because you're not done editing, but you need to close Sigil or the epub and come back to it later.

It's true that saving an epub in Sigil will cause Mend to correct things it thinks are wrong (if the default preferences for Mend on Open/Save are being used). But in my testing, the user guide's source was already in a "state of grace" so Mend on Save didn't result in any changes.

[philja]

Originally Posted by DiapDealer

I tried saving the epub myself to see if it made a difference in my testing--and it didn't. The only question is where did you save the epub to before? Hopefully not in the repository (not that it should really matter).

I clearly need to give the instructions a bit of TLC. For changes that are simple enough to finish in one quick session, there really is no need to save the epub when working on changes to the guide. The only real reason to save would be because you're not done editing, but you need to close Sigil or the epub and come back to it later.

It's true that saving an epub in Sigil will cause Mend to correct things it thinks are wrong (if the default preferences for Mend on Open/Save are being used). But in my testing, the user guide's source was already in a "state of grace" so Mend on Save didn't result in any changes.

The saves of the epub that I made were to Desktop - certainly NOT to the repo. And, now you mentioned it, the Preferences were set for Mend on Open & Save. In each of the three attempts, the few edits I made were all done in a single, short session.

I would have expected my fork and its clone to have been in your "state of grace" when I started, on all three attempts (each with fresh, clean forks and clones). So why did the save to a temp.epub cause so many changes to files which I didn't even open let alone edit? Maybe, the source was not in its "state of grace"?

The second attempt was an improvement on the first, but still the fresh-start fork should have been in that "state of grace".

The only difference I made on the third go was that I saved a temp epub copy, AFTER the FolderOut operation was completed.

The lesson I'm drawing from this is that the order of events seems to matter for reasons I don't understand. But pragmatism shall prevail in the future unless further discoveries turn up.

[DiapDealer]

Now when you master the commit, merge (unless you push your new branch to your fork) and push, you'll be ready to tackle the pull request.