From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from minnie.tuhs.org (minnie.tuhs.org [45.79.103.53]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 75479d98 for ; Tue, 18 Feb 2020 11:23:30 +0000 (UTC) Received: by minnie.tuhs.org (Postfix, from userid 112) id 6B54A9D528; Tue, 18 Feb 2020 21:23:29 +1000 (AEST) Received: from minnie.tuhs.org (localhost [127.0.0.1]) by minnie.tuhs.org (Postfix) with ESMTP id D01679D51A; Tue, 18 Feb 2020 21:22:32 +1000 (AEST) Received: by minnie.tuhs.org (Postfix, from userid 112) id 68A839D51A; Tue, 18 Feb 2020 21:22:29 +1000 (AEST) Received: from cfcl.com (cpepool4cmts2-144.sanbrunocable.com [24.143.248.144]) by minnie.tuhs.org (Postfix) with ESMTP id 16DA29D518 for ; Tue, 18 Feb 2020 21:22:29 +1000 (AEST) Received: from spot.local (spot.local [IPv6:fe80::cb8:77d2:18e:cd21]) by cfcl.com (Postfix) with ESMTP id 6B5C79ADD36 for ; Tue, 18 Feb 2020 03:22:28 -0800 (PST) From: Rich Morin Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Mime-Version: 1.0 (Mac OS X Mail 13.0 \(3608.40.2.2.4\)) Date: Tue, 18 Feb 2020 03:22:25 -0800 References: <202002171520.01HFKqKi026749@tahoe.cs.Dartmouth.EDU> <4d252035b323b7583c5760c952d1982c@firemail.de> <202002171839.01HId8FT1358073@darkstar.fourwinds.com> <202002180017.01I0HI0I1415945@darkstar.fourwinds.com> To: The Unix Heritage Society mailing list In-Reply-To: Message-Id: X-Mailer: Apple Mail (2.3608.40.2.2.4) Subject: Re: [TUHS] man Macro Package and pdfmark X-BeenThere: tuhs@minnie.tuhs.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: The Unix Heritage Society mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: tuhs-bounces@minnie.tuhs.org Sender: "TUHS" 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