[TUHS] man Macro Package and pdfmark

[Rich Morin]

Ahem.  Back in the 80's, I used both nroff and troff a fair amount.
For example, Vicki Brown and I used nroff, in combination with an
IBM I/O Selectric (Datel 30) to print most of her master's thesis.
I also used troff to typeset several books for Prime Time Freeware.
Mostly, I used pre-existing macro packages, but sometimes I had to
dive down to the bare metal.  It all worked, and was quite flexible,
but I really don't miss it for adding docs to software projects.

Lately, I've been using the built-in documentation tools for Elixir,
a functional programming language based on the Erlang VM and a lot
of Ruby syntax.  I'm pleased to say that it's really quite pleasant.

I create multi-line "attributes" using macros such as @doc.  These
are encoded using Markdown, which isn't perfect but seems adequate.
The results are converted into both HTML pages and interactive help
text, with automagical indexing.

I'm able to create "doctests" by embedding IEx (Interactive Elixir)
examples, eg:

    iex> 2 + 2
    4

These get tested automagically, providing a modicum of reliability
to the documentation.  Amusingly, I did something similar years ago,
extracting C code from the SYNOPSIS sections of Apple's man pages.
This let me find and report a few docubugs...

-r