Added detail on defining a path on MacOS

[bunk3m]

@gdt suggested that I add an edit (Aug 2022) to the manual that shares the answers that @tleedjarv graciously provided for me. I was having problems defining a root on OSX. OSX generally requires a backslash escape when there is a space in the path. However, Unison doesn't need the backslash escape when defining paths on OSX. I hope the addition helps describe the OSX special case.

[tleedjarv]

I don't think this is specific to OSX. You can leave out any mention of an OS and just state that spaces in paths don't need to be escaped.

(Haven't tested this, but I think this also applies to other special characters; in fact, there is no way to escape anything.)

[bunk3m]

Thanks for the addition @tleedjarv . Back in August I did try all the combination of " "; ' '; backtick backtick (can't find how to escape it in markdown); etc. and none worked on OSX. That's why I was stumped and asked the question. Sometimes the obvious (no escape) isn't obvious 🤣 .

Is the "no need to escape" something that would be explained in the oocaml compiler docs so we can confirm our belief?

This is my first attempt to do anything in Github so I haven't figured out how to make the change you suggested. I'll look for the Github docs to see if I can figure it out.

[tleedjarv]

Is the "no need to escape" something that would be explained in the oocaml compiler docs so we can confirm our belief?

Actually the opposite. The "no need to escape" is the default and the "need to escape" is something exceptional that is required by the shell, for example. I quickly looked at the code (it's spread in too many separate locations to post here for reference). It does no other processing than trimming whitespace from beginning and end when reading from a profile. So there are paths that can't be specified in the profile file (but they should still be possible when specified on the command line directly!).

So: no escaping needed in the profile file; escaping needed on the command line, but this is required and processed by the shell - none of this escaping reaches Unison.

[gdt]

I squashed the three commits together, because I only want to merge clean history.

I did some experiments (on NetBSD) and found that while spaces (and tabs!) in the middle of the line are read, initial spaces and tabs and trailing spaces and tabs are dropped. A BEL (^G, 007) also worked. And, CR is dropped everywhere. I edited to reflect this more complicated situation (which I didn't understand before as I am someone who does not believe in putting spaces in directory names!) Some of this behavior seems perhaps buggy, and some happenstance, so the manual leaves most behavior outside the spec to avoid precluding cleanup.

I then force-pushed to your branch.

I did not dig into UTF-8.

@bunk3m This commit lists you as author, which I think is good because you did most of the digging and bringing this to our attention. Let me know if you think this is accurate and if you're ok with this result. Anyone else, the usual review is appreciated.

[tleedjarv]

I'm fine in general but the location in the manual is a bit difficult. The section is about paths and then all the examples are about the root preference. Of course, processing of paths and roots is the same, so nothing's factually wrong, just seems somewhat out of place. A separate subsection is probably the best, making it very clear that this applies to both roots and paths.

(No, I don't think it's bikeshedding because the "path" section in the manual is about a specific concept, not about fs paths in general. Also, since the manual does eventually need to be updated and overhauled, I would not want these interim additions make that future work more difficult.)

[bunk3m]

@bunk3m This commit lists you as author, which I think is good because you did most of the digging and bringing this to our attention. Let me know if you think this is accurate and if you're ok with this result. Anyone else, the usual review is appreciated.

Thank you and yes, it's OK.

This was great as this is my first contribution on github. I appreciate everyone's help in sorting it out. I'm happy to help again. Thank you!

[gdt]

I'm fine in general but the location in the manual is a bit difficult. The section is about paths and then all the examples are about the root preference.

I moved this to the section that introduces profile files.