Hi Damian, At 2026-02-19T15:52:36+1100, Damian McGuckin wrote: > I am documenting some work on programming some simple algorithms for > some very Elementary Mathematical functions, the C routine cproj(),
I suggest that anything to do with the Riemann Sphere is not elementary,
but beyond undergraduates in most disciplines. ;-)
Have I gotten so old that I don't hear tell of preteens bullying each
other via social media for insufficient mastery of Lebesgue integration?
> scalbn(), nextup() and nextdown(). There is some maths involved. It is
> an internal technical report but it will be available on ARXIV.org.
Cool!
> I then have to create what is basically a summary of that paper that
> can go onto a web site as documentation. It will be RST - ick!
Yikes!
> Has anybody done something similar and can offer some advice?
I have not done a similar task but, presumptuously, I'll offer some
advice anyway.
It sounds like you get to use the full power of mm for the paper proper,
but the summary itself needs conversion to RST.
I assume that the summary is being separately hand-composed.
I further assume that, for whatever reason, you don't want to bite a
bullet for as long as it takes to get comfortable enough with RST to
complete this task.
If those are correct, then what I would do is write a bastardized
variant MM package that:
1. Implements only as much of the MM macro interface as you need for
this specific document;
2. works only in nroff mode; and
3. formats the ASCII-spelled elements of RST that the recipients expect
instead of bothering with the usual typesetting concerns that *roff
macro packages have (beyond breaking lines and putting a 1v space on
the output).
Here's a sketch.
---snip---
$ cat ATTIC/example.mmrst
.H 1 Overview
We are proud to introduce our prototype of a Ramjet Encabulator.
Foo bar baz qux.
.H 2 Background
Lorem ipsum quodlibet.
$ nroff -M ATTIC -m mmrst ATTIC/example.mmrst | cat -s
Overview
========
We are proud to introduce our prototype of a Ramjet Encabulator.
Foo bar baz qux.
Background
−−−−−−−−−−
Lorem ipsum quodlibet.
---end snip---
Also see attachment. I apologize if it's too superficial to be of use.
> I find a lot of RST documents really painful to read because they are
> poorly structured and often ramble.
I find this to be generally true (with honorable exceptions) of software
documentation undertaken by people who regard the avoidance of tools
(like *roff or TeX[1]) for structured document composition as a positive
good. It is a common trait of self-regarded rock star programmers that
no discipline other than their own demands expertise or craft.
Regards,
Branden
[1] Or, as I understand it, the expensive, proprietary, and now dead
FrameMaker, which I never encountered in the flesh.
.\" mutant form of memorandum macros producing reStructured text (RST)
.if t \{\
.tm \n[.F]: RST is a plain text document format; go away
.ab
.\}
.
.ad l \" RST is strictly left-adjusted.
.
.de P
.\" \\$1 ignored
.sp
..
.
.de H
.\" \\$3 ignored
.ds decorator!1 =\"
.ds decorator!2 \-\"
.ds decorator!3 \[ga]\"
.ds decorator!4 \[aq]\"
.ds decorator!5 .\"
.ds decorator!6 \[ti]\"
.ds decorator!7 *\"
.nr level \\$1
.ds text \\$2\"
.sp
.nop \\*[text]
.br
.nop \l'\w"\\*[text]"u\&\\*[decorator!\\n[level]]'
.P
..
signature.asc
Description: PGP signature
