articulate-common-lisp / Articulate Common Lisp.github.io

• articulate-common-lisp

docs/specs for a tutorial/introduction site for a Common Lisp environment

** Dear Reader,

One of the key problems in onboarding developers to use modern Common Lisp is the vertical wall of difficulty. Things that are routinely problematic:

• emacs use. Most people don't use emacs.

• Library creation. Putting together ASDF libraries and using them is a fairly horrid experience the first time.

• Selection of Lisp system to use, along with an up-to-date discussion of pros and cons.

• Putting together serious projects is not commonly discussed.

This repository is the source code to build a Common Lisp site dedicated to handling these problems. My goal is to put together an introduction/tutorial for practicing professionals and hobbyists from other languages. People who want to get started with Lisp beyond just typing into a REPL. Right now, it feels like this information is less disseminated and much less centralized than it otherwise might be. It's not intended to be a HOWTO for Common Lisp. That's been covered quite well. But it is intended to be a HOWTO on how to put together a Lisp environment.

Anyway, I'd like to collaborate with other people to build a remarkably fine Lisp help site. Contributions are both accepted and welcome. It's a wholly static site at this point in time - I don't see a need for articulate-lisp.com to have a dynamic backend. Perhaps/probably one of the code examples will be a webapp.

Happy Hacking,

Paul Nathan

P.S.: feel free to contact me for anything you like.

** Making Contributions.

Please send in pull requests or issues!

Each pull request is vetted to correctly compile in Jekyll; this is then logged on Github and has to pass for a pull request to be mergable to master.

We use [[https://github.com/orthecreedence/highlight-lisp][highlight-lisp]] for syntax highlighting. Just add a =lisp= class to your code samples.

** Notes regarding build process.

Articulate Common Lisp is super-heavy on Docker (http://docker.com/). Docker is used for doing builds, as well as the vehicle of deployment. This is because we think it's simpler than having to install all sorts of other dependencies and keeping them up to date.

This is a Jekyll site; therefore existing build scripts use Dockerized Jekyll to do the build.

If you run this...

 #+BEGIN_EXAMPLE
 ./livetest.sh
 #+END_EXAMPLE

You will have a hot-rebuilding Jekyll server running on http://localhost:4000. Hit Ctrl-C to stop it. This is very useful for contributing content!

If you run this...

#+BEGIN_EXAMPLE ./build.sh #+END_EXAMPLE

You will then have the Jekyll compile occur, then the Docker instance build.

This is the process used to deploy new versions onto Docker Hub; these are then downloaded onto the VPS and started up.

** License information & legalities.

My opinion on articulate-lisp.com's licensing is this: it should be easy to grab bits and pieces and easy to fork if the author disappears. After some careful reading, I selected...

• GPL3 for the documentation itself.

• Snippets and other samples embedded in the documentation should be considered public domain a.k.a CC0.

• The full-size examples in examples/src/ are more substantial and, are licensed as AGPL3. This is denoted in their comment header.

I do not believe that these terms are onerous and I have sought to structure them to permit both free use of small things and continuity of information.

AGPL3 is a very strict copyleft license and I feel obligated to justify its choice.

Simply put, I believe that software developers have a moral obligation to allow their users to repair the software that they provide. This facility is usual for physical items: we can fix our bikes, chairs, cars, etc. I believe that we ought to let our users fix the software they use, or hire other people to make that fix. I also have profound issues with the software patent industry. AGPL3 is the best license I know of to ensure that what I create gives users these capabilities and will not be patented. As these are ridiculously small examples, I am fairly positive that any serious work will not use them. So it should not be onerous on you.

If your corporate lawyers refuse to let example AGPL3 code exist in your development environment, please write in and - for my part - I will make a good faith effort to negotiate with you for you a less strict license for your company.