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

HTML 58.27% Shell 0.54% Ruby 1.65% CSS 3.10% Common Lisp 1.91% JavaScript 33.98% Dockerfile 0.56%

common-lisp lisp introduction-to-lisp tutorial examples programming-environment

articulate-common-lisp.github.io's Introduction

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 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…

./livetest.sh

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…

./build.sh

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.

articulate-common-lisp.github.io's People

Contributors

Stargazers

Watchers

Forkers

jsmpereira kisom priyadarshan crashcoredump veddox salewski rockiger grimderp peroksid akanouras simendsjo alx-a qazwse nja

articulate-common-lisp.github.io's Issues

Cusp/eclipse walk through

Cusp may be the best IDE approach for a new user. Get it working and document this process & use.

Define licences

The source code and the documents need to be correctly licensed so that the code can be reasonably used and the documents can be contributed to, or if needful, both can be forked and continued without my permission.

Public domain?
Cc0?
LLGPL?
Agpl3?
GFDL?

Key questions: is it ok for this material to be reused without releasing the source? Is it ok to remix it without crediting authorship?

As a tutorial site, people need to be able to mooch snippets without qualms of having angry lawyers sue them. However, if the example work is substantial, then it shouldn't be crassly used without some reference to its originator. Further, the docs should not be copied and remixed as someone else's original work; it should be remixed as a derived work.

Tbd.

quicklisp setup

Walkthrough quicklisp setup, including LispWorks Personal not loading the ~/.lispworks file.

Include note on proxy

Formatting

The site looks ugly and ill justified. It needs to be visually more readable.

Add sbcl build info

Add info about building sbcl from source and why.

Goes in env:sbcl.md

clisp setup page

Work through clisp setup on

Windows
Linux
OSX

Just Use Roswell

Most problems can be solved by just installing Roswell

Add tutorial about lisp packages

I just got this pounded into my head on #lisp and it is very very different from other module/package systems (but awesome).

A newbie friendly tutorial should be made on this. I can't find one anywhere.

Authors file

I would recommend creating an authors file for the project since you have a few contributors.

While the same information is available via git (including contact info) I believe a lot of people would prefer to be able to just look at a text file that is updated when a new contributor contributes for the first time.

Investigate CCL for cross platform lisp.

CCL may be our only reasonable cross platform cl.

Needs:

Threading, drakma.

Wants: decent read line type interface.

Document how to load files and set up slime for CCL.

Thinking about site future

Hey @pnathan. I didn't know the best way to contact you on things like this, so I thought opening an issue would be fine.

Had a discussion on IRC today about what the lisp community needs. Check it out below. I think a slight consensus is a curated site like this is a good idea.

So from my point a view, the site needs to focus on getting some contributors and get auto-deploys for merges to master. Long term, a small group of maintainers rather than just you with the power to approve pull requests would be good.

Thoughts?

<mordocai> Btw, if anyone can contribute content to http://articulate-lisp.com that'd be great. I've
           been helping out a bit but my knowledge is limited. I think the purpose of the site is a
           valid need. Better information about the different implementations + some fleshed out
           project tutorials is what it most needs I think.
*** native_killer ([email protected]) has quit: Quit: Leaving                           [12:57]
* Shinmera has never seen that site before
<Shinmera> Blogging about it and getting said blog onto plent-lisp might get some attention.  [12:58]
<Shinmera> *planet-lisp
<eudoxia> it's on the r/lisp sidebar kek                                                      [12:59]
<eudoxia> ive only looked at it superficially
<hitecnologys> There's already cliki.net, why another site?
<mordocai> Yeah, I found it via /r/lisp. Noobies don't like cliki.net
<mordocai> Really not sure why
<Xach> I also don't like cliki.net.                                                           [13:00]
<Xach> I don't like it because it's ugly and chaotic.
<hitecnologys> Well, me neither, but doesn't that mean it needs improvements?
<Xach> I would like it more if it was not ugly and not chaotic.
<Shinmera> Same.                                                                              [13:01]
<resttime> "I'll just write my own" <- A frequent goto solution when it comes to lisp         [13:02]
<zwdr> lisp makes it easy though!
<Xach> I like some parts of it. The ansi corrections page is good. But if someone were to make that
       today, I'd suggest a google doc or something like that.
<eudoxia> yes, cliki is indeed horrible                                                       [13:03]
<hitecnologys> There isn't an alternative at the moment.
<hitecnologys> Maybe let's make something instead of saying how horrible it is?
<mordocai> I think the main problem is that AFAIK I can't make a pull request to fundementally
           change cliki. I already did that once with articulate-lisp
<Xach> The alternative is to not use it and not look at it.
<rpg> resttime, zwdr: that's how we end up with so many 70% solutions.
<zwdr> yea true                                                                               [13:04]
<hitecnologys> Xach: but we still need some place where we can aggregate stuff.
<resttime> Thank goodness quicklisp exists.
* eudoxia feels bad for abandoning https://github.com/eudoxia0/lisp-site
*** knobo ([email protected]) has quit: Ping timeout: 260 seconds
<Xach> hitecnologys: That would be great. It's too bad there's nothing like that already.
<hitecnologys> resttime: quicklisp doesn't have proper categories and neither does quickdoc.
*** Whymind ([email protected]) has quit: Read error: Connection reset by peer  [13:05]
<hitecnologys> resttime: and don't tell me that I don't need them because I usually end up in
               situations where I'm not sure what to look for so I open cliki and look at the list
               of software on appropriate page and compare them, then decide.
* mordocai asks #lisp                                                                         [13:06]
<mordocai> Cliki seems often out of date
<Shinmera> You can change the seems to is.
*** Whymind ([email protected]) has joined channel #lisp
<hitecnologys> Xach: I think I've become too spoiled. Now I can't tell whether you were sarcastic or
               not… =P                                                                        [13:07]
<Xach> hitecnologys: I'm not being sarcastic. I don't like cliki.net and I don't think it's worth
       using for any current problem.
<Xach> Other people can work on it if they like. I'm not going to do it.                      [13:08]
<mordocai> So like, is something like articulate-lisp (curated by pull request/one maintainer) what
           we need? Or do we need a better wiki?
<Xach> I like the idea of something curated. Execution can always be a stumbling block.       [13:09]
<hitecnologys> I'm not so sure that wiki is what we need.
<eudoxia> i think a website like scala-lang.org (well designed, advertises language's strengths)
          plus a wiki is what's needed                                                        [13:10]
<hitecnologys> So I'd vote for something being centrally controlled by a small publicly elected
               committee.
<Shinmera> I've been thinking about something like a wiki but using a versioning system as a
           backend.
<Xach> I think "publicly elected committee" is a kiss of death.
<hitecnologys> Xach: but it has hope.
<eudoxia> as in, waiting for consensus to form before acting?                                 [13:11]
<Shinmera> hitecnologys: Committees are slow and you'll always get a good chunk of people who'll
           immediately shoot it down because they don't like the electives.
<zwdr> Mmmh, I wrote a small wiki that simply uses the FS
<zwdr> so if you add the folder to git its versioned
<zwdr> I believe thats a good approach
<zwdr> instead of reinventing versioning
<hitecnologys> But uncontrolled wikis are a good way to end up in the garbage dump. We need some
               group of people who would manage it anyway.
<eudoxia> show of hands, how many people here have their own lisp-backed personal wiki :)
<Shinmera> The versinoning system thing would be neato because you could have branches for people's
           changes and thus have only one public version that might be checked by some.
<Shinmera> *versioning
<zwdr> eeh--it's scheme eudoxia :D                                                            [13:12]
<mordocai> eudoxia: Bunch of org files count?
<eudoxia> mordocai: no
<mordocai> Then nope
<hitecnologys> eudoxia: I had a project like that once but I shut it down due to lack of time to
               work on it.
*** lispyone_ ([email protected]) has joined channel #lisp        [13:15]
*** nikki93 ([email protected]) has joined channel #lisp
*** runneypo ([email protected]) has quit: Read error: Connection reset by peer             [13:16]
<mordocai> I wonder how arch wiki does it. Nearly always top notch information.
*** plato_14 ([email protected]) has joined channel #lisp                                   [13:17]
<zwdr> same with the gentoo wiki
*** NeverDie ([email protected]) has quit: Quit: http://radiux.io/ ->
    Manhattan Project
*** nyef ([email protected]) has quit: Ping timeout: 264 seconds
                                                                                              [13:19]
*** kushal (~kdas@fedora/kushal) has quit: Ping timeout: 260 seconds
<Xach> at a guess, lots and lots and lots of people involved.                                 [13:20]
*** hrs ([email protected]) has quit: Quit: My MacBook Pro has gone to sleep. ZZZzzz…
<Xach> low-ish barrier to entry, a path to progressing in levels of contributions, mostly unified
       user community, etc
*** NeverDie ([email protected]) has joined channel #lisp             [13:21]
<Xach> will wright gave a nice talk about the pyramid of contributions to The Sims. there were
       millions of users (the base of the pyramid), and some fraction of those decided they wanted
       to customize the game a little, and some fraction of that fraction decided they wanted to do
       more, and so on.
<Xach> that was one aspect of a really interesting talk about many topics
*** earl-ducaine ([email protected]) has joined channel #lisp                             [13:22]
<Xach> common lisp has many different groups with their own, completely valid, agendas, priorities,
       etc. none of which is particularly large in the absolute sense.
*** zygentoma ([email protected]) has joined channel #lisp
*** NeverDie ([email protected]) has quit: Max SendQ exceeded         [13:23]
<Xach> with common lisp, any energetic weirdo can, on their own, do a great deal of good. or harm.
<Xach> it's better if you have a large pool of potential weirdos                              [13:24]
*** eazar001 ([email protected]) has joined channel #lisp
*** shookees (~shookees@unaffiliated/doublestring) has quit: Remote host closed the connection
<Xach> and also helps if they tend to be more good than harmful, on average
*** varjagg ([email protected]) has joined channel #lisp                    [13:25]
*** eazar001 ([email protected]) has quit: Read error:
    Connection reset by peer
*** eazar001 ([email protected]) has joined channel #lisp
<eudoxia> can confirm, am spooky energetic weirdo                                             [13:26]
*** futpib ([email protected]) has joined channel #lisp
<mordocai> Yeah, I feel like despite the problems with it our best bet is a linux-style group (one
           dictator for life, with subordinates nomiated by him/her) and a curated site.
<mordocai> nominated*
*** NeverDie ([email protected]) has joined channel #lisp             [13:27]
*** dkcl (~user@unaffiliated/dandersen) has joined channel #lisp
*** rpg ([email protected]) has quit: Quit: rpg
*** kushal (~kdas@fedora/kushal) has joined channel #lisp                                     [13:28]
*** plato_14 ([email protected]) has quit: Ping timeout: 260 seconds                        [13:33]
#lisp>

Minor design considerations

The site looks nice, but I guess it would be even better if the navigation items in the top menu had friendlier labels (instead of ids, page titles).

For example, instead of "env" write "Development environment", instead of "new-project" write "Creating a new project in Common Lisp" etc.

Also I guess it would be nice if the text body was a little bit not so wide, this could make reading easier.

Implementations aren't "systems"

«Common Lisp implementations usually are called “systems”» says env/lisp-systems.html

That's the first time I hear of implementations called "systems". They are usually "implementations", or when the OS (and optionally CPU) is also specified, "platform". I would remove that remark and rename the page.

A link from implementation to implementation-specific page in that page would be nice.

HTTPS error

When I attempt to visit https://articulate-lisp.com/ in my browser (Tor Browser), I get -

[...] The certificate is only valid for the following names: *.github.com, github.com
 
Error code: SSL_ERROR_BAD_CERT_DOMAIN

Reading a text file snippet is too convoluted ?

Indeed, it turns out we have uiop at help:

(uiop:read-file-string "file.txt")

or read-file-lines,

when your snippet is longer (http://articulate-lisp.com/examples/snippets.html, bottom)

ABCs page

Demonstrate how to load a file with CLISP.

Create small and easy example. Perhaps downloading a web page with DRAKMA and regexing with CL-PPCRE?

about LispWorks not loading the init file

You write

I’ve found that Lispwork’s Personal 6.0 doesn’t appear to respect the Lispworks init file, so the init file (used for Quicklisp) has to be loaded manually with the form (LOAD "~/.lispworks"). I’m not sure why this happens, but I wish it wouldn’t!

http://articulate-lisp.com/ides/lispworks-setup.html

Looks like it is one of the limitations of the free version. They write

Initialization files are not loaded.

http://www.lispworks.com/downloads/index.html

Running the livetest.sh script produces an error

I am running this on Fedora 37 and when I run ./livetest.sh I get the following output:

ruby 3.1.1p18 (2022-02-18 revision 53f5fc4236) [x86_64-linux-musl]
jekyll 4.2.2 -- Jekyll is a blog-aware, static site generator in Ruby

Usage:

  jekyll <subcommand> [options]

Options:
        -s, --source [DIR]  Source directory (defaults to ./)
        -d, --destination [DIR]  Destination directory (defaults to ./_site)
            --safe         Safe mode (defaults to false)
        -p, --plugins PLUGINS_DIR1[,PLUGINS_DIR2[,...]]  Plugins directory (defaults to ./_plugins)
            --layouts DIR  Layouts directory (defaults to ./_layouts)
            --profile      Generate a Liquid rendering profile
        -h, --help         Show this message
        -v, --version      Print the name and version
        -t, --trace        Show the full backtrace when an error occurs

Subcommands:
  compose               
  docs                  
  import                
  build, b              Build your site
  clean                 Clean the site (removes site output and metadata file) without building.
  doctor, hyde          Search site and print specific deprecation warnings
  help                  Show the help message, optionally for a given subcommand.
  new                   Creates a new Jekyll site scaffold in PATH
  new-theme             Creates a new Jekyll theme scaffold
  serve, server, s      Serve your site locally

I've already verified that docker runs correctly. Is this a bug or am I just doing something wrong?

Create jekyll build

The current content gives a handle into where I'm going with A-L. For simplest operation, I think a static site generated from the extant markdown docs is reasonable. So a jekyll build script should be developed; this will be then pulled down by the articulate-lisp.com server, built and rsynced to the web location.

@yogthos - do you have a working jekyll install? my home Linux box is being rebuilt. :-(

System recommendations

My own uiop:run-program is IMNSHO much easier to use and much more powerful than external-program. Or inferior-shell, for a higher-level interface to the same functionality, with an alternative to string interpolation, etc.

I've never used cl-csv, but I admit I'm slightly jealous it was chosen instead of my fare-csv. Not jealous enough to dig in and work towards library unification, though.

For cl-ppcre, I find that optima-ppcre is often a much better interface to the same underlying library.

Instead of metabang-bind and the endless variations on the idea, necessarily incomplete, I prefer uiop:nest which allows to reuse existing binding forms and is thus complete by construction.

I don't condone anaphora. It is generally considered bad style, as opposed to explicit binding forms, e.g. if-let vs aif.

I'm glad you didn't include cl-fad in your list of systems; I consider my uiop to be a higher-quality replacement for the same functionality.

Improve snippets.

From a reddit comment: someone wished that they had snippets for: 'macros, loop construct, multiple dispatch, restarts (maybe), lambdas of course, before and after etc.'

I would classify these into 3 levels based on difficulty:

intro - macros, loop, multiple dispatch, lambda
intermediate - :before, :after
advanced - restarts.

Probably should move these into their own page.

Fixup some syntax

Referencing pull request #19 .

missed a newline at https://github.com/pnathan/articulate-common-lisp/pull/19/files#L0R109

Checked in http://articulate-lisp.com/devel/initial:new-project.html and ls code block is messed up.

And a missing parens at https://github.com/pnathan/articulate-common-lisp/pull/19/files#L0R96 sigh

Add method-combinator snippet

Create a snippet to demonstrate method-combinations.

Suggestions:

initialize-instance
validation

Add page about garbage collection

A general garbage collection page seems useful. This could explain what garbage collection is and give an overview of the different possible approaches and common issues. Particularly useful to people who haven't programmed in dynamic languages much/at all. This could also be a place to talk in very general terms about how different lisps (Not different common lisp implementations) handle garbage collection.

Link fixup

Hyper references need to be turned into hyperlinks.

Landing page cleaned up

The index.md is not a good landing page.

Do we really have to write html ? Where to write content ?

Hi,
finally I got quicklisp and slime working, thanks to this website :)
I forked this repo. It's done with Jekyll. But I can't find markdown content. Nor can I find a "gh-pages" branch. Where the heck can I find the content files ? I see html files with a yaml frontend… do we have to write html ?

thanks

Choosing your Lisp has very few links

Choosing your Lisp page links just to SBCL, I think that it would be nice if the table had links to the corresponding web sites, for example, in the Name column.

LispWorks looksee.

lisp works needs to be walked through as an IDE. Maybe add screenshots?

Add snippet for conditions/restarts

Add a condition/restart example for standard try/catch/finally behavior.

Add ASDF tutorial

ASDF was a pain in the butt to bootstrap myself with quickly.

Add a tutorial and a sample ASDF system (CC0 license).

Can't use filenames containing colons on Windows

After cloning the repo I can't see any of the env:XXX files because filenames on Windows can't contain colons.

Convert a-c-l to Jekyll

Articulate common lisp is in a custom static site builder. This inhibits extension and contribution.

CUSP all dead links, Dandelion Eclipse plugin

Hello,

the CUSP / Eclipse plugin page would need an update.

There seems to be an active Eclipse plugin: https://github.com/Ragnaroek/dandelion

Quickproject

How about some mention to Xach's Quickproject for new-project section?

Along with Quicklisp's local-projects functionality I find it the fastest way to get started hacking.

Include Roswell? Very welcoming for newcomers.

Thanks for this very helpful guide. Would you consider including a brief pointer to Roswell?

Given that it's 2017, some may consider that downloading tar.gz files, configure and make are less than optimal ways to try out a new language. Of course, it's quite helpful at some later point to understand how to build various implementations from source code, but it may not be what newcomers are expecting.

Roswell is easily installed on all platforms, including Windows. (This guide currently asks for help with Windows instructions, so Roswell may help fill this gap.)

It allows users to install and switch to various implementations as easily as ros install sbcl, ros install ccl, then ros use sbcl etc. This is also quite helpful for newcomers who may want to try various implementations. (Though I imagine most newcomers would rather have a single recommended implementation.)

Hope this helps, and thanks again.

highlighting of source code

The source code right now just refers to raw code. It would be nice if syntax highlighted versions of this source existed.

Implementation description

Environment is better than "system", but I would still say "implementation".
Traditionally by "environment", one includes Emacs + SLIME + entire toolchain.

Descriptions are off.

I would qualify SBCL as "Highest speed. Great on Linux, Good on OSX, passable on Windows". The compiler itself is the slowest. It's the code it produces that's fast.

For CCL, I'd write "High speed code. Great on Linux, OSX, Windows. Commercial support."

For CLISP, I'd write "Most compact code. Most portable. A bit quaint. Not actively maintained." Base: bytecode.

For LW and Allegro, I'd write "High speed. Great on Linux, OSX, Windows. Proprietary platform."

Or I'd make a grid for how fast the code is, how well each OS is supported, whether it's free software, whether there's commercial support.

articulate-common-lisp / articulate-common-lisp.github.io Goto Github PK