diff options
author | Stephen Dolan <mu@netsoc.tcd.ie> | 2013-05-09 20:27:12 +0100 |
---|---|---|
committer | Stephen Dolan <mu@netsoc.tcd.ie> | 2013-05-09 20:35:19 +0100 |
commit | e6494857fc188f50808fcf64e4f43188a455f264 (patch) | |
tree | 6e6d3e68569692e5f2a3b225de5d7180a8d93bd3 | |
parent | 12d2d4d1f53f7f1c6d53d0eb82672cdbd75a6df9 (diff) |
Add some build instructions for how to install doc dependencies.
jq can now build without Ruby, but you won't get a nice manpage.
-rw-r--r-- | Makefile.am | 23 | ||||
-rw-r--r-- | configure.ac | 15 | ||||
-rw-r--r-- | docs/README.md | 25 | ||||
-rw-r--r-- | docs/Rakefile | 5 | ||||
-rw-r--r-- | docs/default_manpage.md | 22 | ||||
-rw-r--r-- | jq.1.default | 39 |
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 |