Some modified files in `SCDoc.helpSourceDir`Not Copied to `SCDoc.helpTargetDir`

[prko]

Environment

• SuperCollider version: 3.14.0-dev[a800715]
• Operating system:
• Other details (Qt version, audio driver, etc.):

Steps to Reproduce

1. Launch scide or supercollider.app.
2. Modify a file within SCDoc.helpSourceDir +/+ "static".
3. Recompile sclang or restart scide (or supercollider.app).

Expected vs. Actual Behaviour

Expected Behaviour
The modified file(s) should be copied to SCDoc.helpTargetDir.

Actual Behaviour
The modified file(s) are not copied to SCDoc.helpTargetDir.
Even if the scdoc.css file is deleted from SCDoc.helpTargetDir +/+ "static", it is not copied over again.

To keep some files in SCDoc.helpTargetDir up to date, I have to delete the whole SCDoc.helpTargetDir.

This appears to be a regression. While it does not impact the user experience, it is inconvenient for developers who need to revise files within SCDoc.helpTargetDir.

One more example:

• If there is no SCDoc.targetDir, SCDoc.helpSourceDir +/+ "custom.css" is copied into SCDoc.helpTargetDir.
• However, recompiling sclang after editing custom.css in SCDoc.helpSourceDir does not update custom.css in SCDoc.helpTargetDir. To update custom.css in SCDoc.helpTargetDir, I should delete SCDoc.targetDir.
• Previously, every changed file was synchronised when recompiling sclang.

[capital-G]

Hey @prko - I think this is not a bug which was introduced by 3.14 but has always been present. IIRC the static files are only replaced if their mtime is newer - which is a flawed mechanism IMO.

#6627 introduced an additional way to invalidate cached static files, that is if a new SCDoc version is encountered - this allows to get rid of the former formatting errors encountered in the docs when switching between 3.13 and 3.14 (see https://dev.docs.supercollider.online/Classes/SCDoc.html#*refreshStaticFiles)

As the SCDoc caching system is somehow brittle, I have some drafts that in a rewrite we will not require caching at all as everything will be generated on-the-fly.

[prko]

I think this is not a bug which was introduced by 3.14 but has always been present.

No, it is a new phenomenon, and it is a regression:

1. Until SC3.13.0:

   • The modified custom.css was synchronised when recompiling sclang.
   • The changed image files were synchronised when recompiling sclang.

2. With SC3.14.0-dev from mid of 2024 [d52b052]:

   • The modified custom.css was synchronised when refreshing any help documentation using SC HelpBrowser after modifying an schelp file.
   • The changed image files were synchronised when refreshing any help documentation using SC HelpBrowser after modifying an schelp file.

3. With SC3.14.0-deve after #6627: To synchronise any modification (including newly created files), SCDoc.helpTargetDir should be manually removed.

   • The modified custom.css is not synchronised when SCDoc.helpTargetDir already exists.
   • The changed image files were synchronised when SCDoc.helpTargetDir already exists.

Which is best for developers who update the contents of SCDoc? I used [d52b052], which also supports KaTeX. Yesterday, I switched to the latest version of SC3.14.0-dev, but have since reverted to [d52b052].

[capital-G]

Mh, I am sorry for all the trouble :/ The intention of https://github.com/supercollider/supercollider/pull/6627 was/is to not overwrite any user files implicitly, especially custom.css - this caused issues when 3.13 and 3.14 needed a different stylesheet/js file, it made essentially any updates not really possible anymore when switching between releases which is something we should keep possible.

As mentioned I think its best to stop putting any resources into SCDoc and focus on a proper rewrite - the whole system is really broken due to its implicit caching and when fixing one thing another one breaks and it is already in a broken state (e.g. we produce invalid DOM code).

[prko]

Thank you for the clarification.

By restoring the code in SCDoc.sc between lines 506–515, I was able to revert to the previous behaviour.

		this.postMsg("Copying"+nonHelpFiles.size+"non-help files...",1);


 		nonHelpFiles.do {|x|
 			var dest = SCDoc.helpTargetDir+/+x[1];
 			var folder = dest.dirname;
 			File.mkdir(folder);
 			if(File.exists(dest).not or: {File.mtime(x[0]) > File.mtime(dest)}) {
 				File.delete(dest);
 				File.copy(x[0],dest);
 			};
 		};

I understand your reasoning behind #6627 and the decision to avoid implicitly overwriting user files, particularly custom.css. Maintaining compatibility between different releases is certainly important, and I appreciate the rationale behind this change.

However, I would greatly appreciate reconsideration of restoring these lines, though I understand that may not be feasible based on your explanation.

That said, I am curious how other developers are adapting to this breaking change. Are they generally avoiding SC-IDE when working with schelp files? The new behavior does not seem very convenient in practice.