Straight.el: Add "how-to" guides to documentation

[ghost]

It'd be nice for me to have a list of common tasks and how to do them. This is like the inverse of the "what each command does" style of documentation which is already present. For example I'm not currently sure which combination of pull/rebuild/use I need to use in order to upgrade a package.

Some instances:

• How to upgrade a package
• How to get a specific package version
• How to remove a package
• How to update my list of packages
• How to change my package sources
• other common tasks...

[raxod502]

That sounds like a good idea; thanks for suggesting it. Although I don't have the time right now to make the relevant changes, I can answer briefly here:

• Upgrading is M-x straight-pull-package.
• Checking out a particular revision should be done manually using git checkout or git reset. If you want to reset to the revision listed in your lockfile, run M-x straight-thaw-versions.
• Removing a package is not an operation that exists in straight.el, since there is no concept of "installed packages". Simply remove the straight-use-package invocation from your init-file, and the package will not be made available. If you wish for it to be removed from disk also, you can delete it manually. (The only reason to do this would be to save disk space.)
• By "update my list of packages" I am guessing you mean fetch updates to MELPA et al. That is done the same way as upgrading a package, since recipe repositories are just regular packages.
• By "change my package sources" I am guessing you mean change which recipe repositories are used to fetch recipes, and in which order. That is done by customizing straight-recipe-repositories. Unlike package.el, straight.el comes with a sane configuration for package sources out of the box, so I'm curious about what you want to change—perhaps it should be done by default?

Note also:

• You should never have to invoke M-x straight-rebuild-package, unless something has gone wrong.
• Invocation of straight-use-package usually happens during init, or interactively to test out a package temporarily. It is totally orthogonal to repository management (upgrades, etc.).

In general you will find that some operations in package.el do not have analogues in straight.el and vice versa, due to differences in package management philosophy. If that is what is leading to your confusion, perhaps the Conceptual overview section will help.

I appreciate any suggestions on how the documentation or user interface might be improved, as this is a difficult problem.

[wedens]

How do I keep package versions in sync on multiple computers?

Currently I do the following when I want to upgrade all packages and have the same versions on computers A and B:

Computer A:

• straight-pull-all
• straight-freeze-versions

Computer B:

• obtain new version of the lockfile
• straight-fetch-all
• straight-thaw-versions

Is it correct workflow?

It's a bit unclear what'll happen when straight-thaw-versions is used, but there is no such commit in some repo (e.g. if I don't use straight-fetch-all before ). I'd expect an error or attempt to fetch a repo and try to do a checkout again.

[ghost]

Upgrading is M-x straight-pull-package.

Invocation of straight-use-package usually happens during init, or interactively to test out a package temporarily. It is totally orthogonal to repository management (upgrades, etc.).

Is straight-pull-package intended for upgrading interactively? Or do I need to follow that with straight-use-package or restarting emacs? (I usually run emacsclient and the daemon to avoid startup time.)

[raxod502]

@wedens

How do I keep package versions in sync on multiple computers?

The process you described is exactly right.

I'd expect an error

That's what happens.

or attempt to fetch a repo and try to do a checkout again.

That's what I'd _like_ to happen; see #58. _(Update: this is what happens now!)_

@apnewberry

do I need to follow that with straight-use-package or restarting emacs?

While technically you could cause the updated version of the package to be made available by invoking M-x straight-use-package or by reloading your init-file, this would probably not have the effect you intended. If a library is already loaded, then it won't be loaded again. Even if you caused it to be loaded again by finding the file and evaluating it manually, the old and new versions of the code could interfere with one another. You should restart Emacs after updating packages.

(Before using M-x straight-use-package to re-load a package, see https://github.com/raxod502/straight.el/issues/122. You should really be reloading your entire init-file whenever you change package configuration.)

[AndersonTorres]

Hello, guys! I'm @AndersonTorres, and I'm very interested in helping that project!

To the point: As a matter of, huh, style?, I think the @apnewberry is suggesting not a howto per se, but something more akin to a _cookbook_.

In a cookbook, we can insert use cases, more or less related to each other. A good, albeit mininmal, example would be the Sed One Liners

On the other hand, howtos are more dense and concentrated in a single subject - something like "how-to configure your infrared joystick in Linux", or "How to configure a full-featured C++ programming environment in Emacs".

I think it could be a good start for a community-driven documentation, something less strongly tied to the main straight.el project.

What do you think?

[raxod502]

I am open to whatever documentation format people would find useful. I think the main thing that is missing currently is:

• quick reference for simple operations that people want to know how to do, and
• example code showing how you use straight.el

something less strongly tied to the main straight.el project.

I tried that in the straight.el support repository, but it didn't age well. I think putting it in the main repository would work better, and that's what I intend to do.

I am fine with some parts of the project being less formal than others. See e.g. straight-x.el that has random user-contributed functions which don't have any particular documentation or functionality guarantees, but are nevertheless quite nice and helpful.