search

realm / jazzy

Soulful docs for Swift & Objective-C
https://realm.io
MIT License
7.36k stars 413 forks source link

Update README.md: add ticks to ensure that commands work in zsh #1374

Closed richardtop closed 9 months ago

richardtop commented 1 year ago

Related issue: https://github.com/realm/jazzy/issues/1373

I've got confused because of the zsh errors and shell expansion. I've updated the examples in a way so that there is a better chance that they'll work for a beginner user.

johnfairh commented 1 year ago

I don't think that's a very natural way to use quotes; they're not part of the program's syntax.

You could add a para to the 'troubleshooting' section for beginner shell users? For zsh you could recommend the alias jazzy='noglob jazzy' trick.

richardtop commented 1 year ago

Could you please explain "not part of the program's syntax" ?

alias jazzy='noglob jazzy' what would this do and how would it work? Where to put this code (zprofile?)

Happy to make changes, just want to clarify these issues first.

johnfairh commented 1 year ago

The quote characters added are not part of jazzy's syntax, they're one of several techniques for avoiding unwanted shell expansion.

noglob turns off filename globbing in zsh. You could just type the command into a shell or I think .zshrc is the right place. Lots of zsh documentation out there! But it's not the place of a random tool's readme to tell users exactly how to use zsh or whatever shell they're using -- we just need a reminder that this kind of thing can interfere if you happen to be running Jazzy like this.

richardtop commented 1 year ago

Clear. Unfortunately, this took a lot of time for me to figure out. Jazzy doesn't give a clear understanding in it's error descriptions, in fact, it just continues to generate the documentation. I think it's very important to have these issues fixed, as this is basically a default use case. ZSH is the default shell on mac and of course people don't want to have just a single readme file as an article.

johnfairh commented 9 months ago

Doing in #1378.