Improve build flow

Fixes #16

.travis.yml

@@ -1,11 +1,26 @@
-# https://github.com/koalaman/shellcheck/wiki/TravisCI
-# Reference: https://github.com/ccztux/glsysbackup/blob/c59fedeafa9398e4f0aa65de1f63fdbabe2d54f8/.travis.yml
+dist: trusty
 sudo: required
-language: bash
+language: generic
+env:
+  global:
+    - CURL="curl -fsSkL --retry 9 --retry-delay 9"
+  matrix:
+  # https://github.com/npostavs/emacs-travis/releases
+  - EMACS_VERSION=26 # emacs-26 branch
+  - EMACS_VERSION=25.3
+  - EMACS_VERSION=25.1
+  - EMACS_VERSION=24.5
+  - EMACS_VERSION=24.4
+  - EMACS_VERSION=master # master branch
 services:
   - docker
 before_install:
   - docker pull koalaman/shellcheck
+install:
+  - $CURL -O https://github.com/npostavs/emacs-travis/releases/download/bins/emacs-bin-${EMACS_VERSION}.tar.gz
+  - tar xf emacs-bin-${EMACS_VERSION}.tar.gz -C /
+  - export EMACS=/tmp/emacs/bin/emacs
+  - $EMACS --version
 script:
   - docker run koalaman/shellcheck --version
   # https://docs.docker.com/engine/reference/commandline/run/#mount-volume--v---read-only
@@ -15,8 +30,19 @@ script:
   #   So this combination executes the command using the container, but inside
   # the current working directory.
   - docker run -v $(pwd):/repo_root -w /repo_root koalaman/shellcheck eless
+  - make --no-print-directory all EMACS=${EMACS} # Just ensure that "make all" doesn't fail for any reason.. this is *not* used to generate the script or the docs on Travis.
 matrix:
   fast_finish: true
 branches:
   except:
   - images
+notifications:
+  email:
+    # Default is change, but that includes a new branch's 1st success.
+    on_success: never
+    on_failure: always # The default
+
+# References:
+# https://github.com/magit/magit/blob/master/.travis.yml
+# https://github.com/koalaman/shellcheck/wiki/TravisCI
+# https://github.com/ccztux/glsysbackup/blob/c59fedeafa9398e4f0aa65de1f63fdbabe2d54f8/.travis.yml

CONTRIBUTING.org

@@ -15,62 +15,33 @@ This guide is for you if you'd like to do any of the below:
      - If you are providing debug info for something like =man foo=, do
        - =PAGER=​"eless -D" man foo=
 * Development
-** Dependencies
-Here's a short list of dependencies if you would like to build =eless=
-and the documentation from =eless.org=:
-
-1. Org version 9.x -- Latest version of Org from Melpa or Org Elpa
-2. =htmlize= package for syntax highlighting of code in html exports
-   -- Melpa
-3. =rainbow-delimiters= package for syntax highlighting of parenthese
-   in elisp code in html exports -- Melpa
-
-The recommended way is to run =emacs -Q= and then run =M-x
-eless-install-dependencies= to install the dependencies in your
-=temporary-file-directory=. /You can choose to even install these
-manually in your emacs config if you like./
-
-I used the latest emacs and org-mode versions built from their =master=
-branches for this project. So if any of the below steps do not work
-for you, open an issue!
-
-Talking about dependencies, this project builds *everything* from
-=eless.org= file, the =eless= script /plus/ all the [[https://kaushalmodi.github.io/eless/][HTML]], Info
-documentation, =README.org=, =CONTRIBUTING.org=, and even the Wiki
-pages. So before running =M-x eless-build= mentioned in below build
-steps, you also need to:
-#+begin_src shell
+** Preparation
+This project builds *everything* from the =eless.org= file --- the
+=eless= Bash script /plus/ all the [[https://kaushalmodi.github.io/eless/][HTML]], Info documentation,
+=README.org=, =CONTRIBUTING.org=, and even the Wiki pages. So before
+your proceed, you also need to:
+#+BEGIN_SRC shell
 cd docs/
 git clone https://github.com/kaushalmodi/eless.wiki.git
-#+end_src
-** Steps to build =eless= and documentation
-- =emacs -Q=
-- *First* open a non-org file like =build/build.el= and *evaluate it*.
-  - The emphasis on opening a non-org file is so that the
-    older-than-required version of =org= in =emacs -Q= doesn't get
-    auto-loaded.  The next step would be to install newer version of
-    org to a temp location. That step would fail due to mixed org
-    versions if the default org version got loaded first.
-  - Evaluating this file will now allow you to run =M-x
-        eless-install-dependencies= or =M-x eless-build=.
-- Do =M-x eless-install-dependencies=.
-  - You will need to do this step only for the very first time you
-    start working on this project.
-- Do =M-x eless-build=.
-- Run the tangled =eless= through [[http://www.shellcheck.net/][shellcheck]] to ensure that there are
-  no errors.
-- Understand the changes made in =eless=, /plus/ all the other files.
-  - I build the HTML documentation using the Org version from =master=
-    branch. So if you build the HTML documentation using the latest
-    stable as of today (version =9.0.7=), your HTML export will look a
-    bit different (absence of nested =<code>= blocks inside =<pre>=),
-    but that's OK.
-  - Also the randomly generated hyperlinks and section numbers (if you
-    added/removed/moved documentation sections) will be different in
-    the HTML and Info exports.
-  - .. and the =git rev-parse= returned commit hash will be different.
-  - Other than that, you shouldn't see any unexpected changes.
-- Provide a PR.
+#+END_SRC
+** To build =eless= and documentation
+#+BEGIN_SRC shell
+make eless
+#+END_SRC
+*** Sanity check of the tangled =eless=
+Run the tangled =eless= through [[http://www.shellcheck.net/][shellcheck]] to ensure that there are no
+errors.
+** To build documentation
+#+BEGIN_SRC shell
+make doc
+#+END_SRC
+*** Understand the changes
+- The randomly generated hyperlinks and section numbers in the Info
+  document and HTML will be different.
+- Other than that, you shouldn't see any unexpected changes.
+** Submitting PR
+- You can submit a PR once you have reviewed all the changes in the
+  tangled =eless= script and documentation.
 - If changes are only to the Wiki, I believe you can push them
   directly using =git= or manually edit those [[https://github.com/kaushalmodi/eless/wiki][here]]. /I have to yet
   figure out how to keep the non-git Wiki changes and changes in

Makefile

@@ -0,0 +1,97 @@
+# Time-stamp: <2018-02-13 18:26:27 kmodi>
+
+# Makefile to export org documents to md for Hugo from the command line
+# Run just "make" to see usage examples.
+
+MAKE_ := $(MAKE) --no-print-directory
+
+EMACS ?= emacs
+EMACS_exists := $(shell command -v $(EMACS) 2> /dev/null)
+ifeq ("$(EMACS_exists)","")
+	EMACS := /tmp/emacs/bin/emacs
+endif
+
+# EMACS_BIN_SOURCE and EMACS_BIN_VERSION are used later in the vcheck rule
+# only if EMACS_exists has evaluated to "".
+EMACS_BIN_SOURCE ?= https://github.com/npostavs/emacs-travis/releases/download/bins
+EMACS_BIN_VERSION ?= 26
+
+# Directory where the required elisp packages are auto-installed
+TMPDIR ?= /tmp
+ELESS_ELPA=$(TMPDIR)/$(USER)/eless-dev/
+
+ELESS_ELISP_DIR="$(shell pwd)/build/"
+ORG_FILE=$(shell pwd)/eless.org
+
+# Function to be run in emacs --batch
+FUNC=
+
+.PHONY: default help emacs-batch \
+	eless doc docs all vcheck \
+	ctemp clean
+
+default: eless
+
+help:
+	@echo "Help for Eless building"
+	@echo "====================================================="
+	@echo " make eless <-- Build eless bash script"
+	@echo " make doc   <-- Build eless documentation"
+	@echo " make all   <-- Build eless script + documentation"
+	@echo " make help  <-- Show this help"
+
+# Note: The Org file from $(ORG_FILE) is loaded *after* the --eval
+# section gets evaluated i.e. --eval '(progn ..)' $(ORG_FILE) If the
+# order is reversed i.e. i.e.$(ORG_FILE) --eval '(progn ..)', the act
+# of loading the $(ORG_FILE) file first will load the older Org
+# version that ships with Emacs and then run the stuff in --eval that
+# loads the new Org version.. and thus we'll end up with mixed Org in
+# the load-path.
+emacs-batch:
+	@echo ""
+	@echo "$(ORG_FILE) ::"
+	@$(EMACS) --batch --eval "(progn\
+	(setenv \"ELESS_ELPA\" \"$(ELESS_ELPA)\")\
+	(setq-default make-backup-files nil)\
+	(load-file (expand-file-name \"setup-eless.el\" \"$(ELESS_ELISP_DIR)\"))\
+	)" $(ORG_FILE) \
+	-f $(FUNC) \
+	--kill
+
+eless:
+	@$(MAKE_) emacs-batch FUNC=eless-build-script
+
+doc docs:
+	@$(MAKE_) emacs-batch FUNC=eless-build-docs
+
+all: vcheck eless doc
+
+vcheck:
+ifeq ("$(EMACS_exists)","")
+	@curl -fsSkL --retry 9 --retry-delay 9 -O $(EMACS_BIN_SOURCE)/emacs-bin-$(EMACS_BIN_VERSION).tar.gz
+	@tar xf emacs-bin-$(EMACS_BIN_VERSION).tar.gz -C /
+endif
+	@echo "Emacs binary used: $(EMACS)"
+	@$(EMACS) --batch --eval "(progn\
+	(setenv \"ELESS_ELPA\" \"$(ELESS_ELPA)\")\
+	(load-file (expand-file-name \"setup-eless.el\" \"$(ELESS_ELISP_DIR)\"))\
+	(message \"[Version check] Emacs %s\" emacs-version)\
+	(message \"[Version check] %s\" (org-version nil :full))\
+	)" \
+	--kill
+
+ctemp:
+	@find $(shell pwd)/docs -name "*.*~" -delete
+
+clean: ctemp
+	@find ./docs/content -name "*.md" -delete
+	@rm -rf $(ELESS_TEST_SITE_DIR)/public $(ELESS_TEST_SITE_DIR)/content-golden
+	@rm -rf $(ELESS_ELPA)
+	@rm -rf ./docs/public
+	@rm -rf /tmp/hugo/bin
+
+# Set a make variable during rule execution
+# https://stackoverflow.com/a/1909390/1219634
+
+# Check if an executable exists
+# https://stackoverflow.com/a/34756868/1219634

README.org

@@ -64,7 +64,7 @@ As a bonus:
         install=]].
 * Try it out
 Here are some usage examples:
-#+begin_src shell
+#+BEGIN_SRC shell
 eless foo.txt               # Open foo.txt in eless in terminal (-nw) mode by default.
 eless foo.txt --gui         # Open foo.txt in eless in GUI mode.
 echo 'foo' | eless          #
@@ -80,7 +80,7 @@ PAGER=eless git diff        # Show git diff with ANSI coded colors
 eless -h | eless            # See eless help ;-)
 info emacs | eless          # Read emacs Info manual in eless
 eless foo.tar.xz            # Read the contents of archives; emacs does the unarchiving automatically
-#+end_src
+#+END_SRC
 * Contributors
 - Thanks to [[https://github.com/iqbalansari][Iqbal Ansari]] for adding support to read piped data in
   =emacs -Q -nw=.