Examples

• Erlang: http://learnxinyminutes.com/docs/erlang/
• Common Lisp: http://learnxinyminutes.com/docs/common-lisp/
• Clojure: http://learnxinyminutes.com/docs/clojure/
• Clojure Macros: http://learnxinyminutes.com/docs/clojure-macros/
• Racket: http://learnxinyminutes.com/docs/racket/

Process

• Fork this: https://github.com/adambard/learnxinyminutes-docs
• Write
• Submit a PR

Suggested by Aleksandar Radulovic.

Part of epic #75

Moved to: cnbbooks/lfe-manual#30

This page: http://docs.lfe.io/user-guide/diving/5.html

Create a new site book (like the User Guide, the Cookbook, etc.) that does a thorough job explaining how to use (and maximize the use of) lfetool in developing LFE projects of all types.

We've received some feed back on Twitter about the lack of a good LFE tutorial; that's got a new ticket (issue #40).

While that work is in progress, we need to do some "preventative medicine" by clearly setting expectations (a little of this was done in the README for Casting SPELs in LFE; we need a shorter version of that for our current docs).

So, at the top of the docs site, we need to do the following:

• Convert the section "Erlang Resources" to "Learning LFE"
• Add explanatory text saying that, until we have more and better beginners' materials, one needs to learn a bit of Lisp and some Erlang before tackling LFE
• Provide resources for both, with links
• Provide a note on "what's next", i.e., once that task has been accomplished, what the reader can do next

Both Quick Starts should have their introductions updated along these lines as well.

Based on some recent feedback in Twitter, @rvirding and I are brainstorming about ways in which we can address this lack (both short-term, as well as a more thorough long-term solution). Being a very small open source project with few resources, we have to be very practically minded about this :-) Also, we want to get something out to people as soon as possible, without agonizing over it for a year or two ... so the intended audience would probably be intermediate programmer with minimal experience with Erlang and/or Lisp.

More thoughts on this:

• this tutorial should mirror a good Erlang tutorial
• it wouldn't be a comprehensive/detailed tutorial (or workshop?) on LFE
• rather, it would assume a level of certain knowledge with both Lisps and Erlang itself.

We've created a separate ticket for a comprehensive tutorial (a "phase 2" of the basic tutorial developed in this ticket).

Part of epic #75

There was a recent email to the list that went into this; it should be documented:
https://groups.google.com/d/msg/lisp-flavoured-erlang/f1mF360pUC4/EOjokdzUDmQJ

Part of epic #98

There are two interesting examples of this, one of which has a very nice visual presentation:

• http://hyperpolyglot.org/lisp
• https://kanaka.github.io/clojurescript/web/synonym.html

Suggested by Aleksandar Radulovic.

Part of feature #100

Right now, there's a listing of functions here:

• http://lfe.github.io/user-guide/funcode/2.html

This should be moved to the introductory section, right after the page on data types in LFE.. In its place should be several pages of functions -- description and usage examples for each. What are sections on that page right now should become separate pages.

Best cheatsheet I've seen for a language so far:
http://jafingerhut.github.io/
Do one like that for LFE.

Part of epic #75

Part of feature #100

Moved to: cnbbooks/catalog#14

Following up on the "Basic Tutorial" in issue #40, this ticket aims to take it to the next level with the following:

• providing an introduction to Lisps in general for folks that have no background there
• providing a gentler introduction to Erlang than that provided in the basic tutorial
• identifying holes or "weak spots" in the Basic Tutorial where new-comers have struggled, encountered ambiguities or difficulties, etc.
• examining good tutorials from other languages
• putting all of this together for a v2 of the tutorial

Part of epic #75

Moved to: cnbbooks/catalog#14

Recommended by Mário Guimarães.

If we go with a whole new layout (versioned docs, etc.) for the new LFE docs site, we're going to need to put some redirections in place ...

This section should go in the introductory chapter, right after the section on loading files. (The listing of functions should come after this, and then the "setting up a dev env" section.)

Show how to get characters from strings, etc., as well.

Most pertinent stuff for LFE devs should be first.

Moved to: cnbbooks/catalog#14

Recommended by Mário Guimarães.

Moved to: cnbbooks/catalog#14

Recommended by Mário Guimarães.

In the same vein as issue #36 (but with a less immediate need), we should build a list of top-notch programming language, framework, and library docs:

• what makes them good?
• how might a given approach be adopted to LFE?
  • how about third-party, community LFE libraries?

Some examples that come to mind:

• Python: nothing fancy, but rock-solid for nigh two decades
• OpenStack: Anne Gentle has done an amazing job with this massive, massive project
• Some bits of the Django docs, since I'm a firm believer in showing code in the docs (though this does introduce a phenomenal maintenance burden, unless you get clever with your docs infrastructure...)
• I've heard good things about MSDN, but maybe I need more familiarity with it before I see its greatness
• I hated Amazon's AWS API docs initially, but have grown quite fond of them over the years (and with improvements)

Please share your favourites!

Part of the Planning Epic.

Moved here: cnbbooks/lfe-rebar3-command-reference#10

Creating and using them.

Part of epic #75

Have two sections for the book:

• Operations, and the errors you get with them, and
• An alphabetical list of errors and where they show up (maybe more of an index ...)

We should have history links for Lisp, Erlang, and LFE. The "LFE" page on http://lfe.io/ has two of the best sources for Lisp; this should be added to a "History" section on the docs main page.

Add the following for Erlang:

• http://webcem01.cem.itesm.mx:8005/erlang/cd/downloads/hopl_erlang.pdf
• http://www.cs.tut.fi/~popl/essays/erlang.pdf
• https://www.erlang-factory.com/upload/presentations/416/MikeWilliams.pdf
• http://www.infoq.com/interviews/williams-erlang
• https://www.youtube.com/watch?v=HCwRGHj5jOE

Part of feature #100

Moved here: cnbbooks/catalog#2

This would be a whole new segment of the site, not just another section.

Part of epic #75

1. processes on multi-core apps

2. distributed processes

Need to find a good location for mentioning $ENV and demonstrating how to use it. Possibly in a section on debugging?

Part of feature #100

The copy of the github developer docs site running on docs2.lfe.io is a mess right now, with only partial styling applied. We need to get this fixed up before eyes start bleeding ...

Also, add a note about (: c i)

Tasks:

• Identify core site areas to highlight on simplified landing page
• Decide upon top-nav menu items
• Decide upon bottom-nav menu items
• Identify major documentation categories
• For each major category, identify subcategories
• Identify which categories have content that should be versioned

Our information architecture is basically non-existent. We need to create one.

Part of Milestone v3 #62

As we begin to iterate on the LFE docs, we need to think about the content we want to present to various types of end user, how that content should be organized, what content is missing from existing docs that would be nice to add, and what content we should remove or rework.

@bigos shared the following link:

• https://en.wikibooks.org/wiki/Haskell

And this is a great example of organizing content by experience level. It's not a very common approach, but I like it -- especially for an online resource.

We should also map out the topics covered in:

• Learn You Some Erlang
• Programming Erlang
• Erlang Programming
• Designing for Scalability with Erlang/OTP

Then, after compiling that list, we could divide the topics up across one or more levels of experience, as the Haskel wiki book has done...

At any rate, if you have a favorite programming book, please provide a link in the comments and why you liked it, and if you have the time, why you think LFE would benefit from something like that.

Thanks!

Part of the Planning Epic.

Tutorial: Lightweight Processes: 4 Process Communications

To demonstrate this, let's update our print-result function to do this: * pattern match for a process id as well as a message * write message about sending data to another process * actually send that data to the other process

This can just start with a sample of all the different things that are styled:

• terminal code
• terminal code with emphasis
• source code
• code in a paragraph
• tables
• alert boxes
• warning boxes
• numbered steps/instructions
• various LFE logos (small grey, small black, small color, large color, etc.)

It would just be a single page showcasing these things (and more), as a reminder to docs maintainers regarding the available styles and the prescribed way to do things.

Part of epic #96

https://github.com/basho/riak-erlang-client

Part of the Versioning Docs Epic

Moved to: cnbbooks/catalog#14

Be sure to include a section about working with a table across processes:

"The table identifier can be sent to other processes so that a table can be shared between different processes within a node."

(from http://www.erlang.org/doc/man/ets.html)

Dorai gave permission to copy this excellent tutorial:

• http://www.ccs.neu.edu/home/dorai/lfe-lessons/index.html#node_toc_start

New page URL:

• http://www.ccs.neu.edu/home/dorai/lfe-lessons/index.html

This will make a nice addition to the site!

Convert Java Interop section to just "Interop" -- include Elixir and Joxa interop examples?

Similar to the rightly-famous Clojure cheat sheet:

• https://jafingerhut.github.io/

This is from an email that Robert sent, and it's a great idea:

I was looking through some of the examples you refer to in the LFE page when I remembered that LFEs backquote macro even works with tuples . So you can use a tuple "pattern" which expands into code to build a tuple. For example:

`#(ok ,reply) ==> (tuple 'ok reply))

With that you could write the callbacks to the ping_pong server as:

(defun init (args)
  `#(ok ,(make-state pings 0)))

(defun handle_call (req from state)
  (let* ((new-count (+ (state-pings state) 1))
         (new-state (set-state-pings state new-count)))
    `#(reply #(pong ,new-count) ,new-state)))

It of course also works in patterns. This is clearer and more concise for those who know about it but I don't think that this is something to drop on the poor unsuspecting reader from the beginning, but a section on the backquote macro would be good to have somewhere.

To figure out of the Github Documentation example site will work for LFE's versioned docs, a couple of example uses are needed. This will help determine if the Github approach will suit our needs. If so, this will allow us to close issue #38 :-)

To accomplish this:

• use the LFE user_guide.txt for the v0.6, v0.8, v0.9, and v0.9.1 releases
• identify the workflow necessary to create a versioned part of the site
• use that to create 4 versioned "areas", one for each of the above
• identify weak spots, difficulties, etc.

Moved to: cnbbooks/lfe-manual#29

This page:

• http://docs.lfe.io/user-guide/diving/5.html

Example Erlang code:

handle_info(ping, #state {remote_pid = undefined} = State) ->
    gen_server:cast(self(), ping),
    {noreply, State};

handle_info(ping, State) ->
    {noreply, State};

handle_info({pong, Pid}, #state {remote_pid = undefined,
                                 waiters = Waiters} = State) ->
    ?INFO("connection to java node established, pid ~p", [Pid]),
    link(Pid),
    lists:foreach(fun(Waiter) ->
                          gen_server:cast(self(), {wait_for_login, Waiter})
                  end, Waiters),
    {noreply, State#state {waiters = [],
                           remote_pid = Pid}};

handle_info({pong, _}, State) ->
    {noreply, State};

handle_info({Port, {exit_status, Status}}, #state {ext_port_ref = Port} = State) ->
    ?ERROR("external java app exited with status ~p", [Status]),
    {stop, {error, {java_app_exit, Status}}, State};

handle_info({'EXIT', Pid, Reason}, #state {remote_pid = Pid} = State) ->
    ?ERROR("external java mbox exited with reason ~p", [Reason]),
    {stop, {error, {java_mbox_exit, Reason}}, State};

handle_info(_Info, State) ->
    ?ERROR("unhandled info, ~p", [_Info]),
    {noreply, State}.

Corresponding LFE code:

(defun handle_info
  (('ping (= (match-state remote-pid 'undefined) state))
    `#(noreply ,state))
  (('ping state)
   `#(noreply ,state))
  (((tuple 'pong pid) (= (match-state remote-pid 'undefined
                                      waiters waiters)
                         state))
   (INFO "Connection to java node established, pid: '~p'" (list pid))
   (link pid)
   (lists:foreach
     (lambda (x)
       (gen_server:cast (self) `#(wait-for-login x)))
     waiters)
   `#(noreply ,(make-state remote-pid pid
                           waiters waiters
                           ext-port-ref (state-ext-port-ref))))
  (((tuple 'pong _) state)
   `#(noreply ,state))
  (((tuple port (tuple 'exit-status status)) (= (match-state ext-port-ref ext-port)
                                                state)) (when (== port ext-port))
   (ERROR "External java app exited with status: '~p'" (list status))
   `#(stop #(error #(java-app-exit ,status)) ,state))
  (((tuple 'EXIT pid reason) (= (match-state remote-pid remote-pid)
                                state)) (when (== pid remote-pid))
   (ERROR "External java mbox exited with reason: '~p'" (list reason))
   `#(stop #(error #(java-mbox-exit ,reason)) ,state))
  ((info state)
   (ERROR "Unhandled info: '~p'" (list info))
   `#(noreply ,state)))