Re: graphical manuals

[James K. Lowden]

On Fri, 21 Jul 2023 22:33:09 -0500
Nate Bargmann <n0nb@n0nb.us> wrote:

> Looking at the railroad diagram, I wonder if there are enough drawing
> characters in UTF-8 that they could be used for the diagrams rather
> than generating image files that would likely not be useful for
> terminal output.  

Thanks for reminding me, Nate.  Here's a current result: 

$ groff -T utf8  -mandoc -pet ./gcobol-start.3c
GCOBOL-START(3c)                   GCC COBOL
GCOBOL-START(3c)

NAME
     START  position file for reading

SYNOPSIS
           ????????    ?????????
      ??????START??????filename?????????????????????????
           ????????
     ???????FIRST???????????????????????????????????????
      ????????????????????????????????????????????
      ?    ??LAST??         ?????????    ?????????
      ?????? KEY  ???????????compare?????? name ??
            ??????????????? operator?     ???????
                   ?? IS   ??
                     ???????
     ???????????????????????????????????????????????????
       ?    ??????? ?LENGTH????expr???
       ??????WITH  ??
            ????????

     ???????????????????????????????????????????????????
       ???????????????????????????????????
            INVALID????????error-statements
                    ?  KEY  ?
                     ????????
     ????????????????????????????????????????????????????????
       ?????? NOT  ?????????????????????????????????????
            INVALID????????valid-statements?END-START??
                    ?  KEY  ?
                     ????????

 I haven't tried to understand exactly what's going on with that.  pic
is emitting troff input, and troff, I expect, is emitting drawing
instructions in ditroff, which grotty renders.  Something is evidently
lost in translation.  

The grotty manual mentions, under BUGS: 

        "There is no support for \D commands other than horizontal and
         vertical lines."

Given that constraint, a useful rendering might be possible if the pic
input took care to align the boxes and lines consistent with grotty's
character matrix.  

But, how?  An xterm determines its own font; it doesn't not
respond to in-band font requests. And there is no way afaik for a troff
drawing instruction to say "line right 7 characters; line down 3
lines", using whatever sizes the terminal decided on.  

That leaves us standing before my favorite hobbyhorse.  The demise of
Display Postscript doomed the possibility of a Unix graphical
terminal.  We had X, so applications could draw, but nothing like
"printing to the screen", where a data stream could control a graphical
terminal akin to how a data stream controls a graphical printer.
Instead, we got HTML, and thence epub.  

What would you use your MacArthur grant for?  I know what I would do: I
would create VT-roff, an xterm that, instead of recognizing VT-100
control codes, would recognize ditroff(5) output.  Then we could have
manpages "in the terminal" as good as on paper, or a PDF.  

--jkl