Re: graphical manuals

[T. Kurt Bond]

The pikchr program was inspired by pic, and is somewhat compatible, and can
output SVG.

https://pikchr.org/home/doc/trunk/homepage.md
https://pikchr.org/home/doc/trunk/doc/differences.md

I have not used it, but it might be useful.

Niklaus Wirth used railroad diagrams in the Pascal User Manual and Report,
and I always found them very helpful, easily understood by those unfamiliar
with the various BNF variants, especially for complicated languages, so
using it to describe COBOL makes perfect sense.

I have often wished for some easy way to produce them, and a preprocessor
for good would be wonderful.

I’ve also wished for some way to browse PDF versions of the man pages as
easily as the text ones, but taking advantage of PDF links somehow to bring
up other PDF man pages and other PDF documents, but I think that would take
a specialized viewer…

Having all of the man pages for a system in one bid PDF works to start
with, but what do you do when you add a new package with new man pages?  If
the viewer understood where to find PDF versions of man pages, and could
interpret links in the PDF to other man pages, perhaps it could be mad to
work?

On Sat, Jul 15, 2023 at 14:31 James K. Lowden <jklowden@schemamania.org>
wrote:

> I have a public groff demonstration project.  Its purpose is to show
> the world what groff + mandoc can produce in terms of technical
> documentation, and to show ourselves what it cannot do.  I'd like to
> ask first for suggestions on how to bring it up to the state of the
> art.  Then see what we can do to improve on that.
>
> http://www.schemamania.org/groff/gcobol-demo/
>
> https://gitlab.cobolworx.com/COBOLworx/gcc-cobol/-/tree/master+cobol/gcc/cobol/man
>
> As I'm sure no one on this is aware, I'm part of a project to add COBOL
> to gcc.  Like any self-respecting compiler, ours needs a reference
> manual.  And, like any self-respecting troff fan, I want to use groff
> and, because HTML, mandoc.
>
> But I really can't.  Not yet, not for what I want and what the project
> demands. Mostly because we want "railroad diagrams", but tables, too.
>
> Perhaps IBM's best known and most verbose programming languages are SQL
> and COBOL. Our COBOL parser at present recognizes 1593 grammar rules
> using 649 language tokens. These appear mostly in 41 statements,
> verbs such as DISPLAY and READ.  Each statement can be quite long,
> consisting of a dozen or more words.
>
> The files linked above illustrate a relatively simple verb, START.  In
> the PDF, you can see my version.  For a non-railroad comparison, see
> the texinfo output (which I also contributed to) at
> https://gnucobol.sourceforge.io/HTML/gnucobpg.html#START.
>
> For another point of comparison, consider the SQL DELETE statement:
>
>         https://sqlite.org/lang_delete.html
> vs      https://www.postgresql.org/docs/current/sql-delete.html
>
> I suspect railroad diagrams might be sniffed at by many (like me, once)
> who like how their manpages look.  Don't we have typographical
> conventions to distinguish keywords and literals and arguments, and
> optionality?  We do.  But I posit that those conventions break down in
> the large: as the number of terms grow, it becomes more difficult to
> follow, and the amount visual noise, excuse me, "notation convention"
> grows.
>
> For proof, I offer that railroad diagrams are popular with users.
> SQLite and IBM both use them.  I would venture that the less one knows
> about BNF, the more attractive they are.
>
> I suggest they're not more widely used because tools are lacking, which
> in turn is because there is a widespread mistaken belief documentation
> should be automatically generated and, when that's insufficient, Use
> the Source, Luke.  And because folks who contribute to open source
> projects tend to have BNF in their quiver.
>
> On the pattern of dformat, I'd like eventually to design a macro
> language to generate these diagrams.  That processor's inputs could be
> generated from yacc outputs, plus some ancillary placement and style
> information.  As a baseline, I'm using pic.  That at least shows what
> can be done.  Which, I hope you agree, is not enough.
>
> There are two classes of problems with output currently: those that can
> be remedied with better use of existing tools, and those that cannot.
>
> Things that could be done better:
>
> 1.  PDF TOC, especially  using Deri's new work.
> 2.  PDF hyperlinks within pic, so that common terms can be cross
> referenced, and so the user can jump to the term's definition.
> 3.  Extract the diagram as a graphic artifact, and reference it in the
> HTML.  Use some kind of conditional logic to tell groff to link to the
> artifact if it's rendering HTML.
> 4.  Make the boxes in the #3 artifact "clickable", so they include a
> URL.
> 5.  Wrap the graphic in some kind of CSS to make them expand/collapse.
> Not a PDF option at this time, like the VAX atomic clock.
>
> I don't know the best way to do those things.  If you'd like to suggest
> command-line options, that's why I'm asking.  I haven't tried Deri's
> branch or the convenience macros he described recently.  Until I read
> about them, I had planned to use pdfmark directly.
>
> Things that can't be done:
>
> 1.  Render diagrams as SVG.  I think that would be optimal.
>
> 2.  Useful results from
>
>     $ groff -T utf8  -mandoc -pet ./gcobol-start.3c
>
> Actually, I'm not sure there's any better way inside a character-cell
> terminal to render the diagram than by reverting to standard manpage
> notation, with braces and brackets and boldface.  To do that would
> require something like my nonexistent macro language, because pic lacks
> the necessary semantic information. Please tell me if you have a better
> idea.
>
> 3.  In the PDF, and HTML, to render a "right mouse click" menu on
> linked items.  Just clicking on the link takes to you the target.
> Right-clicking presents a menu of cross-referenced items, other
> references to the same term.  That way, for, say, a "FILE", you could
> jump to the rules for how it is used in this context, or to its global
> definition, or to how it's used in other contexts, say by "WRITE".
>
> 4.  As far as I know, there is no tool for producing a TOC or an index
> for a set of HTML pages.
>
> I haven't mentioned tables in HTML only because I haven't gotten that
> far yet. Last I checked, grohtml gave terrible tables from tbl. Again,
> if there's good news on that front, I'd be happy to hear.
>
> Thank you for your kind consideration.  I would be glad to try new
> constructs and demonstrate outputs from other commands using different
> options.  I would like to get first to a place where the HTML is
> comparable to the PDF, and as good as the SQLite diagrams.
>
> --jkl
>
> --
T. Kurt Bond, tkurtbond@gmail.com, https://tkurtbond.github.io