Add recipes for additional packages README in private/local dir

[dalanicolai]

Add detailed info for how to use additional packages as the (online) documentation for how to use single local packages is lacking. See issues #13180, #8421 and #2278

Thank you for contributing to Spacemacs!

Before you submit this pull request, please ensure it is against the develop branch and not master.

Add detailed info for how to use additional packages as the (online) documentation for how to use single local packages is lacking. See issues #13180, #8421 and #2278

Thank you <3

[duianto]

Here are some possible minor changes:

diff --git a/private/local/README.md b/private/local/README.md
index 2277a43af..52463da5b 100644
--- a/private/local/README.md
+++ b/private/local/README.md
@@ -7,22 +7,23 @@ the `dotspacemacs-additional-packages` variable of your dotfile.

Additional packages can be added using the same recipe as for [adding packages to layers](https://develop.spacemacs.org/doc/LAYERS.html#packagesel) i.e.:

-- if the package is on (M)ELPA simply add the package name to the list
+- If the package is on (M)ELPA simply add the package name to the list.

-- for a local package add `(some-package :location local)` to the list and load or
-  require it explicitly in the user/config section. The first part only adds the
-  package directory (i.e. .emacs.d/private/local/package-dir/) to the load path
-  so that the .el file should be placed inside the package directory. If the
-  package provides a feature it can be loaded with require, otherwise it must be
-  loaded using load.
+- For a local package, add `(some-package :location local)` to the list and load
+  or require it explicitly in the `dotspacemacs/user-config` section. The first
+  part only adds the package directory to the load path:
+  i.e. `.emacs.d/private/local/package-dir/`
+  Therefore the `.el` file should be placed inside the package directory. If the
+  package provides a feature, then it can be loaded with require. Otherwise it
+  must be loaded using `load-file`.

-- for a package hosted on github the recipe for github packages can be used i.e. add
+- For packages that are hosted on GitHub, use the recipe for GitHub packages by
+  adding the following to the `dotspacemacs-additional-packages` list:

-(some-package :location (recipe
-:fetcher github
-                             :repo "some/repo"))
+(some-package :location (recipe :fetcher github
+                                :repo "some/repo"))

-to the list. This will fetch the package on every startup, this can be
-prevented by installing the package locally as described in the previous point.
+This will fetch the package on every startup, this can be prevented by
+installing the package locally as described in the previous point.

Questions

• The sentence:

If the package provides a feature it can be loaded with require, otherwise it must be loaded using load.

Is using load referring to using load-file?
If yes then it might be clearer to spell it out.

If the package provides a feature, then it can be loaded with require. Otherwise it must be loaded using load-file.

• The last paragraph doesn't seem to be correct, or maybe I'm missing something?

This will fetch the package on every startup, this can be prevented by
installing the package locally as described in the previous point.

When I install a package using the GitHub recipe:

     (evil-repeat-motion :location (recipe :fetcher github
                                           :repo yyoncho/evil-repeat-motion))

Then the package only gets installed once, it doesn't try to install it again on the next restart.

[dalanicolai]

Thanks for the review and sorry for the late reply. Except for the change from load to load-file, I agree with all the suggested modifications.

About your first question, I guess load and load-file can both be used. However, the important point is that is can be done by adding it to the body of the dotspacemacs/user-config function. Referring to load-file might suggest that is should be done interactvely. But I think it should be stated more explicitly that the load should be placed also in the body of the dotspacemacs/user-config function.

About the loading every time on startup, it seems that you are right that it is installed only once. However I remember that the org-server had some problems the day before I created this pull request, and because of that starting spacemacs took very long as the initialization was hanging on trying to reaching that server, even though I was just connecting to the emacsclients (if I remember well not sure about this... btw I mentioned the slow startup on gitter where Grant Shangreaux confirmed that he also experienced this issue). Anyway, I concluded that fetching packages form servers was not an ideal approach although fetching from github might be handled differently than the fetching of org-packages.

[smile13241324]

@dalanicolai I have just checked your PR for merging and noticed that the changes @duianto requested have not yet been done though your second commit message suggests that way.

Please kindly check his comments and adjust your PR accordingly.
Please also squash your commits and rebase your branch on develop.

[duianto]

The first part should probably be clarified what it's referring to.

And the mention that load and require should be declared in the dotspacemacs/user-config section is mentioned twice. It's enough to mention it once.

[duianto]

Maybe the README.md could say something like the text below the horizontal line:

This was written in the list item starting with for a local package add:

The first part only adds the package directory (i.e.
.emacs.d/private/local/package-dir/) to the load path. The .el file should be
placed inside this package directory.

But I'm not sure what The first part is referring to.

---

Private directory for local packages

The content of this directory is ignored by Git.

This is the place to store the local packages that you define in the
dotspacemacs-additional-packages variable of your dotfile.

Additional packages can be added using the same recipe as for adding packages to layers i.e.:

• if the package is on (M)ELPA, then simply add the package name to the
  dotspacemacs-additional-packages list.

• for a local package add:

(some-package :location local)

to the dotspacemacs-additional-packages list.

Then in the dotspacemacs/user-config function in your dotfile:

• If the package provides a feature, add:

`(require 'package-name)`

• otherwise load the package with:

(load "package-name")

• for a package that's hosted on GitHub, use the recipe for GitHub packages,
  i.e. add the following to the dotspacemacs-additional-packages list:

(some-package :location (recipe
                         :fetcher github
                         :repo "some/repo"))

[smile13241324]

As wished closed in favor of #13381.