dedoc Tutorial

To get started with _dedoc begin by cloning the repsitory:

$ git clone https://github.com/hlandau/dedoc

Dependencies. You will need to have the following tools available in your environment:

GNU Guile Scheme (guile(1)) (required);
GNU Make v4.4 or later (make(1)) (required) — note that this is very new and your distro may not have it yet;
xmllint(1) (strongly recommended and assumed);
xsltproc(1) (strongly recommended and assumed);
rnv(1) (strongly recommended and assumed);

Specific output methods may require additional tools:

xml(1), provided by XMLStartlet (for mdoc output and transforms dependent on it);
zip(1) (for EPUB support);
groff(1) (for groff-based transformations);
mandoc(1) (for mandoc-based transformations);
Python 3 with the packages lxml and html5_parser (for mandoc-based XHTML output).

On NixOS, you can get a shell with all the needed dependencies using the following command, though you will need to be using nixpkgs 23.05 or newer, or unstable:

$ nix-shell -p guile libxml2 libxslt rnv xmlstarlet zip groff \
    mandoc gnumake 'python3.withPackages(p: [p.lxml p.html5-parser])'

Basic usage. To compile a document using dedoc, run the bin/dedoc command while in the directory containing a dd-*.scm file; alternatively, run bin/dedoc -C <dir>, where <dir> is the directory containing the dd-*.scm file. Output will be produced in the build/ directory.

For example, create an empty directory tutorial-1 and place a file named dd-tutorial-1.scm in it:

(define-module (dd-tutorial-1))
(use-modules (dedoc))

(define-public (top)
  (doc
    (docctl (title "Tutorial 1"))
    (docbody
      (sec "Section Title"
        (p "This is a paragraph.")))))

(You can find more information on the DEDOC schema in the DEDOC schema specification.)

Now run $DEDOC/bin/dedoc from that directory, where $DEDOC is the path you cloned the dedoc repository to. The output will be produced in the build/ directory.

Note: By default, dedoc uses the dd-*.scm naming convention to automatically detect which file in a directory is the dedoc.scm file containing your document source. If you have multiple files of the form dd-*.scm in a directory, you will need to specify the correct file manually by customising the Makefile options (see below).

Shell shortcut. mk/dedoc-shell.sh is a file you can optionally source into your shell to setup an alias for the dedoc(1) command, sparing you from needing to type the full path to bin/dedoc every time:

$ cd some-document/
$ ls
dd-some-document.scm
$ . ~/path/to/dedoc-checkout/mk/dedoc-shell.sh
$ dedoc

Makefile customisation. The part of dedoc which actually transforms the output DEDOC XML file into useful output formats is known as the dedoc-methods collection. This is a Makefile-driven workflow in the UNIX tradition. The workflow has been organised in a highly modular way so that each possible output method has its own makefile in its own subdirectory of the $DEDOC/methods directory. This is then tied together with a master makefile in the $DEDOC/mk directory. In fact, invoking dedoc(1) is actually just a shorthand for invoking GNU Make with this master makefile.

You can customise the default settings of the various makefiles by creating a makefile named Makefile.config in the same directory as your dd-*.scm file. This is an optional file which, if present, GNU Make will source to allow you to override dedoc-methods's default settings.

The settings you can override include:

DOCNAME: By default, dedoc automatically determines the filename of your document by looking for a file named in the pattern dd-*.scm. If you have more than one file named this way, this is ambiguous; alternatively, you may not wish to name your source files this way. In this case, you can set this to the source file name explicitly.
BUILD_DIR: The output build directory. Defaults to build/
METHODS: The list of method names to use when creating output files. You can use this to disable some methods or to add your own methods. By default, a reasonable default set of supported methods is listed.

The path to each program needed for the operation of dedoc can generally be overridden also; see mk/support.mk for details.

Each method may also have its own settings you can override. See the file named method.mk in each method's directory in the dedoc source tree for details.

Makefile targets. The following make targets are available:

all: Build everything.
clean: Deletes the build output directory.
method_NAME_all: Builds all outputs defined by the method NAME.
build/DOCNAME.xhtml (for example): You can also instruct make to build a specific build output directly by naming the path of the file which would be produced.