Table of Contents

• Building
  • Requirements
  • Make
  • Meson
  • Cmake
  • setuptools
• Vendored Libraries
  • quickjs
• Build Artifacts
  • dndc
  • libdndc
  • dndc.wasm
  • pydndc
  • DndEdit
  • DndcEdit
  • PyDndEdit
  • dndc-tag
  • dndc-browse
  • dndbr
• Testing
• Type Checking
• Scripts
  • tag_and_syntax.py
  • cdoc.py
  • make_cdoc_index.py
  • win_utils.py
  • convert.py
• Docs

Dndc

See the overview, written in .dnd for a description of the file format. Or checkout the reference.

This is a compiler and associated tooling for the dnd document format. DND stands for David's New Document.

Building

This project builds with clang (including apple clang) or gcc. It should compile with MSVC.

Mingw is not supported. Or maybe it is, I haven't tried.

Requirements

You need a C compiler. It is known to work with gcc and clang. It should work with MSVC.

You need make, meson or cmake to build the code. Or if you really want you can read the makefiles and type the build command by hand.

The python extension requires python and supports python3.6+.

Qt-based editor requires Qt 5 or 6 and a C++ compiler.

Make

Building with the Makefile requires gnu make. The first time you invoke make, it will create a makefile called opt.mak. opt.mak allows you to configure things like debug vs release build, the right compile flags for the python extension if on windows and whether to build the qt-based gui editor.

You can invoke make opt.mak yourself to not use the default options before the first build.

To compile everything + tests, do make all.

To compile and run the tests, do make tests.

To compile the documentation, do make docs and for C docs do make cdocs.

You can list the make targets with make list.

Meson

You can also compile everything using meson. Meson currently doesn't build the docs or dndc.wasm.

Cmake

Cmake is also supported. Cmake currently doesn't build the docs or dndc.wasm.

setuptools

If you just want the python extension, you can build using the setup.py script. Builds with gcc, clang or clang-cl.

Vendored Libraries

quickjs

The dnd document format allows for in-document scripting to manipulate the document's ast using javascript. To support this, we include a vendored copy of quickjs, with some small modifications.

It is a future project to see if we can use system javascript engines instead to reduce the filesize footprint of dndc. For example, javascript core on macos.

Build Artifacts

dndc

The command-line, batch program that can compile dnd files into html, md or to dnd. It can also be used to format the dnd file to a standard width.

libdndc

Both static and dynamic versions are supported. libquickjs is also built and is required for linking. You can either transforms strings in a batch mode, similar to the interface of dndc, or you can use the slightly more low-level ast api to manipulate a dnd document.

dndc.wasm

A stripped down version of libdndc is available as a wasm target. Some of the output formats are not available and in-document scripting with quickjs is not enabled.

Compiling to wasm requires compiler support. Apple clang does not support this, but other versions of clang do.

pydndc

libdndc, but as a python extension. Exposes a pythonic api to libdndc. This will embed quickjs in the python extension.

DndEdit

Mac only. A rich gui editor for dnd files, showing the resulting document in a webview. Built with appkit.

This does not produce an app bundle. It creates a self-contained executable with an embedded Info.plist and app icon. Patches to create an actual app bundle instead are welcome.

DndcEdit

Qt 5 or 6 required. Also a rich gui editor for dnd files, like DndEdit. This is built with Qt instead.

PyDndEdit

A python version of DndcEdit, using pydndc and PySide6's bindings to Qt.

dndc-tag

A command-line utility that will create tags from a list of files or the current directory. These tags are formatted so vim and similar editors can use them to jump around.

dndc-browse

A command-line utility that will start a local webserver that will serve dnd files in the current directory as html. All documents are compiled upon request, so you can edit documents and then immediately see the new document in your browser.

dndbr

Mac Only. This is similar to dndc-browse, but is a gui app instead of a command-line utility.

Similar to DndEdit, this does not produce an app bundle.

Testing

Tests are C programs that can be compiled and run individually. If you are building with make, make tests will build and run all the tests. If using meson, you can do meson test -C or do ninja test from the build directory. With Cmake, be aware that ninja test does not build the tests, it only runs them. Cmake just being Cmake I guess.

Once the tests are compiled, you can run them individually if you want. Run the binary with -h to see a list of options. You can even run only a subset of tests within each binary.

Some tests need their working directory to be the project root as they read the examples or the testcases, etc. Each test has a -C argument to set the current directory.

There is also a python test for the python extension, at Dndc/testpydndc.py. That one needs to know where the compiled python extension is and has an argument for that.

Type Checking

The python code should all type check with mypy. If it doesn't then that is a bug.

Scripts

There are some useful scripts in the Scripts folder for development.

tag_and_syntax.py

This script requires libclang and might only work on my machines. If it does work, it will produce a tags file for vim and also a .vimrc file that will setup semantic highlighting in vim.

This is invoked by make tags.

cdoc.py

This script also requires libclang. It converts C headers into a syntax/semantic highlighted hyperlinked html page.

This and make_cdoc_index.py are invoked by make cdocs.

make_cdoc_index.py

This script will add an index.html to all the folders generated by cdoc.py.

win_utils.py

On windows the basic cli commands are different and weird. To make up for this, this script implements some really basic ones. It implements rm, mkdir, mv, cp, and install.

convert.py

This script can be run in two modes. In either mode, it will recursively find all interesting files if no files are given as an argument. If --strip_only is passed, then it will strip trailing whitespace from all of the files. If not, then it will do some regex replacements in all of the files. This should probably take those as an argument, but it doesn't, you have to edit the script.

This can be invoked by make strip or make convert.

Docs

Using the makefile, you can generate a dash/zeal docset. Simply do make` docset.

Additionally, make docs will generate some html files in the RenderedDocs folder which you can browse.