--- a/doc/doxyhtml/Doxyfile.in	Wed Nov 01 14:05:56 2017 -0700
+++ b/doc/doxyhtml/Doxyfile.in	Fri Nov 03 15:44:02 2017 +0100
@@ -374,12 +374,13 @@
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @abs_top_srcdir@/README.md \
-                         @abs_top_srcdir@/etc/HACKING.md \
-                         @abs_top_srcdir@/src/ \
+INPUT                  = @abs_top_srcdir@/src/ \
                          @abs_top_srcdir@/liboctave/ \
                          @abs_top_srcdir@/libinterp \
-                         @abs_top_srcdir@/libgui
+                         @abs_top_srcdir@/libgui \
+                         @abs_top_srcdir@/etc/HACKING.md \
+                         @abs_top_srcdir@/doc/doxyhtml/pages \
+                         @abs_top_builddir@/doc/doxyhtml/pages
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

--- a/doc/doxyhtml/module.mk	Wed Nov 01 14:05:56 2017 -0700
+++ b/doc/doxyhtml/module.mk	Fri Nov 03 15:44:02 2017 +0100
@@ -1,11 +1,22 @@
-doxyhtml: %reldir%/Doxyfile | %reldir%/$(octave_dirstamp)
+# Generate README.md from README and replace first line by a Doxygen
+# specific one.
+%reldir%/pages/README.md: $(srcdir)/README
+	$(MKDIR_P) $(@D)
+	cat $< | $(SED) '1s/.*/notitle {#mainpage}/; 2s/.*/=======/' > $@
+
+DOXYGEN_PAGES = \
+  %reldir%/pages/macros.dox \
+  %reldir%/pages/README.md
+
+doxyhtml: %reldir%/Doxyfile $(DOXYGEN_PAGES) | %reldir%/$(octave_dirstamp)
 	doxygen %reldir%/Doxyfile
 
 doxyhtml-maintainer-clean:
 	rm -f doc/doxygen_sqlite3.db
-	rm -rf `ls -d %reldir%/* 2>/dev/null | $(GREP) -v 'Doxyfile\.in\|README'`
+	rm -rf `ls -d %reldir%/* 2>/dev/null | $(GREP) -v 'Doxyfile\.in\|README\|pages$'`
 
 doc_EXTRA_DIST += \
+  $(DOXYGEN_PAGES) \
   %reldir%/Doxyfile.in \
   %reldir%/README
 

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxyhtml/pages/macros.dox	Fri Nov 03 15:44:02 2017 +0100
@@ -0,0 +1,106 @@
+/** @page Macros Important Macros
+
+@tableofcontents
+
+Builtin function and method definition   {#macros_defun}
+======================================
+
+In Octave a function is called from the interpreter by for example
+
+    [a, b, c] = foo (d, e);
+
+If `foo` should be defined as **builtin function**, it has to have the type
+`octave_builtin::fcn` or equivalently:
+
+```{.cc}
+octave_value_list
+Ffoo (const octave_value_list& args_name, int nargout_name)
+```
+
+> Notice the **F** prefix of `foo`!
+
+Basically, an `octave_value_list` goes in (referenced within that function by
+`args_name`) and another `octave_value_list` comes out.  The integer
+`nargout_name` indicates, how many outputs arguments the caller of this
+functions expects.
+
+Thus in the example above, `d` and `e` are available via `args_name` and
+`nargout_name` takes the value `3`, because three output arguments `a`, `b`,
+and `c` are expected.
+
+Very similar to builtin functions are **builtin methods**.  Builtin methods
+have to have the type `octave_builtin::meth` or equivalently:
+
+```{.cc}
+octave_value_list
+Ffoo (octave::interpreter& interp_name,
+      const octave_value_list& args_name, int nargout_name)
+```
+
+Notice again the `F` prefix of `foo`.
+
+> The difference between builtin functions and builtin methods is, that builtin
+> methods have access to the `octave::interpreter`, which is referenced by
+> `interp_name`.
+
+To make a builtin function or builtin method available to the interpreter, it
+is not sufficient to just define them somewhere inside `libinterp`.  Octave
+provides two convenience macros, to define them properly:
+
+```{.cc}
+DEFUN     (foo,              args_name, nargout_name, doc)
+DEFMETHOD (foo, interp_name, args_name, nargout_name, doc)
+```
+
+> For a usage example, see the definition of `#Feig`.
+
+The last argument of both macros `doc` will not appear in the builtin function
+or builtin method definition but is further processed.  The idea is, that code
+and documentation should be at one place.
+
+The macros #DEFUN or #DEFMETHOD fulfill two tasks:
+
+1. Proper builtin function or builtin method definition.
+2. Defining a fixed pattern for further processing by
+   - `mk-builtins.pl` (installation on `octave::symbol_table`)
+   - `mk-doc.pl` (docstring `doc` extraction for the help system)
+
+In addition to #DEFUN and #DEFMETHOD, there are two specialized versions of
+both macros, that should only be used with reason:
+
+1. If the name `foo` cannot be used directly (for example if it is already
+   defined as a macro), one can use instead one of
+   ```{.cc}
+   DEFUNX     ("foo", Ffoo,              args_name, nargout_name, doc)
+   DEFMETHODX ("foo", Ffoo, interp_name, args_name, nargout_name, doc)
+   ```
+   where `"foo"` is the name for the interpreter, protected by macro expansion
+   inside a string, and `Ffoo` is the actual builtin function or builtin method
+   name.
+2. In case `foo` may not be hidden by a variable, defined in an Octave
+   interpreter session, one can use instead one of
+   ```{.cc}
+   DEFCONSTFUN    (foo,              args_name, nargout_name, doc)
+   DEFCONSTMETHOD (foo, interp_name, args_name, nargout_name, doc)
+   ```
+
+Last but not least, there is #DEFALIAS.  As the name suggests, this macro can
+be used to define an alias for an existing builtin function.
+
+Dynamic builtin function and method definition  {#macros_defun_dld}
+==============================================
+
+When making use of the [OCT-file interface][OCT], it is desired to define
+functions or methods, than can be loaded dynamically at run time, e.g. those
+are not loaded at Octave startup.
+
+[OCT]: https://www.gnu.org/software/octave/doc/interpreter/Oct_002dFiles.html
+
+To achieve this, analog to #DEFUN and #DEFMETHOD, there are:
+
+```{.cc}
+DEFUN_DLD     (name,              args_name, nargout_name, doc)
+DEFMETHOD_DLD (name, interp_name, args_name, nargout_name, doc)
+```
+
+**/

--- a/etc/HACKING.md	Wed Nov 01 14:05:56 2017 -0700
+++ b/etc/HACKING.md	Fri Nov 03 15:44:02 2017 +0100
@@ -1,4 +1,4 @@
-Hacking Octave
+Hacking Octave  {#Hacking}
 ==============
 
 This file attempts to describe the rules to use when hacking the