flintlib · albinahlback · Jan 29, 2025 · Jan 29, 2025 · Jan 29, 2025 · Jan 29, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -29,7 +29,7 @@ jobs:
 
       - name: "Setup"
         run: |
-          sudo apt-get install -y python3-sphinx texlive-full
+          sudo apt-get install -y python3-sphinx texlive-full m4
           sphinx-build --version
 
       - name: "Build documentation"

diff --git a/.gitignore b/.gitignore
@@ -30,6 +30,7 @@ doc/latex/flint-manual.*
 !doc/latex/flint-manual.tex
 doc/latex/input/*
 doc/latex/create_doc
+doc/source/*.rst
 libflint*
 *.suo
 *.pyc

diff --git a/doc/Makefile b/doc/Makefile
@@ -6,15 +6,34 @@ SPHINXOPTS    = -j=auto
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = flint
 SOURCEDIR     = source
+ORIGSRCDIR    = origsrc
 BUILDDIR      = build
 
+M4 := m4
+
+SPHINX_ACTIONS := html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf latexpdfja text man texinfo info gettext changes xml pseudoxml linkcheck doctest coverage
+
+CONFIG := macros.m4
+SRCS := $(wildcard $(ORIGSRCDIR)/*.rst)
+OBJS := $(patsubst $(ORIGSRCDIR)/%,$(SOURCEDIR)/%,$(SRCS))
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+$(SOURCEDIR)/%.rst: $(ORIGSRCDIR)/%.rst $(CONFIG)
+	@$(M4) $< > $@
+
+preprocess: $(OBJS)
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
+$(SPHINX_ACTIONS): Makefile preprocess
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -f $(OBJS)
+	rm -rf $(BUILDDIR)
+
+print-%:
+	@echo "$*=$($*)"
+
+.PHONY: help Makefile preprocess
diff --git a/doc/macros.m4 b/doc/macros.m4
@@ -0,0 +1,148 @@
+dnl############################################################################
+dnl Change quotation marks to avoid conflicts
+dnl############################################################################
+changequote({{{,}}})dnl
+dnl############################################################################
+dnl notation
+dnl############################################################################
+define({{{_neg_}}},dnl
+{{{-$1}}})dnl
+define({{{_add_}}},dnl
+{{{$1 + $2}}})dnl
+define({{{_sub_}}},dnl
+{{{$1 - $2}}})dnl
+define({{{_mul_}}},dnl
+{{{$1 \cdot $2}}})dnl
+define({{{_div_}}},dnl
+{{{$1 / $2}}})dnl
+define({{{_pow_}}},dnl
+{{{{$1}^{$2}}}})dnl
+define({{{_addmul_}}},dnl
+{{{_add_($1, _mul_($2, $3))}}})dnl
+define({{{_submul_}}},dnl
+{{{_sub_($1, _mul_($2, $3))}}})dnl
+define({{{_fmma_}}},dnl
+{{{_add_(_mul_($1, $2), _mul_($3, $4))}}})dnl
+define({{{_fmms_}}},dnl
+{{{_sub_(_mul_($1, $2), _mul_($3, $4))}}})dnl
+define({{{_lt_}}},dnl
+{{{$1 < $2}}})dnl
+define({{{_gt_}}},dnl
+{{{$1 > $2}}})dnl
+define({{{_eq_}}},dnl
+{{{$1 = $2}}})dnl
+dnl
+define({{{_boolzero_}}},dnl
+{{{`0`}}})dnl
+define({{{_boolpos_}}},dnl
+{{{`1`}}})dnl
+define({{{_boolneg}}},dnl
+{{{`-1`}}})dnl
+define({{{_zero_}}},dnl
+{{{`0`}}})dnl
+define({{{_one_}}},dnl
+{{{`1`}}})dnl
+dnl############################################################################
+dnl memory management
+dnl############################################################################
+define({{{desc_init_set}}},{{{
+    Initialises `$1` and sets it to `$2`.dnl
+}}})dnl
+dnl############################################################################
+dnl set
+dnl############################################################################
+define({{{desc_set}}},{{{
+    Sets `$1` to `$2`.dnl
+}}})dnl
+define({{{desc_zero}}},{{{
+    Sets `$1` to _zero_.dnl
+}}})dnl
+define({{{desc_one}}},{{{
+    Sets `$1` to _one_.dnl
+}}})dnl
+dnl############################################################################
+dnl negation, absolute value etc.
+dnl############################################################################
+define({{{desc_neg}}},{{{
+    Sets `$1` to `_neg_($2)`.dnl
+}}})dnl
+define({{{desc_abs}}},{{{
+    Sets `$1` to the absolute value of `$2`.dnl
+}}})dnl
+dnl############################################################################
+dnl basic arithmetic operations
+dnl############################################################################
+define({{{desc_add}}},{{{
+    Sets `$1` to `_add_($2, $3)`.dnl
+}}})dnl
+define({{{desc_sub}}},{{{
+    Sets `$1` to `_sub_($2, $3)`.dnl
+}}})dnl
+define({{{desc_mul}}},{{{
+    Sets `$1` to `_mul_($2, $3)`.dnl
+}}})dnl
+define({{{desc_divexact}}},{{{
+    Sets `$1` to `_div_($2, $3)` under the assumption that the division is
+    exact.  If `$3` is _zero_, an exception is raised.dnl
+}}})dnl
+dnl############################################################################
+dnl extended basic arithmetic operations
+dnl############################################################################
+define({{{desc_addmul}}},{{{
+    Sets `$1` to `_addmul_($1, $2, $3)`.dnl
+}}})dnl
+define({{{desc_submul}}},{{{
+    Sets `$1` to `_submul_($1, $2, $3)`.dnl
+}}})dnl
+define({{{desc_fmma}}},{{{
+    Sets `$1` to `_fmma_($2, $3, $4, $5)`.dnl
+}}})dnl
+define({{{desc_fmms}}},{{{
+    Sets `$1` to `_fmms_($2, $3, $4, $5)`.dnl
+}}})dnl
+dnl############################################################################
+dnl powering
+dnl############################################################################
+define({{{desc_pow}}},{{{
+    Sets `$1` to `_pow_($2, $3)`.  Defines `_eq_(_pow_(0, 0), 1)`.dnl
+}}})dnl
+dnl############################################################################
+dnl comparisons
+dnl############################################################################
+define({{{desc_cmp}}},{{{
+    Returns _boolneg_ if `_lt_($1, $2)`, _boolpos_ if `_gt_($1, $2)`, otherwise
+    returns zero.dnl
+}}})dnl
+define({{{desc_equal}}},{{{
+    Returns _boolpos_ if `_eq_($1, $2)`, otherwise returns _boolzero_.dnl
+}}})dnl
+define({{{desc_is_zero}}},{{{
+    Returns _boolpos_ if `_eq_($1, 0)`, otherwise returns _boolzero_.dnl
+}}})dnl
+define({{{desc_is_one}}},{{{
+    Returns _boolpos_ if `_eq_($1, 1)`, otherwise returns _boolzero_.dnl
+}}})dnl
+define({{{desc_sgn}}},{{{
+    Returns the sign of `$1`.  That is, returns `-1` if `_lt_($1, 0)`, `1` if
+    `_gt_($1, 0)` and `0` if `_eq_($1, 0)`.dnl
+}}})dnl
+dnl############################################################################
+dnl factoring
+dnl############################################################################
+define({{{desc_sqrt_nonordered_ring}}},{{{
+    If `$2` is a perfect square, sets `$1` to a square root of `$2`
+    and returns _boolpos_.  Otherwise returns _boolzero_.dnl
+}}})dnl
+define({{{desc_gcd_int}}},{{{
+    Sets `$1` to the greatest common divisor of `$2` and `$3`.  The result is
+    always non-negative.dnl
+}}})dnl
+define({{{desc_divisible}}},{{{
+    Returns _boolpos_ if there is an `x` such that `_eq_($1, _mul_(x, $2))`,
+    and returns _boolzero_ if there is none.dnl
+}}})dnl
+define({{{desc_divides}}},{{{
+    Returns _boolpos_ if there is an `x` such that `_eq_($2, _mul_(x, $3))` and
+    sets `_eq_($1, x)`, and returns _boolzero_ if there is none and sets
+    `_eq_($1, 0)`.dnl
+}}})dnl
diff --git a/doc/source/acb.rst → doc/origsrc/acb.rst b/doc/source/acb.rst → doc/origsrc/acb.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb:
 
 **acb.h** -- complex numbers

diff --git a/doc/source/acb_calc.rst → doc/origsrc/acb_calc.rst b/doc/source/acb_calc.rst → doc/origsrc/acb_calc.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-calc:
 
 **acb_calc.h** -- calculus with complex-valued functions

diff --git a/doc/source/acb_dft.rst → doc/origsrc/acb_dft.rst b/doc/source/acb_dft.rst → doc/origsrc/acb_dft.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-dft:
 
 **acb_dft.h** -- Discrete Fourier transform

diff --git a/doc/source/acb_dirichlet.rst → doc/origsrc/acb_dirichlet.rst b/doc/source/acb_dirichlet.rst → doc/origsrc/acb_dirichlet.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-dirichlet:
 
 **acb_dirichlet.h** -- Dirichlet L-functions, Riemann zeta and related functions

diff --git a/doc/source/acb_elliptic.rst → doc/origsrc/acb_elliptic.rst b/doc/source/acb_elliptic.rst → doc/origsrc/acb_elliptic.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-elliptic:
 
 **acb_elliptic.h** -- elliptic integrals and functions of complex variables

diff --git a/doc/source/acb_hypgeom.rst → doc/origsrc/acb_hypgeom.rst b/doc/source/acb_hypgeom.rst → doc/origsrc/acb_hypgeom.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-hypgeom:
 
 **acb_hypgeom.h** -- hypergeometric functions of complex variables

diff --git a/doc/source/acb_mat.rst → doc/origsrc/acb_mat.rst b/doc/source/acb_mat.rst → doc/origsrc/acb_mat.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-mat:
 
 **acb_mat.h** -- matrices over the complex numbers

diff --git a/doc/source/acb_modular.rst → doc/origsrc/acb_modular.rst b/doc/source/acb_modular.rst → doc/origsrc/acb_modular.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-modular:
 
 **acb_modular.h** -- modular forms of complex variables

diff --git a/doc/source/acb_poly.rst → doc/origsrc/acb_poly.rst b/doc/source/acb_poly.rst → doc/origsrc/acb_poly.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-poly:
 
 **acb_poly.h** -- polynomials over the complex numbers

diff --git a/doc/source/acb_theta.rst → doc/origsrc/acb_theta.rst b/doc/source/acb_theta.rst → doc/origsrc/acb_theta.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acb-theta:
 
 **acb_theta.h** -- Riemann theta functions

diff --git a/doc/source/acf.rst → doc/origsrc/acf.rst b/doc/source/acf.rst → doc/origsrc/acf.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _acf:
 
 **acf.h** -- complex floating-point numbers

diff --git a/doc/source/agm.rst → doc/origsrc/agm.rst b/doc/source/agm.rst → doc/origsrc/agm.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _algorithms_agm:
 
 Algorithms for the arithmetic-geometric mean

diff --git a/doc/source/aprcl.rst → doc/origsrc/aprcl.rst b/doc/source/aprcl.rst → doc/origsrc/aprcl.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _aprcl:
 
 **aprcl.h** -- APRCL primality testing

diff --git a/doc/source/arb.rst → doc/origsrc/arb.rst b/doc/source/arb.rst → doc/origsrc/arb.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb:
 
 **arb.h** -- real numbers

diff --git a/doc/source/arb_calc.rst → doc/origsrc/arb_calc.rst b/doc/source/arb_calc.rst → doc/origsrc/arb_calc.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb-calc:
 
 **arb_calc.h** -- calculus with real-valued functions

diff --git a/doc/source/arb_fmpz_poly.rst → doc/origsrc/arb_fmpz_poly.rst b/doc/source/arb_fmpz_poly.rst → doc/origsrc/arb_fmpz_poly.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb_fmpz_poly:
 
 **arb_fmpz_poly.h** -- extra methods for integer polynomials

diff --git a/doc/source/arb_fpwrap.rst → doc/origsrc/arb_fpwrap.rst b/doc/source/arb_fpwrap.rst → doc/origsrc/arb_fpwrap.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb_fpwrap:
 
 **arb_fpwrap.h** -- floating-point wrappers of Arb mathematical functions

diff --git a/doc/source/arb_hypgeom.rst → doc/origsrc/arb_hypgeom.rst b/doc/source/arb_hypgeom.rst → doc/origsrc/arb_hypgeom.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb-hypgeom:
 
 **arb_hypgeom.h** -- hypergeometric functions of real variables

diff --git a/doc/source/arb_mat.rst → doc/origsrc/arb_mat.rst b/doc/source/arb_mat.rst → doc/origsrc/arb_mat.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb-mat:
 
 **arb_mat.h** -- matrices over the real numbers

diff --git a/doc/source/arb_poly.rst → doc/origsrc/arb_poly.rst b/doc/source/arb_poly.rst → doc/origsrc/arb_poly.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arb-poly:
 
 **arb_poly.h** -- polynomials over the real numbers

diff --git a/doc/source/arf.rst → doc/origsrc/arf.rst b/doc/source/arf.rst → doc/origsrc/arf.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arf:
 
 **arf.h** -- arbitrary-precision floating-point numbers

diff --git a/doc/source/arith.rst → doc/origsrc/arith.rst b/doc/source/arith.rst → doc/origsrc/arith.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _arith:
 
 **arith.h** -- arithmetic and special functions

diff --git a/doc/source/bernoulli.rst → doc/origsrc/bernoulli.rst b/doc/source/bernoulli.rst → doc/origsrc/bernoulli.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _bernoulli:
 
 **bernoulli.h** -- support for Bernoulli numbers

diff --git a/doc/source/bool_mat.rst → doc/origsrc/bool_mat.rst b/doc/source/bool_mat.rst → doc/origsrc/bool_mat.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _bool-mat:
 
 **bool_mat.h** -- matrices over booleans

diff --git a/doc/source/bug_reporting.rst → doc/origsrc/bug_reporting.rst b/doc/source/bug_reporting.rst → doc/origsrc/bug_reporting.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _bug_reporting:
 
 **Bug reporting**

diff --git a/doc/source/building.rst → doc/origsrc/building.rst b/doc/source/building.rst → doc/origsrc/building.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _building:
 
 **Building, testing and installing**

diff --git a/doc/source/ca.rst → doc/origsrc/ca.rst b/doc/source/ca.rst → doc/origsrc/ca.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _ca:
 
 **ca.h** -- exact real and complex numbers

diff --git a/doc/source/ca_ext.rst → doc/origsrc/ca_ext.rst b/doc/source/ca_ext.rst → doc/origsrc/ca_ext.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _ca-ext:
 
 **ca_ext.h** -- real and complex extension numbers

diff --git a/doc/source/ca_field.rst → doc/origsrc/ca_field.rst b/doc/source/ca_field.rst → doc/origsrc/ca_field.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _ca-field:
 
 **ca_field.h** -- extension fields

diff --git a/doc/source/ca_mat.rst → doc/origsrc/ca_mat.rst b/doc/source/ca_mat.rst → doc/origsrc/ca_mat.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _ca-mat:
 
 **ca_mat.h** -- matrices over the real and complex numbers

diff --git a/doc/source/ca_poly.rst → doc/origsrc/ca_poly.rst b/doc/source/ca_poly.rst → doc/origsrc/ca_poly.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _ca-poly:
 
 **ca_poly.h** -- dense univariate polynomials over the real and complex numbers

diff --git a/doc/source/ca_vec.rst → doc/origsrc/ca_vec.rst b/doc/source/ca_vec.rst → doc/origsrc/ca_vec.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _ca-vec:
 
 **ca_vec.h** -- vectors of real and complex numbers

diff --git a/doc/source/calcium.rst → doc/origsrc/calcium.rst b/doc/source/calcium.rst → doc/origsrc/calcium.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _calcium:
 
 **calcium.h** -- global definitions

diff --git a/doc/source/constants.rst → doc/origsrc/constants.rst b/doc/source/constants.rst → doc/origsrc/constants.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _algorithms_constants:
 
 Algorithms for mathematical constants

diff --git a/doc/source/contributing.rst → doc/origsrc/contributing.rst b/doc/source/contributing.rst → doc/origsrc/contributing.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _contributing:
 
 **Contributing to FLINT**

diff --git a/doc/source/contributors.rst → doc/origsrc/contributors.rst b/doc/source/contributors.rst → doc/origsrc/contributors.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _contributors:
 
 **Contributors**

diff --git a/doc/source/d_mat.rst → doc/origsrc/d_mat.rst b/doc/source/d_mat.rst → doc/origsrc/d_mat.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _d-mat:
 
 **d_mat.h** -- double precision matrices

diff --git a/doc/source/d_vec.rst → doc/origsrc/d_vec.rst b/doc/source/d_vec.rst → doc/origsrc/d_vec.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _d-vec:
 
 **d_vec.h** -- double precision vectors

diff --git a/doc/source/dirichlet.rst → doc/origsrc/dirichlet.rst b/doc/source/dirichlet.rst → doc/origsrc/dirichlet.rst
@@ -1,3 +1,4 @@
+include(`macros.m4')dnl
 .. _dirichlet:
 
 **dirichlet.h** -- Dirichlet characters