Make it easy to put the wrapper script on the PATH

[ItsHarper]

My rationale is that setting something up to use topiary-nushell should not require remembering where you downloaded it to

Changes to make

1. Rename wrapper script from format.nu to something like format-nu or topiary-nushell
   a. Note the lack of .nu extension
2. Move the renamed wrapper to a bin folder
   a. Adjust the wrapper as necessary
3. Edit the wrapper to print a helpful message if topiary is not installed.
4. Add a .bat file with the same name alongside the wrapper with the contents nu --stdin <script-name>
   a. This allows the script to run correctly on Windows, as the shebang would not be respected
   b. I have not tested this, as I no longer use Windows
5. Update documentation to recommend putting the bin folder on your PATH, and remove references to the specific topiary-nushell path.

[ItsHarper]

Actually, what if we used the name nufmt? I feel like ultimately there should probably be a single officially-recommended nu formatter, and progress on the current nufmt repo has been very slow. Could it make sense to make this repo the official formatter and rename it to nufmt? The existing nufmt repo could become the long-term, next-generation formatter (kind of like https://github.com/nushell/new-nu-parser), and replace this codebase once it's ready.

Obviously the core Nushell team would need to be on board for that.

[fdncred]

I responded to this in nushell/nufmt#11

[blindFS]

I don't think it's possible to be path agnostic, you have to provide the correct path of the config/query file in this repo.

BTW, you probably won't need it if

1. you have topiary-cli 0.7.0+ on your non-windows machine.
2. this repo cloned to ~/.config/topiary or relevant files in this repo copied to that folder

I mean topiary format --language nu will work without any env var setup.

[blindFS]

PRs are welcome, if you manage to make it work OOTB for all OS, I'll definitely merge it.

[ItsHarper]

I don't think it's possible to be path agnostic, you have to provide the correct path of the config/query file in this repo.

That path is already defined relatively, so it would merely need to be updated to account for the new directory structure. I'm proposing that we make it easy to add a new bin folder to their PATH variable, not that users would install such a bin folder separately from the rest of the repo.

PRs are welcome, if you manage to make it work OOTB for all OS, I'll definitely merge it.

Awesome, maybe I'll do that

[ItsHarper]

you probably won't need it if

1. you have topiary-cli 0.7.0+ on your non-windows machine.
2. this repo cloned to ~/.config/topiary or relevant files in this repo copied to that folder

I mean topiary format --language nu will work without any env var setup.

BTW, that setup (blindly cloning or copying files) isn't compatible with configuring multiple formatters that way, since topiary only looks at a single languages.ncl file in its config dir. Also, the Mac configuration directory is not ~/.config: https://topiary.tweag.io/book/cli/configuration.html#configuration-sources

[blindFS]

you probably won't need it if

1. you have topiary-cli 0.7.0+ on your non-windows machine.
2. this repo cloned to ~/.config/topiary or relevant files in this repo copied to that folder

I mean topiary format --language nu will work without any env var setup.

BTW, that setup (blindly cloning or copying files) isn't compatible with configuring multiple formatters that way, since topiary only looks at a single languages.ncl file in its config dir. Also, the Mac configuration directory is not ~/.config: https://topiary.tweag.io/book/cli/configuration.html#configuration-sources

It is supposed to be working after this.

What's the version of your topiary-cli BTW?

[ItsHarper]

I don't actually use a Mac, I was just going based off of the documentation, which makes no mention of supporting .config on other platforms: https://topiary.tweag.io/book/cli/configuration.html#configuration-sources

I've opened topiary/topiary#1135

[blindFS]

I don't actually use a Mac, I was just going based off of the documentation, which makes no mention of supporting .config on other platforms: https://topiary.tweag.io/book/cli/configuration.html#configuration-sources

Well, is the config merging working for you on Linux then? Have you tried it?

[ItsHarper]

Well, is the config merging working for you on Linux then? Have you tried it?

My point is not that it won't work, but that if someone already has a ~/.config/topiary/languages.ncl file, those instructions would guide them to blindly overwrite whatever they have there (or the git clone command will error-out, if you do it that way).

I am making that PR BTW, and since topiary doesn't have a good way to configure multiple languages across different config files, I'm planning to remove all mentions of cloning to ~/.config, and update everything to use the wrapper script. We can revisit that if topiary adds that feature.

Is that OK with you?

[blindFS]

Well, is the config merging working for you on Linux then? Have you tried it?

My point is not that it won't work, but that if someone already has a ~/.config/topiary/languages.ncl file, those instructions would guide them to blindly overwrite whatever they have there (or the git clone command will error-out, if you do it that way).

If you mean you have another 3rd-party topiary formatter other than this repo and those officially supported ones, then yes, the readme does sound a bit problematic.

I am making that PR BTW, and since topiary doesn't have a good way to configure multiple languages across different config files, I'm planning to remove all mentions of cloning to ~/.config, and update everything to use the wrapper script. We can revisit that if topiary adds that feature.

Is that OK with you?

The instructions were written before v0.7.0 was released. It certainly needs some updates.
And we recently added a nix flake to this repo, which I haven't get time to document either.

It'll be super helpful if you manage to provide more accurate installation/setup instructions of course.

But the wrapper script should be marked as deprecated given now v0.7.0+ will auto-merge ~/.config/topiary/languages.ncl with the official default. No need to mention env setup IMO.

[ItsHarper]

But the wrapper script should be marked as deprecated given now v0.7.0+ will auto-merge ~/.config/topiary/languages.ncl with the official default. No need to mention env setup IMO.

Agreed on not mentioning env setup.

Regarding the wrapper script, why would we deprecate it? ~/.config/topiary/languages.ncl is not a file that topiary-nushell "owns". It belongs to the user, and I don't think we should act like ~/.config/topiary is our playground to do with as we please (cloning our git repo to that location is especially questionable to me). Just because we're an early user of topiary doesn't mean like we should act as if there won't be others in the future.

Instead, now that the wrapper can be easily put on the PATH, we can recommend calling the wrapper by just running topiary-nushell, and you don't have to worry about topiary configuration at all.

If a user wants to configure topiary to know about nu files, providing additional documentation about how to do that would be a good thing, but I think that should involve explaining what files they need to edit, not copy/pasting the files themselves. Ideally, we could configure topiary to look up our languages.scm at wherever topiary-nushell is cloned to on disk, so that the user doesn't have to keep any files in sync. I'm not sure if topiary currently supports that or not.

[blindFS]

But the wrapper script should be marked as deprecated given now v0.7.0+ will auto-merge ~/.config/topiary/languages.ncl with the official default. No need to mention env setup IMO.

Agreed on not mentioning env setup.

Regarding the wrapper script, why would we deprecate it? ~/.config/topiary/languages.ncl is not a file that topiary-nushell "owns". It belongs to the user, and I don't think we should act like ~/.config/topiary is our playground to do with as we please (cloning our git repo to that location is especially questionable to me). Just because we're an early user of topiary doesn't mean like we should act as if there won't be others in the future.

Like I said, the existing instructions need some updates, such as "appending the content of languages.ncl in this repo to ~/.config/topiary/languages.ncl".

At the end of the day, the instructions are basically for nushell users who're not familiar with topiary to get a working setting quick. If you have already setup a 3rd-party topiary formatter, you probably know what you're doing instead of just blindly pasting those commands.

Instead, now that the wrapper can be easily put on the PATH, we can recommend calling the wrapper by just running topiary-nushell, and you don't have to worry about topiary configuration at all.

Occam's Razor, if topiary-cli can be configured to work for nushell easily, why bother a script in PATH? I get pissed if a package installs something into PATH without asking.

If a user wants to configure topiary to know about nu files, providing additional documentation about how to do that would be a good thing, but I think that should involve explaining what files they need to edit, not copy/pasting the files themselves. Ideally, we could configure topiary to look up our languages.scm at wherever topiary-nushell is cloned to on disk, so that the user doesn't have to keep any files in sync. I'm not sure if topiary currently supports that or not.

I don't know what most people think, but I personally want 2 kinds of instructions.

1. A TLDR version for quick testing
2. A detailed version for advanced customization

For the first one, simple cloning to dot config dir is way better than a script in PATH IMO

For the second one, people will have to know what each file does, so no point of a wrapper either.

[ItsHarper]

Occam's Razor, if topiary-cli can be configured to work for nushell easily, why bother a script in PATH? I get pissed if a package installs something into PATH without asking.

I can see your logic, but in my opinion, topiary-cli can't easily be configured to work for nushell without doing something worse than adding a new script to the PATH (which as of now would be merely recommended, not done automatically).

Let's say that a clone of you with your exact opinions wanted to write a topiary formatter for, say, Lua, and they set up their repository exactly like this one, and recommended cloning their repository to ~/.config/topiary too. Now a user who wants to install both the nushell formatter and the lua formatter is unable to follow the getting started instructions for both of them, because they're trying to write to the exact same place.