From 00dfdab0481c531b8608a157dc4c4991f319d7f7 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 7 Jan 2020 17:10:20 +0000 Subject: [PATCH] Add documentation subdirectory. --- .gitignore | 2 ++ Goalfile.in | 79 +++++++++++++++++++++++++++++--------------- TODO | 5 +++ configure.ac | 4 +++ docs/goals.pod | 102 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 165 insertions(+), 27 deletions(-) create mode 100644 docs/goals.pod diff --git a/.gitignore b/.gitignore index d901824..7593c84 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,8 @@ *.cmxa *.o +/docs/*.1 + .depend Goalfile Makefile diff --git a/Goalfile.in b/Goalfile.in index 393b4e9..3a41cbf 100644 --- a/Goalfile.in +++ b/Goalfile.in @@ -18,6 +18,38 @@ include "ocaml.gl" +let subdirs = [ "m4", "src", "stdlib", "docs", "tests" ] + +goal all = : "Goalfile", tool, documentation; + +"Goalfile": "Goalfile.in", "config.status" { + ./config.status %@ +} +"src/config.ml" : "src/config.ml.in", "config.status" { + ./config.status %@ +} + +goal clean = { + for d in %subdirs; do + pushd $d + rm -f *~ + rm -f *.cmi *.cmo *.cmx *.o + popd + done + rm -f src/parser.ml src/parser.mli src/lexer.ml src/parser.conflicts + rm -f docs/*.1 + + # We don't delete src/goals because it is required to do builds. + # If you want to really delete it, use the maintainer-clean rule. +} + +goal maintainer-clean = : clean { + rm -f src/goals +} + +#---------------------------------------------------------------------- +# Build the goals tool itself. + let MENHIR = "@MENHIR@" let OCAMLDEP = "@OCAMLDEP@" let OCAMLFIND = "@OCAMLFIND@" @@ -29,6 +61,7 @@ let OCAMLPACKAGES = [ "-package", "str,unix", "-I", "src" ] #let OCAMLPACKAGES = "@OCAMLPACKAGES@" let objects = [ + # These must be in dependency order. "src/config.cmx", "src/utils.cmx", "src/cmdline.cmx", @@ -41,27 +74,9 @@ let objects = [ "src/main.cmx" ] -let subdirs = [ "m4", "src", "stdlib", "tests" ] - -goal all = : "Goalfile", ocaml_link ("src/goals", objects) - -goal clean = { - for d in %subdirs; do - pushd $d - rm -f *~ - rm -f *.cmi *.cmo *.cmx *.o - popd - done - rm -f src/parser.ml src/parser.mli src/lexer.ml src/parser.conflicts - - # We don't delete src/goals because it is required to do builds. - # If you want to really delete it, use the maintainer-clean rule. -} - -goal maintainer-clean = : clean { - rm -f src/goals -} +goal tool = : ocaml_link ("src/goals", objects) ; +# Parser. "src/parser.mli", "src/parser.ml" : "src/parser.mly" { %MENHIR --explain %< # Hack required to break circular dependencies. @@ -76,7 +91,7 @@ goal maintainer-clean = : clean { # XXX Goalfile itself depends on this and we should probably have a # way to reevaluate it. # XXX Atomic output. -goal depend () = +goal depend = "src/.depend" : wildcard ("src/*.ml"), wildcard ("src/*.mli") { rm -f %@ %@-t # Like many existing tools, ocamldep produces make-compatible @@ -90,9 +105,19 @@ goal depend () = -include "src/.depend"; -"Goalfile": "Goalfile.in", "config.status" { - ./config.status %@ -} -"src/config.ml" : "src/config.ml.in", "config.status" { - ./config.status %@ -} +#---------------------------------------------------------------------- +# Documentation. + +let POD2MAN = "@POD2MAN@" + +goal documentation = : pod2man ("goals") + +goal pod2man (page) = +"docs/%page.1" : "docs/%page.pod" { + rm -f %@ %@-t + %POD2MAN \ + -c "goals" \ + --release "@PACKAGE_NAME@-@PACKAGE_VERSION@" \ + --section 1 %< > %@-t + mv %@-t %@ +} \ No newline at end of file diff --git a/TODO b/TODO index 64fe384..7cbf9f5 100644 --- a/TODO +++ b/TODO @@ -34,3 +34,8 @@ Code should be an expression, eg this ought to work: let foo = { echo "hello" } and/or anonymous functions: let foo = function (arg) { ... } + +Infinite loop when you have this goal: +goal pod2man (page, section) = "docs/%page.%section" : "docs/%page.pod" { ... } +This is caused by %section matching "pod" so the rule is called +again, even if the local file docs/%page.pod actually exists. diff --git a/configure.ac b/configure.ac index d44209a..e3fd9ae 100644 --- a/configure.ac +++ b/configure.ac @@ -49,6 +49,10 @@ AC_CHECK_PROG(MENHIR, [menhir], [menhir], [ AC_MSG_ERROR([OCaml menhir parser generator is required]) ]) +AC_CHECK_PROG([POD2MAN], [pod2man], [pod2man], [ + AC_MSG_ERROR([pod2man tool from Perl is required]) +]) + dnl Substitute OCaml flags and packages. AC_SUBST([OCAMLFLAGS], ["-g -safe-string -warn-error CDEFLMPSUVYZX+52-3"]) AC_SUBST([OCAMLPACKAGES], ["-package str,unix"]) diff --git a/docs/goals.pod b/docs/goals.pod new file mode 100644 index 0000000..eca8876 --- /dev/null +++ b/docs/goals.pod @@ -0,0 +1,102 @@ +=encoding utf8 + +=head1 NAME + +goals - an experimental tool that generalizes "make" + +=head1 SUMMARY + + goals ['TARGET'] ['VAR=VALUE'] + [-C|--directory DIRECTORY] [-d] [-f|--file Goalfile] + [-I|--include DIRECTORY] [--no-prelude] + + goals --help + + goals -v|--version + +=head1 DESCRIPTION + + + +=head1 OPTIONS + +=over 4 + +=item B<-h> + +=item B<--help> + +Display short help summary and exit. + +=item B<-C> DIRECTORY + +=item B<--directory> DIRECTORY + +When goals starts up, and before reading the initial F or +doing any other processing, goals changes directory. + +=item B<-d> + +Enable very verbose debugging. + +=item B<-f> GOALFILE + +=item B<--file> GOALFILE + +Set the name of the initial goal file to read. The default name is +F. + +Note that if a relative path is given here, it is relative to the +directory specified with the I<-C> option, or to the current directory +if I<-C> was not used. + +=item B<-I> DIRECTORY + +=item B<--include> DIRECTORY + +Specify an include directory, used when including goal files using the +C directive. You can use this option multiple times. Later +directories have priority over earlier ones. There is also an +implicit C<%stdlib> directory which is used for prelude files (see +L). + +Note that if a relative path is given here, it is relative to the +directory specified with the I<-C> option, or to the current directory +if I<-C> was not used. + +=item B<--no-prelude> + +Do not load F from C<%stdlib>. The default is that the +prelude is always loaded automatically before any initial goal file +(but you can redefine prelude definitions in your goal file if you +want). + +=back + +=head1 SEE ALSO + +L, L, L. + +=head1 AUTHORS + +Richard W.M. Jones + +=head1 COPYRIGHT + +Copyright (C) 2020 Richard W.M. Jones + +Copyright (C) 2020 Red Hat Inc. + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program; if not, write to the Free Software Foundation, Inc., +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. -- 1.8.3.1