You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.org
+16-24Lines changed: 16 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ docs/specs for a tutorial/introduction site for a Common Lisp environment
8
8
9
9
One of the key problems in onboarding developers to use modern Common Lisp is the vertical wall of difficulty. Things that are routinely problematic:
10
10
11
-
- emacs use. Most people don't use emacs.
11
+
- emacs use. Most people don't use emacs.
12
12
13
13
- Library creation. Putting together ASDF libraries and using them is a fairly horrid experience the first time.
14
14
@@ -19,7 +19,7 @@ One of the key problems in onboarding developers to use modern Common Lisp is th
19
19
20
20
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*.
21
21
22
-
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.
22
+
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.
23
23
24
24
Happy Hacking,
25
25
@@ -30,48 +30,40 @@ P.S.: feel free to contact me for anything you like.
30
30
31
31
** Notes regarding build process.
32
32
33
-
Various site building tools are out there; I wanted one that was, above all, simple. Initially Jekyll was chosen,
34
-
but Ruby proved contentious, and frankly, I wanted to ship the site. Pandoc was really easy to use and install on my
35
-
OSX boxes. With a bit of hackery on the templates, I could generate a very nice page. With a bit more hackery,
36
-
`make.lisp` got created, which included snippets automatically, as well as have a simplistic 1-level hierarchical
37
-
menu for sections of the site based on filename. I use SBCL as the Lisp system for make.lisp.
33
+
This is a Jekyll site; the existing build scripts use Dockerized
34
+
Jekyll for sandboxing.
38
35
39
-
You can see this in action in the makefile for the system.
40
-
41
-
On the build side, the `master` branch is polled routinely by a Jenkins instance at home, which builds the site into
42
-
the "site" folder and then uploads it to the http://articulate-lisp.com host.
36
+
Unfortunately, I don't have autobuild yet set up to Docker build &&
37
+
docker push, as that requires credentials and capabilities Travis
38
+
doesn't have yet.4
43
39
44
40
** Contributions.
45
41
46
-
Please pull off the top of the `devel` branch for your contributions and use github Pull Requests for contributing.
42
+
Please send in pull requests!
47
43
48
-
My home Jenkins instance deploys that branch out to articulate-lisp.com/devel. This allows me to merge your PR and
49
-
see the result quickly without being at a development machine: e.g., I can use my mobile phone to merge your work and
50
-
keep the awesome flowing as fast as possible.
51
44
52
45
** License information & legalities.
53
46
54
47
My opinion on articulate-lisp.com's licensing is this: it should be easy to grab bits and pieces and easy to fork if
55
48
the author disappears. After some careful reading, I selected...
56
49
57
-
- GPL3 for the documentation itself.
50
+
- GPL3 for the documentation itself.
58
51
59
52
- Snippets and other samples embedded in the documentation should be considered public domain a.k.a CC0.
60
53
61
-
- The full-size examples in src/ are more substantial and, are licensed as AGPL3. This is denoted in their comment header.
54
+
- The full-size examples in examples/src/ are more substantial and, are licensed as AGPL3. This is denoted in their comment header.
62
55
63
56
I do not believe that these terms are onerous and I have sought to structure them to permit both free use of small things
64
-
and continuity of information.
57
+
and continuity of information.
65
58
66
-
AGPL3 is a very strict copyleft license and I feel obligated to justify its choice.
59
+
AGPL3 is a very strict copyleft license and I feel obligated to justify its choice.
67
60
68
61
Simply put, I believe that software developers have a moral obligation to allow their users to repair the software that
69
62
they provide. This facility is usual for physical items: we can fix our bikes, chairs, cars, etc. I believe that we
70
63
ought to let our users fix the software they use, or hire other people to make that fix. I also have profound issues with
71
-
the software patent industry. AGPL3 is the best license I know of to ensure that what I create gives users these
72
-
capabilities and will not be patented. As these are ridiculously small examples, I am fairly positive that any
64
+
the software patent industry. AGPL3 is the best license I know of to ensure that what I create gives users these
65
+
capabilities and will not be patented. As these are ridiculously small examples, I am fairly positive that any
73
66
serious work will not use them. So it should not be onerous on you.
74
67
75
-
If your corporate lawyers refuse to let example AGPL3 code exist in your development environment, please write in and -
76
-
for my part - I will make a good faith effort to negotiate with you for you a less strict license for your company. And I
77
-
will doubtlessly say rude things about lawyers.
68
+
If your corporate lawyers refuse to let example AGPL3 code exist in your development environment, please write in and -
69
+
for my part - I will make a good faith effort to negotiate with you for you a less strict license for your company.
0 commit comments