bug#70640: A Texinfo aware `,describe` command.

Yuval Langer <[email protected]> Mon, 29 Apr 2024 06:47:50 +0300

Newsgroups	gmane.lisp.guile.bugs
Message-ID	<CAK0OjG2m66FE-mLNA-Jua0-1ncia7vdKUF9TtoJ+c0E9-poO_g@mail.gmail.com>

Hello hackers,

I have noticed there are many docstrings containing Texinfo markup,
but when one runs the `,describe` command, one gets the Texinfo markup
source, not a render of those Texinfo commands.

I wish to write a better `,describe` command that would render Texinfo
in a pleasant way.  Attached are some procedures I wrote for this
purpose.  They are far from being complete, but I wish to start a
conversion about the topic.

I searched for the describe command in the guile source code and found:

https://git.savannah.gnu.org/cgit/guile.git/tree/module/system/repl/command.scm#n346

Is that the right place?

Also, the code of these files is currently stored in:

https://codeberg.org/kakafarm/guile-fancy-describe/

Also also, previous message related to this:

https://lists.gnu.org/archive/html/guile-devel/2024-04/msg00015.html

fancy-docstrings.scm (text/x-scheme, 1.7 KB)

(define-module (fancy-docstrings)
  #:use-module (srfi srfi-1)
  #:use-module (texinfo)
  #:use-module (ice-9 documentation)
  #:use-module (ice-9 match)
  #:use-module (ice-9 pretty-print))

(define ansi-begin-bold "\x1b[1m")
(define ansi-begin-underline "\x1b[4m")
(define ansi-end-it-all "\x1b[0m")

;;;(pretty-print texi-command-specs)

(define (display-fancy-string str)
  "Display a fancy @var{str}."
  (display ansi-begin-underline)
  (display ansi-begin-bold)
  (display str)
  (display ansi-end-it-all))

(define (display-fancy-stexi-para stexi)
  "Display fancy @var{stexi} paragraph."
  (let loop ((stexi stexi))
    (match stexi
      (() '())
      ((('var (and (? string?) str)) . rest-of-elements)
       (display-fancy-string str)
       (loop rest-of-elements))
      ((('code (and (? string?) str)) . rest-of-elements)
       (display-fancy-string str)
       (loop rest-of-elements))
      (((some-tag (and (? string?) str)) . rest-of-items)
       ;; TODO: What about the rest of them?
       (error "Still unsupported stexi element:" some-tag str)
       (loop rest-of-items))
      (((and (? string?) str) . rest-of-items)
       (display str)
       (loop rest-of-items))
      (_
       (error "Unknown stexi value:" stexi)))))

(define (display-fancy-stexi-fragment stexi)
  (let loop ((stexi stexi))
    (match stexi
      (() '())
      (('*fragment* ('para . first-paragraph) . rest-of-paragraphs)
       (display-fancy-stexi-para first-paragraph)
       (loop rest-of-paragraphs))
      ((('para . paragraph) . rest-of-paragraphs)
       (display "\n\n")
       (display-fancy-stexi-para paragraph)
       (loop rest-of-paragraphs))
      ((element . rest-of-elements)
       (error "Unknown stexi element" element)))))

mucking-about.scm (text/x-scheme, 635 B)

(use-module (fancy-describe))

(define find-stexi (texi-fragment->stexi (object-documentation find)))

(pretty-print find-stexi)

(display-fancy-stexi-fragment find-stexi) (newline)

(display-fancy-stexi-fragment (texi-fragment->stexi "poop")) (newline)

(let* ((text "aaaaa @var{aaaaa} bbbbb.

ccccc @var{moo} ddddd.


@var{@@moo}


eeeee @code{gah} fffff.
")
       (stexi (texi-fragment->stexi text)))
  (pretty-print stexi)
  (display-fancy-stexi-fragment stexi))

(newline)

(let* ((text "@var{moo}
@code{gah}
")
       (stexi (texi-fragment->stexi text)))
  (pretty-print stexi)
  (display-fancy-stexi-fragment stexi))
(newline)