Pure: When using zplug, `prompt` prints usage, does not include pure

[ELLIOTTCABLE]

General information

• Pure version: HEAD
• ZSH version: 5.3.1
• Terminal program & version: Hyper 1.3.3
• Operating system: macOS High Sierra 10.13
• ZSH framework: zplug

I have:

• [x] Tested with another terminal program and can reproduce the issue:
• [x] Followed the Integration instructions for my framework

Problem description

The zplug ‘Integration’ section doesn't make it clear whether the autoload -U promptinit; promptinit; prompt pure lines are still necessary.

They don't seem to be, because I get the following output on startup if I include them,

Usage: prompt <options>
Options:
    -c              Show currently selected theme and parameters
    -l              List currently available prompt themes
    -p [<themes>]   Preview given themes (defaults to all)
    -h [<theme>]    Display help (for given theme)
    -s <theme>      Set and save theme
    <theme>         Switch to new theme immediately (changes not saved)

Use prompt -h <theme> for help on specific themes.

… and prompt -l doesn't include “pure”; but Pure still seems to load and work just fine.

While we're on a documentation kick, I'd also like to point out that including an ‘integration’ section that is separate from the ‘installation’ section — and separated by an intervening ‘configuration’ section — is very confusing. Maybe consider moving the ‘integration’ section into the body of the ‘installation’ section, because those instructions seem to replace the other ‘installation’ instructions?

Also see: zplug/zplug#425.

---

IssueHunt Summary

bricewge has been rewarded.

Backers (Total: $20.00)

• issuehunt ($20.00)

Submitted pull Requests

- #494 Simplify the setup phase in the readme

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
  

  - Need some help from other developers? Add your repositories on IssueHunt to raise funds.

IssueHunt has been backed by the following sponsors. Become a sponsor

[ELLIOTTCABLE]

On a related note, the ‘example’ section seems to imply that the configuration options need to be included between promptinit and prompt pure (although this, again, isn't explicitly documented) — and how to use them in the context of zgen, zplug, etc is, say it with me now … undocumented!

Let me know if I can help. ☺️

[mafredri]

Thanks for opening up this issue, documentation updates / clarifications are very essential.

Maybe consider moving the ‘integration’ section into the body of the ‘installation’ section, because those instructions seem to replace the other ‘installation’ instructions?

Hmm, I don't think you're wrong about the clarity issue, but I think integration is less important than installation & configuration and thus I do not want to have it before. Furthermore, it takes up way too much vertical space to be included before configuration 😕.

Maybe a section in Installation mentioning to skip to Integration if using a zsh framework?

On a related note, the ‘example’ section seems to imply that the configuration options need to be included _between_ promptinit and prompt pure (although this, again, isn't explicitly documented) — and how to use them in the context of zgen, zplug, etc is, say it with me now … undocumented!

Order doesn't matter, and I'm not opposed to moving the configuration option before promptinit if that makes things clearer. Although all Pure options should support being changed at any point (at runtime), this is not a guarantee we currently provide, as such it is safest to set them before. I'm against documenting how to use different zsh frameworks though, it's enough if we let people know how to load Pure in them, configuration is their responsibility.

A PR would be very welcome if you have a clear idea of how to improve the readme, considering the above @ELLIOTTCABLE 😊.

[ELLIOTTCABLE]

Might hit that edit-on-GitHub button when I get home, if I have a second, sure!

Before I go making changes, how about a Markdown ‘table?’ That reduces the vertical space, and perhaps makes the landing-README look a little more professional. That would allow for including all of the plugin systems directly below the manual installation instructions.

Alternatively, a pretty, syntax-highlighted image, inlined into the README, allows direct control of the vertical space, layout, etceteras — less-accessible, though, which I'm not in love with.

Finally, quite possibly the most user-friendly option, is auto-detecting and auto-configuring based on the user's plugin manager: npm install --global pure-prompt && pure-prompt --configure prints instructions for whatever plugin-manager is detected. That might be significant work, though; and some users will still want to manually configure. ¯\_(ツ)_/¯

[mafredri]

@ELLIOTTCABLE apologies it's taken me this long to get back to you!

Before I go making changes, how about a Markdown ‘table?’ That reduces the vertical space, and perhaps makes the landing-README look a little more professional. That would allow for including all of the plugin systems directly below the manual installation instructions.

It doesn't sound like a bad idea, if you have a good idea for the structure, go ahead 👍.

Alternatively, a pretty, syntax-highlighted image, inlined into the README, allows direct control of the vertical space, layout, etceteras — less-accessible, though, which I'm not in love with.

I think accessibility (being able to highlight text, etc) is more important, I prefer the table idea.

Finally, quite possibly the most user-friendly option, is auto-detecting and auto-configuring based on the user's plugin manager: npm install --global pure-prompt && pure-prompt --configure prints instructions for whatever plugin-manager is detected. That might be significant work, though; and some users will still want to manually configure. ¯_(ツ)_/¯

I'm not so sure about auto-configuring, but auto-detect + provide instructions might be nice, not sure. A PR for this would also be welcome 😉.

[Jerome1337]

I have exactly the same problem en Arch linux fresh install.

[mafredri]

@Jerome1337 this issue is about documentation, not a place for issue reports. Please open a new issue and describe your problem.

[IssueHuntBot]

@issuehunt has funded $20.00 to this issue.

---

• Submit pull request via IssueHunt to receive this reward.
• Want to contribute? Chip in to this issue via IssueHunt.
• Checkout the IssueHunt Issue Explorer to see more funded issues.
• Need help from developers? Add your repository on IssueHunt to raise funds.

[bricewge]

When using zplug, prompt prints usage, does not include pure

I had the same issue with zplugin, tweaking the relevant integration section to the following solved it:

zplugin ice pick"async.zsh" src"pure.zsh" \
  atclone"ln -s ./pure.zsh prompt_pure_setup" atload"fpath+=(\$PWD)"
zplugin light sindresorhus/pure

So I'm guessing that this should also work for zplug, if it adds pure to $fpath somehow:

zplug mafredri/zsh-async, from:github
zplug sindresorhus/pure, use:pure.zsh, from:github, as:theme, \
  hook-build:"ln -s ./pure.zsh prompt_pure_setup"

At the heart of this issue is the use of non standard file names in the repo:

The first step for adding your own theme is to choose a name for it, and create a file ‘prompt_name_setup’ in a directory in your fpath

So one way to fix it would be to update the integration part of the README for each package manager to be sure that they add pure's path to $fpath and create a symlink named prompt_pure_setup. It won't be need for prezto and zim because they aren't affected. But I don't like this solution since the effort has to be duplicated for each package manager.
The solution that seems less hackish to me but may break compatibility is to follow the correct naming scheme, ie. ./pure.zsh is renamed to ./prompt_pure_setup and ./pure.zsh became a script that adds the repo to $fpath, load promptinit and apply the prompt. It would also allow us to reduce to a minimum the README section about manual installation to a minimum since all the logic would go in the new ./pure.zsh.

I'm willing to write a PR for it when have decided which solution is better.

[mafredri]

@bricewge related https://github.com/sindresorhus/pure/pull/419. The idea would be to place symlinks (or files that source) in a subfolder called fpath with the appropriate names. Users could download the whole repo as a zip, unpack it, and set fpath+=(/path/to/extracted/pure/fpath).

[bricewge]

That's very nice to see that a PR was already written based on this idea!

[issuehunt-app[bot]]

@sindresorhus has rewarded $18.00 to @bricewge. See it on IssueHunt

• :moneybag: Total deposit: $20.00
• :tada: Repository reward(0%): $0.00
• :wrench: Service fee(10%): $2.00