From d3af9c1e97c2022bbe220c77f8ee50afcb0b34db Mon Sep 17 00:00:00 2001 From: fpliu Date: Fri, 15 Apr 2022 18:25:25 +0800 Subject: [PATCH] Revert "buildsys: rewite man/Makefile.am" This reverts commit 0759cac8de253787b7a9f3e780e8ec7c562d4641. --- .github/workflows/testing-alpine.yml | 2 - makefiles/testing.mak | 6 +- man/Makefile.am | 194 ++++++++++---- man/build.sh | 363 --------------------------- 4 files changed, 144 insertions(+), 421 deletions(-) delete mode 100755 man/build.sh diff --git a/.github/workflows/testing-alpine.yml b/.github/workflows/testing-alpine.yml index f4c174dcef..43889f0bc9 100644 --- a/.github/workflows/testing-alpine.yml +++ b/.github/workflows/testing-alpine.yml @@ -20,8 +20,6 @@ jobs: steps: - run: apk add libc-dev gcc make automake autoconf pkgconf python3 file diffutils git - - run: git config --global --add safe.directory /__w/ctags/ctags - - uses: actions/checkout@v2 - run: cc --version diff --git a/makefiles/testing.mak b/makefiles/testing.mak index 78386a977e..14b17ea2c2 100644 --- a/makefiles/testing.mak +++ b/makefiles/testing.mak @@ -318,12 +318,12 @@ check-genfile: fi if HAVE_RST2MAN # man/*.in : committed for man pages to be genrated without rst2man -# make clean-docs remove both man/*.rst and docs/man/*.rst +# make clean-docs remove both man/*.in and docs/man/*.rst $(chkgen_verbose)$(MAKE) -C man clean-docs - $(chkgen_verbose)$(MAKE) -C man + $(chkgen_verbose)$(MAKE) -C man man-in $(chkgen_verbose)if ! git diff --exit-code -- man; then \ echo "Files under man/ are not up to date." ; \ - echo "Please execute 'make -C man' and commit them." ; \ + echo "Please execute 'make -C man man-in' and commit them." ; \ exit 1 ; \ else \ echo "Files under man are up to date." ; \ diff --git a/man/Makefile.am b/man/Makefile.am index 84047412f4..52bbe0dbce 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -1,5 +1,6 @@ # # This is a Makefile.am read by the Autotools. +# GNU Make is needed. # # Copyright (c) 2017, Masatake YAMMATO # Copyright (c) 2017, Red Hat, Inc. @@ -9,63 +10,150 @@ # later version. # -#SUFFIXES = .rst.in .rst .html .pdf +# Note: RST2MAN, RST2HTML, RST2PDF, and RST2MAN_OPTIONS are defined by configure.ac +RST2MAN_FLAGS = $(RST2MAN_OPTIONS) +RST2HTML_FLAGS = +RST2PDF_FLAGS = +DOCS_DIR = ../docs/man + +SUFFIXES = .rst .html .pdf .in + +# The man_MANS or dist_man_MANS requires conventional file names for man files. +# For example `$(basename $(files))` is not accepted. +GEN_IN_MAN_FILES = \ + ctags.1 \ + ctags-optlib.7 \ + ctags-incompatibilities.7 \ + ctags-client-tools.7 \ + ctags-faq.7 \ + \ + ctags-lang-gdscript.7 \ + ctags-lang-iPythonCell.7 \ + ctags-lang-julia.7 \ + ctags-lang-python.7 \ + ctags-lang-tcl.7 \ + ctags-lang-verilog.7 \ + ctags-lang-inko.7 \ + ctags-lang-r.7 \ + ctags-lang-rmarkdown.7 \ + ctags-lang-sql.7 \ + ctags-lang-elm.7 \ + \ + readtags.1 \ + tags.5 \ + \ + $(NULL) + +man_pages = $(GEN_IN_MAN_FILES) +man_in_files = $(addsuffix .in,$(man_pages)) +rst_files = $(addsuffix .rst,$(man_pages)) +html_pages = $(addsuffix .html,$(man_pages)) +pdf_pages = $(addsuffix .pdf,$(man_pages)) +doc_files = $(addprefix $(DOCS_DIR)/,$(rst_files)) + +# for automake +# generate man pages only when rst2man is installed +if HAVE_RST2MAN +man_MANS = $(man_pages) +endif +EXTRA_DIST = README $(addsuffix .rst.in,$(GEN_IN_MAN_FILES)) $(man_in_files) +CLEANFILES = $(man_pages) $(addsuffix .rst,$(GEN_IN_MAN_FILES)) $(html_pages) $(pdf_pages) +MAINTAINERCLEANFILES = $(man_in_files) + +.PHONY: man man-in html pdf update-docs clean-docs + +all-am: update-docs + +man: $(man_pages) +man-in: $(man_in_files) +html: $(html_pages) +pdf: $(pdf_pages) + +# use `[@]` not to be replaced by automake +REPLACE_CONF_VARS = sed \ + -e s/[@]CTAGS_NAME_EXECUTABLE[@]/ctags/g \ + -e s/[@]ETAGS_NAME_EXECUTABLE[@]/etags/g \ + -e s/[@]VERSION[@]/$(VERSION)/g + +rst2man_verbose = $(rst2man_verbose_@AM_V@) +rst2man_verbose_ = $(rst2man_verbose_@AM_DEFAULT_V@) +rst2man_verbose_0 = @echo RST2MAN " $@"; + +rst2html_verbose = $(rst2html_verbose_@AM_V@) +rst2html_verbose_ = $(rst2html_verbose_@AM_DEFAULT_V@) +rst2html_verbose_0 = @echo RST2HTML " $@"; + +rst2pdf_verbose = $(rst2pdf_verbose_@AM_V@) +rst2pdf_verbose_ = $(rst2pdf_verbose_@AM_DEFAULT_V@) +rst2pdf_verbose_0 = @echo RST2MAN " $@"; + +sed_verbose = $(sed_verbose_@AM_V@) +sed_verbose_ = $(sed_verbose_@AM_DEFAULT_V@) +sed_verbose_0 = @echo SED " $@"; + +rm_verbose = $(rm_verbose_@AM_V@) +rm_verbose_ = $(rm_verbose_@AM_DEFAULT_V@) +rm_verbose_0 = @echo RM " $@"; -VERBOSE = $(VERBOSE_@AM_V@) -VERBOSE_ = $(VERBOSE_@AM_DEFAULT_V@) -VERBOSE_0 = @ - -BUILD_OPTIONS = $(BUILD_OPTIONS_@AM_V@) -BUILD_OPTIONS_ = $(BUILD_OPTIONS_@AM_DEFAULT_V@) -BUILD_OPTIONS_1 = -v - -############################################################################# - -# https://www.gnu.org/software/autoconf/manual/autoconf-2.67/html_node/Preset-Output-Variables.html -# in this document, we use `abs_srcdir`, this is an absolute dir of this file. to prevent: No such file or directory - -rst: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) gen-rst +# +# generate man +# +# generate *.in to be distributed +%.in: %.rst.in +if HAVE_RST2MAN + $(rst2man_verbose)$(RST2MAN) $(RST2MAN_FLAGS) $< > $@ +else + $(error Cannot make $@: rst2man is not installed) +endif -man: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) rst2man $(RST2MAN_OPTIONS) +%: %.in + $(sed_verbose)$(REPLACE_CONF_VARS) < $< > $@ -pdf: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) rst2pdf $(RST2PDF_OPTIONS) +# +# generate HTML and PDF +# +%.rst: %.rst.in + $(sed_verbose)$(REPLACE_CONF_VARS) < $< > $@ + +%.html: %.rst +if HAVE_RST2HTML + $(rst2html_verbose)$(RST2HTML) $(RST2HTML_FLAGS) $< > $@ +else + $(error Cannot make $@: rst2html is not installed) +endif + +%.pdf: %.rst +if HAVE_RST2PDF + $(rst2pdf_verbose)$(RST2PDF) $(RST2PDF_FLAGS) $< -o $@ +else + $(error Cannot make $@: rst2pdf is not installed) +endif -html: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) rst2html $(RST2HTML_OPTIONS) +# +# generate $(DOCS_DIR)/*.rst for Sphinx document +# +update-docs: $(doc_files) + +# Convert the names of man page files (without suffix) to man page citations. +# ctags.1 tags.5 ... => ctags(1) tags(5) ... +cites := ${subst .,(,${addsuffix ),${man_pages}}} + +# Convert the man page citations to sed patterns for making hyperlinks. +# ctags(1) tags(5) ... +# => -e 's/\`/g' -e 's/\`/g' ... +if HAS_GNU_SED +reppat := $(foreach m,$(cites),-e 's/\<$(m)/:ref:`& <&>`/g') +else +reppat := $(foreach m,$(cites),-e 's/[[:<:]]$(m)/:ref:`& <&>`/g') +endif + +# Delete the line "------" in the first 10 lines of $(DOCS_DIR)/*.rst to +# suppress unnecessary section indices. +$(DOCS_DIR)/%.rst: %.rst + @$(MKDIR_P) $(DOCS_DIR) + $(sed_verbose)sed $(reppat) -e '1,10s/^-*$$//' < $< > $@ # remove generated files to be commited (used for `make checkgen`) +clean-local: clean-docs clean-docs: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) clean rst doc - -update-docs: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) update-docs - -.PHONY: rst man pdf html clean-docs update-docs - -############################################################################# - -# this target will be automatically invoked when you run `make clean` -# https://www.gnu.org/software/automake/manual/html_node/Extending.html -clean-local: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) clean rst man pdf html doc - -# this target will be automatically invoked when you run `make maintainer-clean` -# https://www.gnu.org/software/automake/manual/html_node/Extending.html -maintainer-clean-local: - $(VERBOSE)$(abs_srcdir)/build.sh $(BUILD_OPTIONS) clean rst - -# this target will be automatically invoked when you run `make dist` -# https://www.gnu.org/software/automake/manual/html_node/The-dist-Hook.html -dist-hook: rst - $(VERBOSE)for item in $$(cd $(abs_srcdir) && ls *.rst*) build.sh ; do cp -f $(BUILD_OPTIONS) $(abs_srcdir)/$$item $(distdir)/$$item; done - -# this target will be automatically invoked when you run `make install` -# https://www.gnu.org/software/automake/manual/html_node/Extending.html -install-exec-hook: - $(VERBOSE)if $(abs_srcdir)/build.sh $(BUILD_OPTIONS) find-exec rst2man > /dev/null ; then \ - $(abs_srcdir)/build.sh $(BUILD_OPTIONS) rst2man $(RST2MAN_OPTIONS) ; \ - $(abs_srcdir)/build.sh $(BUILD_OPTIONS) install-mans $(mandir) ; else \ - printf '%s\n' "NOTE: DO NOT INSTALL MAN-PAGES due to rst2man not found."; fi + $(rm_verbose)rm -f $(man_in_files) $(doc_files) diff --git a/man/build.sh b/man/build.sh deleted file mode 100755 index 3aec54c1c8..0000000000 --- a/man/build.sh +++ /dev/null @@ -1,363 +0,0 @@ -#!/bin/sh - -set -e - -COLOR_RED='\033[0;31m' # Red -COLOR_GREEN='\033[0;32m' # Green -COLOR_PURPLE='\033[0;35m' # Purple -COLOR_OFF='\033[0m' # Reset - -success() { - printf '%b\n' "${COLOR_GREEN}[✔] $*${COLOR_OFF}" >&2 -} - -die() { - printf '%b\n' "${COLOR_RED}💔 $*${COLOR_OFF}" >&2 - exit 1 -} - -# usage: die_due_to_command_not_found -# example: die_due_to_command_not_found rst2mam docutils https://docutils.sourceforge.io/ -die_due_to_command_not_found() { - printf '%b\n' "${COLOR_RED}💔 command not found:${COLOR_OFF} ${COLOR_GREEN}$1${COLOR_OFF} - ${COLOR_RED}Please install${COLOR_OFF} ${COLOR_GREEN}$1${COLOR_OFF} ${COLOR_RED}utility which is usually shipped with${COLOR_OFF} ${COLOR_GREEN}$2${COLOR_OFF} ${COLOR_RED}package.${COLOR_OFF} - ${COLOR_RED}To find more information, please go to website${COLOR_OFF} ${COLOR_GREEN}$3${COLOR_OFF}" >&2 - exit 1 -} - -run() { - if [ "$V" = yes ] ; then - printf '%b\n' "${COLOR_PURPLE}==>${COLOR_OFF} ${COLOR_GREEN}$*${COLOR_OFF}" - fi - - eval "$*" -} - -# usage: find_exec -# example: find_exec rst2man -find_exec() { - case $1 in - '') die "$_0 find-exec , must not be empty." ;; - rst2man) - for item in rst2man rst2man.py rst2man-3 rst2man-3.6 rst2man-3.7 rst2man-3.8 rst2man-3.9 - do - command -v "$item" && break - done - ;; - rst2html) - for item in rst2html rst2html.py rst2html-3 rst2html-3.6 rst2html-3.7 rst2html-3.8 rst2html-3.9 - do - command -v "$item" && break - done - ;; - *) command -v "$1" - esac -} - -gen_rst() { - for RST_IN_FILENAME in *.rst.in - do - run "sed -e 's/@CTAGS_NAME_EXECUTABLE@/ctags/g' -e 's/@ETAGS_NAME_EXECUTABLE@/etags/g' -e 's/@VERSION@/5.9.0/g' ${RST_IN_FILENAME} > ${RST_IN_FILENAME%.in}" - done -} - -# usage: gen_man [RST2MAN-COMMAND-OPTOPNS] -# example: gen_man rst2man -# example: gen_man rst2man --syntax-highlight=none -# example: gen_man /usr/local/bin/rst2man --syntax-highlight=none -gen_man() { - unset RST2MAN - - case $1 in - rst2man) - RST2MAN=$(find_exec rst2man) || die_due_to_command_not_found rst2man docutils https://docutils.sourceforge.io/ ;; - '') [ -z "$1" ] && die "$_0 [RST2MAN-COMMAND-OPTOPNS], must be not empty." ;; - *) [ -e "$1" ] || die "$_0 [RST2MAN-COMMAND-OPTIONS], file is not exist: $1" - RST2MAN="$1" - esac - - shift - - gen_rst - - RST2MAN_OPTIONS=$@ - - if [ -z "$RST2MAN_OPTIONS" ] && [ -n "$($RST2MAN --help | sed -n '/--syntax-highlight/p')" ] ; then - RST2MAN_OPTIONS='--syntax-highlight=none' - fi - - for RST_IN_FILENAME in *.rst.in - do - run "$RST2MAN $RST2MAN_OPTIONS ${RST_IN_FILENAME%.in} > ${RST_IN_FILENAME%.rst.in}" - done -} - -# usage: gen_html [RST2HTML-COMMAND-OPTOPNS] -# example: gen_html rst2html -# example: gen_html /usr/local/bin/rst2html --syntax-highlight=none -gen_html() { - unset RST2HTML - - case $1 in - rst2html) - RST2HTML=$(find_exec rst2html) || die_due_to_command_not_found rst2html docutils https://docutils.sourceforge.io/ ;; - '') [ -z "$1" ] && die "$_0 [RST2HTML-COMMAND-OPTOPNS], must be not empty." ;; - *) [ -e "$1" ] || die "$_0 [RST2HTML-COMMAND-OPTIONS], file is not exist: $1" - RST2HTML="$1" - esac - - shift - - gen_rst - - for RST_IN_FILENAME in *.rst.in - do - run "$RST2HTML $@ ${RST_IN_FILENAME%.in} > ${RST_IN_FILENAME%.rst.in}.html" - done -} - -# usage: gen_pdf [RST2PDF-COMMAND-OPTOPNS] -# example: gen_pdf rst2pdf -# example: gen_pdf /usr/local/bin/rst2pdf -gen_pdf() { - unset RST2PDF - - case $1 in - rst2pdf) - RST2PDF=$(find_exec rst2pdf) || die_due_to_command_not_found rst2pdf rst2pdf https://rst2pdf.org/ ;; - '') [ -z "$1" ] && die "$_0 [RST2PDF-COMMAND-OPTOPNS], must be not empty." ;; - *) [ -e "$1" ] || die "$_0 [RST2PDF-COMMAND-OPTIONS], file is not exist: $1" - RST2PDF="$1" - esac - - shift - - gen_rst - - for RST_IN_FILENAME in *.rst.in - do - run "$RST2PDF $@ -o ${RST_IN_FILENAME%.rst.in}.pdf ${RST_IN_FILENAME%.in}" - done -} - -update_docs() { - gen_rst - - # Delete the line "------" in the first 10 lines of ../docs/man/*.rst to suppress unnecessary section indices. - SED_SCRIPT="-e '1,10s/^-*$//'" - - # ctags.1.rst.in -> ctags(1) - for item in $(ls *.rst.in | sed 's|\(.*\)\.\([1-9]\)\.rst\.in|\1(\2)|') - do - # => -e 's/\`/g' -e 's/\`/g' ... - SED_SCRIPT="$SED_SCRIPT -e 's/\<$item/:ref:\`& <&>\`/g'" - done - - for RST_IN_FILENAME in *.rst.in - do - RST_OUT_FILENAME="${RST_IN_FILENAME%.in}" - RST_OUT_FILEPATH="../docs/man/$RST_OUT_FILENAME" - - run "sed $SED_SCRIPT $RST_OUT_FILENAME > $RST_OUT_FILEPATH" - done -} - -# usage: install_mans -# example: install_mans /usr/local/share/man -install_mans() { - if [ -z "$1" ] ; then - die "$_0 install-mans , must be not empty." - fi - - unset MAN_FILE_NAMES - MAN_FILE_NAMES=$(ls *.[1-9].rst.in | sed 's|\.rst\.in$||') - - for MAN_FILE_NAME in $MAN_FILE_NAMES - do - if [ -f "$MAN_FILE_NAME" ] ; then - continue - else - die "$PWD/$MAN_FILE_NAME not exists. you should run ${COLOR_GREEN}./build.sh rst2man [OPTIONS]${COLOR_OFF} ${COLOR_RED}first." - fi - done - - for MAN_FILE_NAME in $MAN_FILE_NAMES - do - unset MAN_FILE_SECTION_NUMBER - MAN_FILE_SECTION_NUMBER="$(printf '%s\n' "$MAN_FILE_NAME" | sed 's|.*\.\([1-9]\)|\1|')" - - MAN_FILE_NAME_INSTALL_DIR="$1/man$MAN_FILE_SECTION_NUMBER" - - if [ ! -d "$MAN_FILE_NAME_INSTALL_DIR" ] ; then - run install -d "$MAN_FILE_NAME_INSTALL_DIR" - fi - - run install "$MAN_FILE_NAME" "$MAN_FILE_NAME_INSTALL_DIR/$MAN_FILE_NAME" - done -} - -print_files() { - for item in $@ - do - case $item in - rst|man|pdf|html|doc|all) ;; - *) die "$_0 print-files ..., unrecognized : $item. must be one or more of rst man pdf html doc all" - esac - done - - unset WHAT_LIST - - if [ -z "$1" ] ; then - WHAT_LIST='rst man pdf html doc' - else - WHAT_LIST=$@ - fi - - for item in $WHAT_LIST - do - case $item in - rst) ls *.[1-9].rst.in | sed 's|\.rst\.in$|.rst|' ;; - man) ls *.[1-9].rst.in | sed 's|\.rst\.in$||' ;; - pdf) ls *.[1-9].rst.in | sed 's|\.rst\.in$|.pdf|' ;; - html) ls *.[1-9].rst.in | sed 's|\.rst\.in$|.html|' ;; - doc) ls *.[1-9].rst.in | sed 's|\.rst\.in$|.rst|' | sed 's|^|../docs/man/|' - esac - done -} - -# usage: clean ... -# example: clean man -# example: clean pdf -# example: clean html -# example: clean rst -# example: clean doc -# example: clean all -clean() { - for item in $@ - do - case $item in - rst|man|pdf|html|doc|all) ;; - *) die "$_0 clean ..., unrecognized : $item. must be one or more of rst man pdf html doc all" - esac - done - - unset WHAT_LIST - - if [ -z "$1" ] ; then - WHAT_LIST='rst man pdf html doc' - else - WHAT_LIST=$@ - fi - - RM_OPTIONS=-f - - if [ "$V" = yes ] ; then - RM_OPTIONS="$RM_OPTIONS -v" - fi - - # here we use for loop , not use xargs , because xargs is not pre-installed in some os(As far as I known, RockyLinux, Fedora). - for item in $WHAT_LIST - do - case $item in - rst) run "for file in \$(ls *.[1-9].rst.in | sed 's|\.rst\.in$|.rst|' ); do rm $RM_OPTIONS \$file; done" ;; - man) run "for file in \$(ls *.[1-9].rst.in | sed 's|\.rst\.in$||' ); do rm $RM_OPTIONS \$file; done" ;; - pdf) run "for file in \$(ls *.[1-9].rst.in | sed 's|\.rst\.in$|.pdf|' ); do rm $RM_OPTIONS \$file; done" ;; - html) run "for file in \$(ls *.[1-9].rst.in | sed 's|\.rst\.in$|.html|'); do rm $RM_OPTIONS \$file; done" ;; - doc) run "for file in \$(ls *.[1-9].rst.in | sed 's|\.rst\.in$|.rst|' | sed 's|^|../docs/man/|'); do rm $RM_OPTIONS \$file; done" - esac - done -} - -help() { - printf '%b\n' " -${COLOR_GREEN}$_0 [-x] [-v] [ARGUMENTS or OPTIONS]${COLOR_OFF} - - -${COLOR_GREEN}$_0 [-x] [-v] gen-rst${COLOR_OFF} - ctags.1.rst.in -> ctags.1.rst - -${COLOR_GREEN}$_0 [-x] [-v] rst2man [OPTIONS]${COLOR_OFF} - ctags.1.rst.in -> ctags.1.rst -> ctags.1 - -${COLOR_GREEN}$_0 [-x] [-v] rst2pdf [OPTIONS]${COLOR_OFF} - ctags.1.rst.in -> ctags.1.rst -> ctags.1.pdf - -${COLOR_GREEN}$_0 [-x] [-v] rst2html [OPTIONS]${COLOR_OFF} - ctags.1.rst.in -> ctags.1.rst -> ctags.1.html - -${COLOR_GREEN}$_0 [-x] [-v] update-docs${COLOR_OFF} - ctags.1.rst.in -> ctags.1.rst -> ../docs/man/ctags.1.rst - -${COLOR_GREEN}$_0 [-x] [-v] install-mans ${COLOR_OFF} - ctags.1 -> /man1/ctags.1 - -${COLOR_GREEN}$_0 [-x] [-v] print-files ${COLOR_OFF} - print the given type of to be generated files. - -${COLOR_GREEN}$_0 [-x] [-v] clean ${COLOR_OFF} - remove the given type of generated files. - -${COLOR_GREEN}$_0 [-x] [-v] find-exec ${COLOR_OFF} - find the given command name in PATH. if command not found, the result code will be 1. - " -} - -main() { - while [ -n "$1" ] - do - case $1 in - -x) set -x ;; - -v) V=yes ;; - *) break - esac - shift - done - - case $1 in - ''|-h|--help) help ; exit ;; - esac - - if [ "$1" != find-exec ] ; then - command -v sed > /dev/null || die_due_to_command_not_found sed sed https://www.gnu.org/software/sed/ - cd "$(dirname "$_0")" - fi - - case $1 in - gen-rst) - gen_rst - ;; - *rst2man|*rst2man.py) - gen_man $@ - ;; - *rst2html|*rst2html.py) - gen_html $@ - ;; - *rst2pdf|*rst2pdf.py) - gen_pdf $@ - ;; - update-docs) - update_docs - ;; - install-mans) - shift - install_mans $@ - ;; - clean) - shift - clean $@ - ;; - find-exec) - shift - find_exec $@ - ;; - print-files) - shift - print_files $@ - ;; - *) die "unrecognized argument: $1" - esac -} - -_0=$0 - -main $@