Ruff!

# IntroductionTop, Main, Index

Ruff! (Runtime function formatter) is a documentation generation system for programs written in the Tcl programming language. Ruff! uses runtime introspection in conjunction with comment analysis to generate reference manuals for Tcl programs.

Ruff! is covered by a liberal BSD open-source license that permits use for any purpose.

## Why Ruff!Top, Main, Index

In comparison with other source code based documentation generators, Ruff! produces documentation that not only requires less duplication of effort from the programmer, but is also more complete, more accurate and more maintainable.

- Comments in source code do not have to be reproduced for documentation purposes.
- Ruff! requires minimal markup in the comments making it lightweight as well as reducing clutter.
- Supports inline formatting using Markdown syntax.
- Diagrams can be embedded using multiple formats.
- Program elements like command arguments, defaults and class relationships like inheritance are automatically derived.
- Maintenance is less of a burden as documentation is automatically updated when source is modified.

On the output side,

- Ruff! supports output formats HTML, Markdown, Nroff, Asciidoctor and reStructuredText.
- Documentation can be in single-page or multi-page formats.
- Hyperlinks between program elements, and optionally source code, make navigation easy and efficient.
- A table of contents and optional searchable index permits quick location of command and class documentation.
- Class relationships are extracted and the full API for a class, with inherited and mixed-in methods, is flattened and summarized.
- The HTML formatter includes multiple themes switchable by the end-user.
- Output targets like Sphinx and Asciidoctor allow Ruff! generated documentation to be integrated with that for other languages or to produce additional formats like PDF.

The Ruff! documentation itself is produced with Ruff!. Examples of other packages documented with Ruff!'s HTML output include iocp, cffi, CAWT, PAWT, apave, baltip, hl-tcl, promise, obex, Woof! and tcl-vix.

For examples of Sphinx-integrated documentation, see SpiceGenTcl or OSVVM.

Ruff!'s PDF documentation is an example of PDF output using Asciidoctor.

## DocumentationTop, Main, Index

The ::ruff reference page describes the Ruff! documentation generation API. The ::ruff::sample page shows some sample output for some of the Ruff! features along with the associated source code from which it was generated.

## DownloadsTop, Main, Index

Download the Ruff! distribution from https://sourceforge.net/projects/magicsplat/files/ruff/. The source code repository is at https://github.com/apnadkarni/ruff.

## InstallationTop, Main, Index

To install, extract the distribution to a directory listed in your Tcl `auto_path` variable.

## CreditsTop, Main, Index

Ruff! is authored by Ashok P. Nadkarni with contributions from George Yashin and Nicolas Robert.

It uses the `textutil` package from tcllib, a modified version of the Markdown inline parser from the Caius project, and portions of the `nroff` generator from Tcllib's `doctools` package.