mercury/doc/Mmakefile

#-----------------------------------------------------------------------------#
# vim: ts=8 sw=8 noexpandtab ft=make
#-----------------------------------------------------------------------------#
# Copyright (C) 1996-2007, 2009-2012 The University of Melbourne.
# Copyright (C) 2013-2017, 2019-2020, 2022-2023, 2025 The Mercury team.
# This file may only be copied under the terms of the GNU General
# Public License - see the file COPYING in the Mercury distribution.
#-----------------------------------------------------------------------------#

# Mmakefile - Mmake file for the Mercury documentation.

MAIN_TARGET=all

MERCURY_DIR=..
include $(MERCURY_DIR)/Mmake.common

#-----------------------------------------------------------------------------#

# Man pages are built automatically, by the `make_manpage' program,
# which runs the program with `--help' and then munges the result.
# This variable specifies which programs to create man pages for.

MANPAGE_PROGS = \
	c2init			\
	mdb			\
	mercury_config		\
	mgnuc			\
	ml			\
	mmc			\
	mmake			\
	mprof			\
	mprof_merge_runs	\
	mtags			\
	mtc

mmc.1: ../compiler/handle_options.m ../compiler/options.m

mprof.1: ../profiler/mercury_profile.m ../profiler/options.m

# This variable specifies the (top-level) TexInfo files.
# NOTE: any changes in these names will need to be reflected in the website.
TEXINFO_FILES = \
	mercury_user_guide \
	mercury_reference_manual \
	mercury_library_manual \
	mercury_faq \
	mercury_transition_guide
# The old names of the TEXINFO_INFO_FILES:
# 	mercury_user_guide.info
# 	mercury_ref.info
# 	mercury_library.info
# 	mercury_faq.info
# 	mercury_trans_guide.info
TEXINFO_INFO_FILES = $(patsubst %,%.info,$(TEXINFO_FILES))

# The following variables specify which programs should be used to
# to format the documentation.

TEXI2HTML="$(MAKEINFO)" --html --number-sections --no-split
TEXI2HTML_SPLIT="$(MAKEINFO)" --html --number-sections

ifeq ("$(MAKEINFO)","")
	HTML=warn_no_html
else
	HTML=html
endif

ifeq ("$(TEXI2DVI)","")
	DVI=warn_no_dvi
	PS=warn_no_ps
else
	DVI=dvi
	ifeq ("$(DVIPS)","")
		PS=warn_no_ps
	else
		PS=ps
	endif
endif

ifeq ("$(PDFTEX)","")
	PDF=warn_no_pdf
else
	PDF=pdf
endif

ifeq ("$(MAKEINFO)","")
	INFOPAGES=warn_no_info
	MDB_DOC=warn_no_mdb_doc
else
	ifeq ("$(INFO)","")
		MDB_DOC=warn_no_mdb_doc
	else
		MDB_DOC=mdb_doc mdb_command_list mdb_command_test.inp
	endif
	INFOPAGES=info
endif

#-----------------------------------------------------------------------------#

.SUFFIXES: .in .texi_pp .texi .dvi .dvi_log .ps .pdf .pdf_log .text

%.dvi: %.texi_pp
	-"$(TEXI2DVI)" $< < /dev/null > $*.dvi_log

%.ps: %.dvi
	"$(DVIPS)" -f < $< > $@

%.pdf: %.texi_pp %.dvi
	"$(PDFTEX)" $< < /dev/null > $*.pdf_log

%.text: %.texi_pp
	"$(MAKEINFO)" --no-headers -o $@ $<

M_ENV = \
	MERCURY_PROFILER=../profiler/mercury_profile \
	MERCURY_COMPILER=../compiler/mercury_compile \
	MERCURY_MKINIT=../util/mkinit \
	MCFLAGS=--no-mercury-stdlib-dir

%.1: ../scripts/% make_manpage
	$(M_ENV) $< --help 2>&1 | \
		awk -f make_manpage -v date=$(shell date "+%Y-%m-%d") > $@

%.man: %.1
	nroff -man $< > $@

# .help files just contain the output of running the command with `--help'.
# They are sometimes useful for debugging "make_manpage".
%.help: ../scripts/%
	$(M_ENV) $< --help > $@ 2>&1

SED_CMD = sed -e "s/<VERSION>/$(VERSION)/g" < $< > $@

%.texi_pp: %.texi ../VERSION
	$(SED_CMD)

mercury.html: mercury.html.in ../VERSION
	$(SED_CMD)

mercury.info: mercury.info.in ../VERSION
	$(SED_CMD)

# mercury_user_guide.texi_pp @includes ug_invocation.texi, so all targets
# that want to process mercury_user_guide.texi must make ug_invocation.texi
# first. mercury_user_guide.texi_pp is the only such *direct* target;
# all the others go through it.
mercury_user_guide.texi_pp: ug_invocation.texi

# The rule for ug_invocation.texi_date compares any existing
# file ug_invocation.texi against its "new" intended contents, and
# leaves it unchanged, including its timestamp, if the "new" contents
# would be the same as the old. Then, after gmake executes  @:,
# the silent do-nothing command, it will believe that ug_invocation.texi
# is up-to-date regardless of whether the rule for ug_invocation.texi_date
# updated it or not.
#
# This is the same scheme that scripts/Mmake.rules uses for e.g.
# .int and .date files. Both copies of this scheme lead to strange errors
# if the timestamp file exists but the file it is the timestamp OF has been
# deleted. This is not usually a problem though, first because making
# such deletions accidentally is rare, and second because an "mmake clean"
# fixes the issue by deleting the timestamp file as well.

ug_invocation.texi: ug_invocation.texi_date
	@:

# If we are building the source distribution or if we are cross-compiling,
# then either we will not have a mercury_compile executable, or we may not be
# able to run it. In both cases, we just use the bootstrap compiler to generate
# ug_invocation.texi, assuming the bootstrap compiler is the same or a similar
# version.
ifdef BUILD_SRCDIST
UG_INVOCATION_DEP=
UG_INVOCATION_MC=$(MC)
else
ifeq ($(CROSS_COMPILING),yes)
UG_INVOCATION_DEP=
UG_INVOCATION_MC=$(MC)
else
# We do not specify the executable extension $(EXT_FOR_EXE) here because we
# need a way to refer to the compiler that works regardless of the grade in
# which it is compiled, and on all platforms. The extension that $(EXT_FOR_EXE)
# stands for
#
# - will not be present on the launcher scripts generated in the non-C grades,
# - will not be present on the executable in C grades on Unix-like systems, and
# - while it will be present on the executable in C grades on Windows,
#   gmake on Windows contains code to add it for us, to both UG_INVOCATION_DEP
#   and UG_INVOCATION_MC.
#
UG_INVOCATION_DEP=../compiler/mercury_compile
UG_INVOCATION_MC=../compiler/mercury_compile
endif
endif

ug_invocation.texi_date: $(UG_INVOCATION_DEP)
	@echo checking whether ug_invocation.texi is up to date
	@$(UG_INVOCATION_MC) --help-texinfo \
		--no-mercury-stdlib-dir \
		--config-file ../scripts/Mercury.config \
		> ug_invocation.texi_new
	@if cmp -s ug_invocation.texi ug_invocation.texi_new; then \
		/bin/rm ug_invocation.texi_new; \
	else \
		mv -f ug_invocation.texi_new ug_invocation.texi; \
	fi
	@date > ug_invocation.texi_date

#-----------------------------------------------------------------------------#

# Currently `mmake all' does not build the PostScript, PDF or plain-text
# versions of the documentation. Nor does it build the formatted versions
# of the man pages. But it might make sense to add them.
# XXX As of 2025 aug 11, making the pdfs by default breaks the construction
# of the source distribution, because testing.mercurylang.org is missing 
# the necessary tools.
.PHONY: all
all: $(INFOPAGES) $(DVI) $(HTML) manpages $(MDB_DOC)
# all: ps pdf text formatted_manpages

#-----------------------------------------------------------------------------#

.PHONY: dvi
dvi: $(TEXINFO_FILES:%=%.dvi)

.PHONY: warn_no_dvi
warn_no_dvi:
	# Warning: Unable to build .dvi files.
	# This is probably due to a missing `texi2dvi'.

.PHONY: info
info: mercury.info $(TEXINFO_INFO_FILES)

.PHONY: warn_no_info
warn_no_info:
	# Warning: Unable to build .info files.
	# This is probably due to a missing `makeinfo'.

.PHONY: html
html: mercury.html $(TEXINFO_INFO_FILES:%.info=%.html)

.PHONY: warn_no_html
warn_no_html:
	# Warning: Unable to build .html files.
	# This is probably due to a missing `perl'.

.PHONY: ps
ps: $(TEXINFO_FILES:%=%.ps)

.PHONY: warn_no_ps
warn_no_ps:
	# Warning: Unable to build .ps files.
	# This is probably due to a missing `dvips' or `text2dvi'.

.PHONY: pdf
pdf: $(TEXINFO_FILES:%=%.pdf)

.PHONY: warn_no_pdf
warn_no_pdf:
	# Warning: Unable to build .pdf files.
	# This is probably due to a missing `pdftex'.

.PHONY: text
text: $(TEXINFO_FILES:%=%.text)

.PHONY: split_html
split_html: mercury.html $(TEXINFO_INFO_FILES:%.info=%/index.html)

.PHONY: manpages
manpages: $(MANPAGE_PROGS:%=%.1)

.PHONY: formatted_manpages
formatted_manpages: $(MANPAGE_PROGS:%=%.man)

.PHONY: help
help: $(MANPAGE_PROGS:%=%.help)

#-----------------------------------------------------------------------------#

%.info: %.texi_pp
	"$(MAKEINFO)" --no-split $<

%.html: %.texi_pp
	$(TEXI2HTML) $<

# XXX Why is one, and only one, of these files split by chapter?
mercury_user_guide/index.html: mercury_user_guide.texi_pp
	$(TEXI2HTML_SPLIT) $<
mercury_reference_manual/index.html: mercury_reference_manual.texi_pp
	$(TEXI2HTML_SPLIT) --split=chapter --no-headers $<
mercury_transition_guide/index.html: mercury_transition_guide.texi_pp
	$(TEXI2HTML_SPLIT) $<
mercury_faq/index.html: mercury_faq.texi_pp
	$(TEXI2HTML_SPLIT) $<
mercury_library_manual/index.html: mercury_library_manual.texi_pp
	$(TEXI2HTML_SPLIT) $<

#-----------------------------------------------------------------------------#

.PHONY: warn_no_mdb_doc
warn_no_mdb_doc:
	# Warning: Unable to build mdb documentation.
	# This is probably due to a missing `makeinfo' or `info'.
	cp mdb_doc_stub.txt mdb_doc

mdb_doc: generate_mdb_doc mercury_user_guide.info mdb_categories
	./generate_mdb_doc

mdb_command_list: generate_mdb_command_list mdb_doc
	./generate_mdb_command_list < mdb_doc > mdb_command_list
	-@if test `wc -l < mdb_command_list` -lt 100; then \
		echo "There was a problem when creating mdb_command_list"; \
		exit 1; \
	fi

mdb_command_test.inp: generate_mdb_command_test mdb_doc
	./generate_mdb_command_test < mdb_doc > mdb_command_test.inp
	-@if test `wc -l < mdb_command_test.inp` -lt 100; then \
		echo "There was a problem when creating mdb_command_test.inp"; \
		exit 1; \
	fi

#-----------------------------------------------------------------------------#

# The following rules automatically build the library documentation
# by extracting the module interfaces from the library source code.
# Note that some modules are just implementation details of the Mercury
# system, so they are not documented.

mercury_library_menu.texi_pp: ../VERSION $(LIBRARY_DIR)/*.m
	{ 								\
	echo "";							\
	for filename in `cat $(LIBRARY_DIR)/MODULES_DOC`; do		\
		echo "* `basename $$filename .m`::";			\
	done;								\
	} > mercury_library_menu.texi_pp

mercury_library_chapters.texi_pp: ../VERSION $(LIBRARY_DIR)/*.m
	for filename in `cat $(LIBRARY_DIR)/MODULES_DOC`; do		\
		file="`basename $$filename .m`"; 			\
		echo "@node $$file"; 					\
		echo "@chapter $$file"; 				\
		echo "@example"; 					\
		sed -n -e '/:- implementation/q' 			\
			-e '/UNDOC_PART_START/,/UNDOC_PART_END/d'	\
			-e '/NOTE_TO_IMPLEMENTORS/d'			\
			-e 's/^%----*----% *$$/%--------------------------------------------------%/' 	\
			-e 's/@/@@/g' 					\
			-e 's/{/@{/g' 					\
			-e 's/}/@}/g' 					\
			-e 'p' 						\
			$(LIBRARY_DIR)/"$$filename";			\
		echo "@end example"; 					\
		echo ""; 						\
	done > mercury_library_chapters.texi_pp

mercury_library_manual.dvi_log \
		mercury_library_manual.info \
		mercury_library_manual.html \
		mercury_library_manual/index.html \
		mercury_library_manual.dvi: \
	mercury_library_menu.texi_pp mercury_library_chapters.texi_pp

#-----------------------------------------------------------------------------#

.PHONY: dist
dist: tar

.PHONY: tar
tar: doc.text.tar.gz doc.ps.tar.gz

doc.text.tar.gz: text
	tar -cf - *.text | gzip > doc.text.tar.gz

doc.ps.tar.gz: ps
	tar -cf - *.ps | gzip > doc.ps.tar.gz

#-----------------------------------------------------------------------------#

# Currently `mmake all' does not build the PostScript or plain-text versions
# of the documentation. If they are added they should be installed here.
.PHONY: install
install: install_info install_html install_dvi install_pdf install_manpages \
	install_mdb_doc
	# install_text install_ps

.PHONY: install_dirs
install_dirs:
	-test -d $(INSTALL_INFO_DIR) || mkdir -p $(INSTALL_INFO_DIR)
	-test -d $(INSTALL_HTML_DIR) || mkdir -p $(INSTALL_HTML_DIR)
	-test -d $(INSTALL_DVI_DIR) || mkdir -p $(INSTALL_DVI_DIR)
	-test -d $(INSTALL_TEXT_DIR) || mkdir -p $(INSTALL_TEXT_DIR)
	-test -d $(INSTALL_PS_DIR) || mkdir -p $(INSTALL_PS_DIR)
	-test -d $(INSTALL_PDF_DIR) || mkdir -p $(INSTALL_PDF_DIR)
	-test -d $(INSTALL_MAN_DIR)/man1 || \
		mkdir -p $(INSTALL_MAN_DIR)/man1
	-test -d $(INSTALL_MDB_DOC_DIR) || mkdir -p $(INSTALL_MDB_DOC_DIR)

.PHONY: install_info
install_info: $(INFOPAGES) install_dirs
	-cp *.info *.info-* $(INSTALL_INFO_DIR)
	# Update the .../info/dir file.
	-if test -x "$(INSTALL_INFO)" ; then				\
		$(INSTALL_INFO) $(INSTALL_INFO_DIR)/mercury.info;	\
	fi

.PHONY: warn_no_install_info
warn_no_install_info:
	# Warning: Unable to install .info files.
	# This is probably due to a missing `install-info'.

.PHONY: install_html
install_html: $(HTML) install_dirs
	-cp *.html $(INSTALL_HTML_DIR)

.PHONY: install_dvi
install_dvi: $(DVI) install_dirs
	# It is possible that there are no .dvi files here,
	# if the TEXI2DVI command generates PDF directly.
	-cp *.dvi $(INSTALL_DVI_DIR)

.PHONY: install_text
install_text: text install_dirs
	cp *.txt $(INSTALL_TEXT_DIR)

.PHONY: install_ps
install_ps: $(PS) install_dirs
	-cp *.ps $(INSTALL_PS_DIR)

.PHONY: install_pdf
install_pdf: $(PDF) install_dirs
	-cp *.pdf $(INSTALL_PDF_DIR)

.PHONY: install_manpages
install_manpages: manpages install_dirs
	cp *.1 $(INSTALL_MAN_DIR)/man1

.PHONY: install_mdb_doc
install_mdb_doc: $(MDB_DOC) install_dirs
	-cp mdb_doc $(INSTALL_MDB_DOC_DIR)

# The uninstall rule here only removes the info files; the others
# are removed by the top-level uninstall rule.
#
# XXX What is the reason for this split, or indeed for any other split?
#
# XXX We also remove man pages here.
.PHONY: uninstall
uninstall:
	-cd $(INSTALL_INFO_DIR); rm -f mercury*.info*
	-cd $(INSTALL_MAN_DIR)/man1; rm -f $(MANPAGE_PROGS:%=%.1)

#-----------------------------------------------------------------------------#

# This install is for installing the Mercury webpage, which goes to
# a different directory (supplied by the environment variable
# INSTALL_WEBPAGE_DIR).

.PHONY: install_webpage
install_webpage: mercury_library_chapters.texi_pp split_html ps pdf
	-test -d $(INSTALL_WEBPAGE_DIR) || mkdir -p $(INSTALL_WEBPAGE_DIR)
	( \
		. ../VERSION; \
		if test "$$VERSION" = DEV ; then \
			echo "Set the version before you build the website"; \
			exit 1; \
		fi; \
	)
	cp *.ps $(INSTALL_WEBPAGE_DIR)
	cp *.pdf $(INSTALL_WEBPAGE_DIR)
	for file in $(INSTALL_WEBPAGE_DIR)/*.ps ; do \
		gzip -f -9 $$file ; \
	done
	cp -r $(TEXINFO_INFO_FILES:%.info=%) $(INSTALL_WEBPAGE_DIR)

webpage.tar.gz:
	rm -rf webpage
	mmake INSTALL_WEBPAGE_DIR=webpage install_webpage
	tar -zcf webpage.tar.gz webpage/

#-----------------------------------------------------------------------------#

clean_local: clean_texi clean_manpages clean_webpage

.PHONY: distclean
distclean: clean_local clean_text_files

realclean_local: distclean

.PHONY: clean_texi
clean_texi:
	rm -f *.aux *.cp *.cps *.fn *.ky *.log *.pg *.toc *.tp *.vr
	rm -f *.dvi *.dvi_log *.pdf *.pdf_log *.ps *.ps_log *.text
	rm -f library*.html mercury_library_manual*.html
	rm -f mercury_user_guide*.html mercury_reference_manual*.html
	rm -f mercuy_faq*.html mercuy_transition_guide*.html
	rm -f mercury.html mercury.info
	rm -f mercury_*.info*
	rm -f mercury_faq.html mercury_library_manual.html \
		mercury_reference_manual.html \
		mercury_transition_guide.html mercury_user_guide.html
	rm -f ug_invocation.texi_date ug_invocation.texi
	rm -rf $(TEXINFO_INFO_FILES:%.info=%)

.PHONY: clean_text_files
clean_text_files:
	rm -f mdb_command_list mdb_command_test.inp mdb_doc
	rm -f mercury_library_menu.texi mercury_library_chapters.texi *.texi_pp

.PHONY: clean_manpages
clean_manpages:
	rm -f *.1

.PHONY: clean_webpage
clean_webpage:
	rm -rf webpage
	rm -f webpage.tar.gz

#-----------------------------------------------------------------------------#