define ciel-5am-user package, add doc to get local nicknames

fixes https://github.com/ciel-lang/CIEL/issues/81

docs/language-extensions.md

@@ -420,6 +420,36 @@ It is a drop-in replacement.
 
 Here's [uiop:define-package documentation](https://asdf.common-lisp.dev/uiop.html#UIOP_002fPACKAGE).
 
+### Packages local nicknames
+
+CIEL defines local nicknames for other libraries.
+
+For example, `csv` is a shorter nickname for `cl-csv`. `time` is a
+shorter nickname for `local-time`.
+
+They are available when you are "inside" the CIEL-USER package (when you do `(in-package :ciel-user)`).
+
+If you define a new package that "uses" CIEL, you might want to also
+get this set of nicknames. Here's the full list:
+
+~~~lisp
+(uiop:define-package myproject
+    (:use :cl :ciel)
+    (:local-nicknames (:/os :uiop/os)
+                      (:os :uiop/os)
+                      (:filesystem :uiop/filesystem)
+                      (:finder :file-finder)
+                      (:notify :org.shirakumo.file-notify)
+                      (:alex :alexandria)
+                      (:csv :cl-csv)
+                      (:http :dexador)
+                      (:json :shasht)
+                      (:json-pointer :cl-json-pointer/synonyms)
+                      (:time :local-time)
+                      (:routes :easy-routes))
+    (:documentation "My package, using CIEL and defining the same local nicknames."))
+~~~
+
 
 
 Pattern matching

docs/libraries.md

@@ -804,13 +804,15 @@ one. This check is done by looking at the `TERM` environment variable.
 
 The [FiveAM](https://common-lisp.net/project/fiveam/docs/) test framework is available for use.
 
-Below we create a package to contain our tests and we define the most simple one:
+CIEL defines a package `ciel-5am-user` that also "uses" all Fiveam symbols, in addition of all others.
+
+It's best to define your own test package for your application (see
+below), but you can start with this one.
+
+Here's how we define a very simple test:
 
 ```lisp
-(defpackage ciel-5am
-  (:use :cl :5am))
-
-(in-package :ciel-5am)
+(in-package :ciel-5am-user)
 
 (test test-one
   (is (= 1 1)))
@@ -873,12 +875,49 @@ Use `run` to not print explanations.
 
 You can use `(!)` to re-run the last run test.
 
+#### Interactive debugger on errors
+
 You can ask 5am to open the interactive debugger on an error:
 
 ``` example
 (setf *debug-on-error* t)
 ```
 
+#### Define your own test package, add local-nicknames
+
+Using only this built-in `ciel-5am-user` package won't be practical if
+you develop different applications at the same time in the same Lisp
+image. Just define a new package:
+
+```lisp
+(uiop:define-package myproject-tests
+   (:use :cl :ciel :5am))
+```
+
+This "uses" all CL, CIEL and Fiveam symbols.
+
+If you want all the local nicknames that are available in the CIEL
+package, copy the list below:
+
+~~~lisp
+(uiop:define-package myproject
+    (:use :cl :ciel)
+    (:local-nicknames (:/os :uiop/os)
+                      (:os :uiop/os)
+                      (:filesystem :uiop/filesystem)
+                      (:finder :file-finder)
+                      (:notify :org.shirakumo.file-notify)
+                      (:alex :alexandria)
+                      (:csv :cl-csv)
+                      (:http :dexador)
+                      (:json :shasht)
+                      (:json-pointer :cl-json-pointer/synonyms)
+                      (:time :local-time)
+                      (:routes :easy-routes))
+    (:documentation "My package, using CIEL and defining the same local nicknames."))
+~~~
+
+
 ### Logging (log4cl)
 
 <https://github.com/sharplispers/log4cl/>

src/packages.lisp

@@ -43,6 +43,30 @@
   (:export
    #:*script-args*))
 
+(uiop:define-package ciel-5am-user
+    (:use :cl :ciel
+          ;; one addition from ciel-user:
+          :5am)
+  (:local-nicknames (:/os :uiop/os)     ; let's try this nickname.
+                    ;; Simply :os doesn't help at auto-discovery with SLIME's autocompletion.
+                    ;; But let's add it anyways for correctness,
+                    ;; it's handy for the shell and scripts.
+                    (:os :uiop/os)
+                    ;; This other uiop module is always useful:
+                    (:filesystem :uiop/filesystem)
+                    (:finder :file-finder)
+                    (:notify :org.shirakumo.file-notify)
+
+                    (:alex :alexandria)
+                    (:csv :cl-csv)
+                    (:http :dexador)
+                    (:json :shasht)
+                    (:json-pointer :cl-json-pointer/synonyms)
+                    (:time :local-time)
+                    (:routes :easy-routes))
+  (:documentation "Same package as ciel-user, with the added symbols of fiveam, in order to define ad run unit tests."))
+
+
 ;TODO: a conflict between Serapeum and generic-cl
 (uiop:define-package generic-ciel
   (:use :generic-cl