And instead of the repos, we should use the hex.pm entries.

Gitbook has changed its services and some of our stuff no longer builds. It would be nice to use some tooling that doesn't depend upon a service going away ... and I'd love to not have to use Ruby.

Ideally, whatever solution we use going forward should satisfy these conditions:

• allow us to continue using the content we've created in markdown with no (or very few changes)
• be usable without having to install tons of dependencies on our systems (e.g., support docker usage)
• not be part of some pay-for-service that could be taken away at any point in time
• support generating and viewing books locally
  a
  One option that is used to generate the copious markdown-based books in the Rust programming language community is this one:
• https://github.com/rust-lang/mdBook

I'll see if it meets our other criteria ...a

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Tasks:

• Extract useful bits from http://docs.lfe.io/current/user-guide/diving/1.html

• Add them here: https://cnbbooks.github.io/lfe-manual/part2/data-types/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/intro/1.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/data-types/index.html

• Extract useful bits from http://docs.lfe.io/current/user-guide/diving/2.html

• Add them here:

  • https://cnbbooks.github.io/lfe-manual/part2/data-types/index.html
  • https://cnbbooks.github.io/lfe-manual/part2/lists/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/diving/2.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/lists/index.html

• Extract useful bits from http://docs.lfe.io/current/user-guide/diving/3.html

• Add them here: https://cnbbooks.github.io/lfe-manual/part2/byte-bin/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/diving/3.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/byte-bin/index.html

• Create a new "Variables" section in https://cnbbooks.github.io/lfe-manual

  • where is that done in the original Chineual?
  • where is this done in the LFE Tutorial? (looks like this doesn't have a dedicated section)
  • what about Rust? (right before the data types section: https://doc.rust-lang.org/book/ch03-01-variables-and-mutability.html -- this is a great place for it)

• Extract useful bits from http://docs.lfe.io/current/user-guide/diving/4.html

• Add them to the new variables section

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/diving/4.html with an HTML meta redirect to the new location (e.g., https://cnbbooks.github.io/lfe-manual/part2/vars/index.html)

• Extract useful bits from http://docs.lfe.io/current/user-guide/diving/5.html

• Add them here: https://cnbbooks.github.io/lfe-manual/part2/patterns/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/diving/5.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/patterns/index.html

This will mean we won't have to have separate branches for build and publish. I've done this in another mdbook repo somewhere fairly recently -- I'll get a link to that repo to use as an example.

There are a handful of phases involved ... and they're not actually linear/sequential, they're more combined + iterative. Which means that, even if a section looks "done" it's actually not. They will be tuned over and over 🙂 So, here are the "phases":

Phase I

• Move useful content out of existing old docs.lfe.io site
• Update that content for LFE 2.0
• Add redirects for moved content from docs.lfe.io to cnbbooks.github.io/lfe-manual/current (note that when officially published, these will redirect further to lfe.io/books/chineual)

Phase II

• Examine each section of the Lisp Machine Manual and carry as much of its good qualities over to the LFE Machine Manual
• Key differences include more information about usage or links to online resources that cover usage in more detail
• Explore the possibility of scraping / parsing Existing Erlang STDLIB and ERTS Reference Manuals and the Erlang User Guide ... but only if a good user experience can be created; otherwise, just link out to these, as applicable

Phase III

• Examine three key Erlang books for content + topics (Erlang Programming, LYSE, Designing for Scalability)
• Carry these over for use in the Chineual chapters
• There are some pre-existing LFE examples and articles which may be pulled in for this as well (blog posts, Rosetta Code, various LFE orgs & repos, etc.)

Phase IV

• Lastly, some of the most competent, useful, and even compelling online manuals / books being produced right now are for Rust
• Examine those Rust resources for inspiration (content to cover, organisation of said content, etc.)
• Pull in as applicable

Note: this is a work in progress, it's not being published to lfe.io/books yet. Drafts are published here: https://cnbbooks.github.io/lfe-manual/current

Primary sources

LFE:

• The minimalist guide that ships with LFE: https://github.com/rvirding/lfe/blob/develop/doc/src/lfe_guide.7.md
• The LFE port of the Erlang Tutorial: https://lfe.io/books/tutorial/
• Any still-useful old content on docs.lfe.io

Erlang:

• Erlang Reference Manual User's Guide: https://erlang.org/doc/reference_manual/users_guide.html
• Kernel Reference Manual: http://erlang.org/doc/apps/kernel/index.html
• Erlang Run-Time System Application (ERTS) Reference Manual: http://erlang.org/doc/apps/erts/index.html
• Learn You Some Erlang: https://learnyousomeerlang.com/content
• Erlang Programming: https://www.oreilly.com/library/view/erlang-programming/9780596803940/
• Designing for Scalability with Erlang/OTP: https://www.oreilly.com/library/view/designing-for-scalability/9781449361556/

Lisp:

• The Lisp Machine Manual: https://drive.google.com/file/d/0B1AjIfhQqXG_Um1sMVh5Ump2R2M/edit
• The Revised Maclisp Manual (The Pitmanual): http://www.maclisp.info/pitmanual/
• Common Lisp HyperSpec: http://www.lispworks.com/documentation/HyperSpec/Front/index.htm

Rust:

• The Rust Programming Language
• The Rust Reference
• Rust by Example

Contributing

If you are interested in contributing to this effort, the most important preparatory steps you can take are:

• read up on the primary resources above
• examine the content that has already been produced
• have a discussion in #docs on the LFE Slack about an area of interest where you'd like to contribute
• spend a few weeks diving into an agreed upon area in Erlang as well as LFE, examining their differences and taking notes on your experiences
• spend a few days examining the Common Lisp analogs
• fork this repo
• write a concise narrative for the topic at hand in the same style as the content already produced
• commit/push to your fork and submit a PR for the content
• work with the editors to make changes according to their requests
• rinse and repeat 😄

Moved from: lfe/docs#29

This was actually the template that was used when envisioning this book, back in 2014 and 2015, per discussions with @rvirding on IRC, etc.

Here's a searchable PDF: https://drive.google.com/file/d/0B1AjIfhQqXG_Um1sMVh5Ump2R2M/edit

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

I keep using the old docs site for some things (such as the list comprehension examples). Lets get that content moved into the manual, and then just link to it from the other pages.

Content to move:

• Integrate useful intro material - #21
• We can rescue the diving in parts - #23
• Lists and simple data sections - #25
• Much of the recursion can be rescued: http://docs.lfe.io/current/user-guide/recursion/1.html
• Mnesia tutorial: http://docs.lfe.io/current/tutorials/mnesia/1.html
• Some of the project setup stuff: http://docs.lfe.io/current/user-guide/devops/1.html
• For all content that is moved, add a redirect to the new location

Everything else can be scrapped.

Possibilities, with the understanding that only "LFE CHINE NUAL" would appear on the (green) cover:

• LFE Greenmachine Manual (the logo)
• LFE Dreammachine Manual (?)
• LFE Frankenmachine Manual (??)
• LFE Multimachine Manual - "The multimachine is an all-purpose open source machine tool that can be built inexpensively by a semi-skilled mechanic with common hand tools, from discarded car and truck parts, using only commonly available hand tools and no electricity. Its size can range from being small enough to fit in a closet to one hundred times that size. The multimachine can accurately perform all the functions of an entire machine shop by itself."
• LFE Moonshine Manual (nod to David Moon + chine -> shine)
• LFE OTP-machine Manual
• LFE Sunshine Manual (open source hippies? let the sun shine in? This is the dawning of the age of ...?)

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

See lfe/docs#16

Conss -> Cons Cells

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Tasks:

• Extract useful bits from http://docs.lfe.io/current/user-guide/data/1.html

• Add them here: https://cnbbooks.github.io/lfe-manual/part2/lists/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/data/1.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/lists/index.html

• Create new section in Part III for list comprehensions (probably after "Closures"? anonymous functions will be covered in the new "Functions" chapter, but the "Closures" chapter should immediately follow that one)

• Extract useful bits from http://docs.lfe.io/current/user-guide/data/2.html

• Add them to the new list comp chapter

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/data/2.html with an HTML meta redirect to the new list comp chapter

• Extract useful bits from http://docs.lfe.io/current/user-guide/data/3.html

• Add them here: https://cnbbooks.github.io/lfe-manual/part2/proplists/index.html

• And here https://cnbbooks.github.io/lfe-manual/part2/dicts/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/data/3.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/proplists/index.html

• Extract useful bits from http://docs.lfe.io/current/user-guide/data/4.html

• Add them here: https://cnbbooks.github.io/lfe-manual/part2/records/index.html

• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/data/4.html with an HTML meta redirect to https://cnbbooks.github.io/lfe-manual/part2/records/index.html

• The Rust Programming Language
• The Rust Reference
• Rust by Example

The content at https://en.wikibooks.org/wiki/Haskell is already categorized according to the 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

https://erlang.org/doc/reference_manual/users_guide.html

Data types, expressions, etc.

Right now, "Pattern Matching" gets its own section towards the end of Part II -- Let's move that to the beginning of Part II, even before data types are discussed. Give an intro about it, that it is integral to the language, and every type section will show how to match that particular type.

Then do the same in the subsequent sections of Part III.

This will allow us to deprecate (and move here) the following:

• https://github.com/cnbbooks/lfe-rebar3-quick-start
• https://github.com/cnbbooks/lfe-rebar3-command-reference

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Starting with LFE 2.0, let's start tracking "Current" as well as all published version numbers, just like with other docs, e.g., https://github.com/cnbbooks/lfe-rebar3-command-reference/tree/7dec0fe5f79328958b60ae57445c9a5c61136a9a

Sections:

• Preface
• About LFE

I have created this ticket based upon feedback from here:

• lfe/lfe#478

In-REPL (set), in assignments with let, function heads, lambda functions, etc.

Categorize according to 4 levels:

• Introductory
• Beginner
• Intermediate
• Advanced

Tasks:

• Extract useful bits from http://docs.lfe.io/current/user-guide/intro/1.html
• Find the right place to put them
• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/intro/1.html with an HTML meta redirect to the new location in the Chineual to use instead
• Extract useful bits from http://docs.lfe.io/current/user-guide/intro/2.html
• Find the right place to put them
• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/intro/2.html with an HTML meta redirect to the new location in the Chineual to use instead
• Extract useful bits from http://docs.lfe.io/current/user-guide/intro/3.html
• Find the right place to put them
• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/intro/3.html with an HTML meta redirect to the new location in the Chineual to use instead
• Extract useful bits from http://docs.lfe.io/current/user-guide/intro/4.html
• Find the right place to put them
• Replace the HTML at https://github.com/lfe/docs/blob/master/docs/current/user-guide/intro/4.html with an HTML meta redirect to the new location in the Chineual to use instead

New sections:

• Style guide - the old repo will need to be deprecated once this is done

No need for a Beginner's Guide -- that's the whole "Getting Started" section.

New "Tooling" subsections:

• Creating new projects
• Using third-party libraries
• Publishing projects
• Upgrading tooling (we need to document some gotchas with rebar3 caching ... it gets people all the time; example commands to add: lfe/rebar3#86)

Moved from lfe/docs#30