From e6494857fc188f50808fcf64e4f43188a455f264 Mon Sep 17 00:00:00 2001 From: Stephen Dolan Date: Thu, 9 May 2013 20:27:12 +0100 Subject: [PATCH] Add some build instructions for how to install doc dependencies. jq can now build without Ruby, but you won't get a nice manpage. --- Makefile.am | 23 +++++++++++++++-------- configure.ac | 15 ++++++++++++--- docs/README.md | 25 +++++++++++++++++++++++++ docs/Rakefile | 5 +++++ docs/default_manpage.md | 22 ++++++++++++++++++++++ jq.1.default | 39 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 118 insertions(+), 11 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/default_manpage.md 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 < 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 `` 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\fR