Sketchup::read_default and ::write_default no mention of v18+ JSON filepaths

[DanRathbun]

Re:

Sketchup::read_default

Sketchup::write_default

---

Whereas the Application Release notes for v18 explains the new locations for user preferences ...

Preferences Location The majority of preferences are now stored in two json files. There are still some OS controlled preferences that remain in the registry (Win) or plist (Mac). The json files are saved in the following locations:

On Win: "PrivatePreferences.json" is saved to : 'C:\Users\AppData\Local\SketchUp\SketchUp 2018\SketchUp'

"SharedPreferences.json" is saved to : 'C:\Users\AppData\Roaming\SketchUp\SketchUp 2018\SketchUp'

On Mac: Both "PrivatePreferences.json" and "SharedPreferences.json" are saved to : '/Users//Library/Application Support/SketchUp 2018/SketchUp'

---

In the ruby.sketchup.com docs (api-stubs) ...

EITHER:

A. Sectionalize the docstring for v18+ and v17 and earlier

B. In the v18+ section:

1. Give JSON filepaths

2. Explain the difference between "private" and "shared"

C. In the v17 and older section:

1. Remove mention of .ini files (as this is no longer true and if it ever was, was likely pre v6 and no one remembers or cares.)

OR:

A. Provide a separate write up in the "Files" collection explaining this detailed history and implementation of extension defaults and preferences, giving paths, sample code, etc, etc.

B. Simplify the docstrings for #read_default and #write_default to simply use a generic term like "preference settings" rather than ".ini" or "registry" or "plist" "json file" etc.

C. Add a "For more detail, history and coding tips, see Saving Preferences" link to the separate markdown file in the "Files" collection, for both methods.

---

Example Code

# Ruby 2+ and SketchUp v18+ ONLY

if (Sketchup::platform == :platform_win rescue RUBY_PLATFORM !~ /darwin/i)

  ver = Sketchup::version.to_i

  # MS Windows editions:

  private_prefs = File.join(
    ENV["LOCALAPPDATA"],'SketchUp',
    "SketchUp 20#{ver}",'SketchUp',
    'PrivatePreferences.json'
  ).encode(Encoding::find("filesystem"))

  shared_prefs = File.join(
    ENV["APPDATA"],'SketchUp',
    "SketchUp 20#{ver}",'SketchUp',
    'SharedPreferences.json'
  ).encode(Encoding::find("filesystem"))

else

  # Apple Mac editions:

  private_prefs = File.join(
    '/Users/Library/Application Support',
    "SketchUp 20#{ver}",'SketchUp',
    'PrivatePreferences.json'
  ).encode(Encoding::find("filesystem"))

  shared_prefs = File.join(
    '/Users/Library/Application Support',
    "SketchUp 20#{ver}",'SketchUp',
    'SharedPreferences.json'
  ).encode(Encoding::find("filesystem"))

end

[Eneroth3]

I agree the mentions of .ini files should be removed but I'm not sure if the new JSON approach should be mentioned here as it lies outside of the API contract. The implementation could be interesting to know, maybe mostly for system administrators syncing up machines, but I think it's outside the scope of the API. Maybe this can be documented elsewhere, or the phrasing could clarify this is an implementation detail.

Don't get me wrong, I've relied on knowledge about the JSON files myself to manually sync them when the IT department failed, but SketchUp should also be able to change the implementation at any point without breaking API.

[DanRathbun]

... as it lies outside of the API contract.

But it is within the "Application Contract" ? ... until the application release notes state otherwise ?

Maybe this can be documented elsewhere, ...

It is (as said,) in the application release notes. I'm not sure why, as it is really extension developers that care, or needed to read and write to these files.

I did suggest two courses of action, the latter ...

A. Provide a separate write up in the "Files" collection explaining this detailed history and implementation of extension defaults and preferences, giving paths, sample code, etc, etc.

B. Simplify the docstrings for #read_default and #write_default to simply use a generic term like "preference settings" rather than ".ini" or "registry" or "plist" "json file" etc.

C. Add a "For more detail, history and coding tips, see Saving Preferences" link to the separate markdown file in the "Files" collection, for both methods.

Anyway ... I think I did open an issue that C API release notes are listed in the application release notes, rather than in the C SDK, and coders wonder where the notes are. They don't think to go looking at the end user application release notes.

So ... I stress again, put the information for coders where they'll go looking for it.

SketchUp should also be able to change the implementation at any point without breaking API.

I agree, and they have. Even though some coders used registry read code to read setting directly from the registry, it didn't stop the SU Dev team from implementing a better solution. The rollout might have broken some code "in the wild", but that was just too bad for the coder. They had to adapt their code.

[thomthom]

I think we could have a separate page with historic details that the docs can link to and expand in more detail. In most cases the details of how settings are stored is irrelevant. For the edge cases we can have a separate information to aid developers.

[DanRathbun]

I think it may be time to create a new repo for the extra Files section.

In addition to categorical pages, each class should get it's own "lost manual" kind of page, with tip, tricks, pitfalls and extended code examples.