Add some build instructions for how to install doc dependencies.

jq can now build without Ruby, but you won't get a nice manpage.

6 files changed, 118 insertions, 11 deletions

diff --git a/Makefile.am b/Makefile.am
index 96a885c1..33175cd1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,4 @@
-### C source files to be built
+### C source files to be built and distributed.
 
 JQ_INCS = jq_parser.h builtin.h bytecode.h compile.h execute.h		\
   forkable_stack.h frame_layout.h jv.h jv_alloc.h jv_aux.h jv_dtoa.h	\
@@ -31,7 +31,6 @@ lexer.h: lexer.c
 AM_YFLAGS = --warnings=all -d
 
 
-
 ### Building the jq binary
 
 main.c: config.h
@@ -48,23 +47,31 @@ TEST_LOG_COMPILER = ${srcdir}/tests/run
 
 ### Building the manpage
 
+# If ENABLE_DOCS is not set, just copy jq.1.default to jq.1
+# The real_docs target succeeds (possibly after building jq.1) only if ENABLE_DOCS is set
+# Thus, making "dist" depend on "real_docs" ensures that we never build a tarball with
+# a stub manpage.
+
 man_MANS = jq.1
 .PHONY: real_docs
 if ENABLE_DOCS
 jq.1: $(srcdir)/docs/content/3.manual/manual.yml
-	( cd ${abs_srcdir}/docs; rake manpage ) > $@ || { rm -f $@; false; }
-real_docs:
-	true
+	( cd ${abs_srcdir}/docs; '$(BUNDLER)' exec rake manpage ) > $@ || { rm -f $@; false; }
+jq.1.default: $(srcdir)/docs/default_manpage.md
+	( cd ${abs_srcdir}/docs; '$(BUNDLER)' exec rake manpage_default ) > $@ || { rm -f $@; false; }
+real_docs: jq.1
+	cmp jq.1 $(srcdir)/jq.1.default > /dev/null && { rm -f jq.1; $(MAKE) $(AM_MAKEFLAGS) jq.1; }
 else
-jq.1: jq.1.default
+jq.1: $(srcdir)/jq.1.default
 	cp $^ $@
 real_docs:
-	@echo "Cannot build full manpage" > /dev/stderr
+	@echo "Ruby dependencies not found, cannot build manpage." > /dev/stderr
+	@echo "Follow the instructions in docs/README.md to install them" > /dev/stderr
+	@echo "and then rerun ./configure" > /dev/stderr
 	false
 endif
 
 
-
 ### Packaging
 
 docs/site.yml: configure.ac
diff --git a/configure.ac b/configure.ac
index 32ecdf7b..0ad893af 100644
--- a/configure.ac
+++ b/configure.ac
@@ -34,19 +34,28 @@ fi
 
 
 dnl Don't attempt to build docs if there's no Ruby lying around
-AC_ARG_ENABLE([docs], 
+AC_ARG_ENABLE([docs],
    AC_HELP_STRING([--disable-docs], [don't build docs]))
 
 AS_IF([test "x$enable_docs" != "xno"],[
-   AC_CHECK_PROG(bundle_cmd, bundle)
+   AC_CHECK_PROGS(bundle_cmd, bundle)
    AS_IF([test "x$bundle_cmd" = "x" || \
-      ! ( cd ${srcdir}/docs; bundle check 2>/dev/null )],[
+      ! ( cd ${srcdir}/docs; "$bundle_cmd" check 2>/dev/null )],[
          AC_MSG_WARN([no bundler])
+         cat <<EOF
+*****************************************************************
+*  Ruby dependencies for building jq documentation not found.   *
+*  You can still build, install and hack on jq, but the manpage *
+*  will not be rebuilt and some of the tests won't run.         *
+*  See docs/README.md for how to install the docs dependencies. *
+*****************************************************************
+EOF
          enable_docs=no
    ])
 ])
 
 AM_CONDITIONAL([ENABLE_DOCS], [test "x$enable_docs" != xno])
+AC_SUBST([BUNDLER], ["$bundle_cmd"])
 
 dnl AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_HEADERS(config.h)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..58e7dca7
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,25 @@
+Documentation
+=============
+
+The jq website, manpages and some of the tests are generated from this
+directory. The directory holds a [Bonsai](http://tinytree.info)
+website, and the manual is a YAML file in `content/3.manual`.
+
+To build the documentation (including building the jq manpage), you'll
+need a working Ruby setup. The easiest way to get one is to install
+RVM and Ruby 1.9.3 like so:
+
+    \curl -L https://get.rvm.io | bash -s stable --ruby=1.9.3
+
+After that finishes installing, you'll need to make sure RVM is on
+your path by doing `source $HOME/.rvm/scripts/rvm`, or just opening a
+new shell. See <http://rvm.io> for more info on RVM.
+
+Once RVM is installed, you can install all the dependencies for jq's
+documentation build by running this from the `docs` directory:
+
+    bundle install
+
+When bundle manages to install the dependencies, rerun `./configure`
+in the jq root directory and then the Makefile will be able to
+generate the jq manpage.
diff --git a/docs/Rakefile b/docs/Rakefile
index 356f7111..f8072072 100644
--- a/docs/Rakefile
+++ b/docs/Rakefile
@@ -120,6 +120,10 @@ task :manpage do
   end  
 end
 
+task :manpage_default => ["default_manpage.md"] do
+  puts Ronn::Document.new("default_manpage.md").convert('roff').gsub(/<\/?code>/,"")
+end
+
 task :mantests do
   load_manual['sections'].each do |section|
     (section['entries'] || []).each do |entry|
@@ -132,3 +136,4 @@ task :mantests do
     end
   end
 end
+
diff --git a/docs/default_manpage.md b/docs/default_manpage.md
new file mode 100644
index 00000000..f1a29a72
--- /dev/null
+++ b/docs/default_manpage.md
@@ -0,0 +1,22 @@
+jq(1) -- Command-line JSON processor
+====================================
+
+## DESCRIPTION
+
+`jq` can transform JSON in various ways, by selecting, iterating,
+reducing and otherwise mangling JSON documents. 
+
+This version of `jq` was built without a manual, so this manpage is a
+stub. For full documentation of the `jq` language, see:
+
+    http://stedolan.github.com/jq
+    
+## BUGS
+
+Presumably. Report them or discuss them at:
+
+    https://github.com/stedolan/jq/issues
+
+## AUTHOR
+
+Stephen Dolan `<mu@netsoc.tcd.ie>`
diff --git a/jq.1.default b/jq.1.default
index e69de29b..c556f794 100644
--- a/jq.1.default
+++ b/jq.1.default
@@ -0,0 +1,39 @@
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "JQ" "1" "May 2013" "" ""
+.
+.SH "NAME"
+\fBjq\fR \- Command\-line JSON processor
+.
+.SH "DESCRIPTION"
+\fBjq\fR can transform JSON in various ways, by selecting, iterating, reducing and otherwise mangling JSON documents\.
+.
+.P
+This version of \fBjq\fR was built without a manual, so this manpage is a stub\. For full documentation of the \fBjq\fR language, see:
+.
+.IP "" 4
+.
+.nf
+
+http://stedolan\.github\.com/jq
+.
+.fi
+.
+.IP "" 0
+.
+.SH "BUGS"
+Presumably\. Report them or discuss them at:
+.
+.IP "" 4
+.
+.nf
+
+https://github\.com/stedolan/jq/issues
+.
+.fi
+.
+.IP "" 0
+.
+.SH "AUTHOR"
+Stephen Dolan \fB<mu@netsoc\.tcd\.ie>\fR