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

[Yuval Langer <yuval.langer@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 844 bytes --]

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

[-- Attachment #2: fancy-docstrings.scm --]
[-- Type: text/x-scheme, Size: 1749 bytes --]

(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)))))

[-- Attachment #3: mucking-about.scm --]
[-- Type: text/x-scheme, Size: 635 bytes --]

(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)