bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Drew Adams]

See https://stackoverflow.com/q/72547221/729907.

Users see this #f(...) syntax.  They should be able to consult the doc
in some way to find out what it is/means.  Please consider documenting
it in the Elisp manual.  Thx.

In GNU Emacs 28.1 (build 2, x86_64-w64-mingw32)
 of 2022-04-21 built on AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19044
System Description: Microsoft Windows 10 Pro (v10.0.2009.19044.1706)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND THREADS TIFF TOOLKIT_SCROLL_BARS
XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> See https://stackoverflow.com/q/72547221/729907.
>
> Users see this #f(...) syntax.  They should be able to consult the doc
> in some way to find out what it is/means.  Please consider documenting
> it in the Elisp manual.  Thx.

From the URL:

The syntax in question is in the following expression

((remote . emacs)
 (system . #f(compiled-function
          (file path)
          #<bytecode -0x47e8150df949387>))
 (t . #f(compiled-function
     (file path)
     #<bytecode -0x47e8150df949387>)))

It's from:

(cl-defmethod cl-print-object ((object compiled-function) stream)
  (unless stream (setq stream standard-output))
  ;; We use "#f(...)" rather than "#<...>" so that pp.el gives better results.
  (princ "#f(compiled-function " stream)

I.e., it's from the "pretty" version of prin1, and is not meant to be
readable by the Lisp reader.

I've now mentioned this in the Special Read Syntax node in the lispref
manual in Emacs 28.2.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Drew Adams]

> > See https://urldefense.com/v3/__https://stackoverflow.com/q/72547221/729907
> __;!!ACWV5N9M2RV99hQ!Js5VF7KbuZreJUFSLAH2FrOVle2g3oyTYcFXS7qlnAwG8QAl9v
> GcS1skzoz2U2AgbNowlTxv7NJQ$ .
> >
> > Users see this #f(...) syntax.  They should be able to consult the
> > doc in some way to find out what it is/means.  Please consider
> > documenting it in the Elisp manual.  Thx.
> 
> From the URL:
> 
> The syntax in question is in the following expression
> 
> ((remote . emacs)
>  (system . #f(compiled-function
>           (file path)
>           #<bytecode -0x47e8150df949387>))
>  (t . #f(compiled-function
>      (file path)
>      #<bytecode -0x47e8150df949387>)))
> 
> It's from:
> 
> (cl-defmethod cl-print-object ((object compiled-function) stream)
>   (unless stream (setq stream standard-output))
>   ;; We use "#f(...)" rather than "#<...>" so that pp.el gives better
> results.
>   (princ "#f(compiled-function " stream)
> 
> I.e., it's from the "pretty" version of prin1, and is not meant to be
> readable by the Lisp reader.
> 
> I've now mentioned this in the Special Read Syntax node in the lispref
> manual in Emacs 28.2.

Thanks, that's a start (and all that the bug report
requested: document in the manual).

But is there any chance this "pretty"-printing itself
can be made more human-friendly / communicative?

Aside from (I guess) naming the formal parameters, it
looks like it just says "BLAT$%@#(*&{}:"|?><(/.,!!".

https://stackoverflow.com/a/72561466/729907

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> But is there any chance this "pretty"-printing itself
> can be made more human-friendly / communicative?
>
> Aside from (I guess) naming the formal parameters, it
> looks like it just says "BLAT$%@#(*&{}:"|?><(/.,!!".

Well, that's what byte code looks like.  Apart from that, "it" is a
clickable button that will disassemble that code for you if you click
it.  Not good enough?

Michael.

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Drew Adams]

> > But is there any chance this "pretty"-printing itself
> > can be made more human-friendly / communicative?
> >
> > Aside from (I guess) naming the formal parameters, it
> > looks like it just says "BLAT$%@#(*&{}:"|?><(/.,!!".
> 
> Well, that's what byte code looks like.  Apart from that, "it" is a
> clickable button that will disassemble that code for you if you click
> it.  Not good enough?

Dunno whether it's good enough.  Depends on why someone
might want to understand what's printed.

From the original thread:

  this is apparently "special read syntax", i.e., Lisp
  reader syntax that's not readable by the Lisp reader
  but is meant to communicate something to humans. ...

  What the source code for the function is; what the
  function does (e.g., it's doc); or where it's defined
  -- nothing like that is conveyed in the "pretty"-print.
  And whether "compiled" there means byte-compiled or
  "native"-compiled also isn't made clear.

(Dunno whether any of those missing things has now been
added as part of the bug fix.)

Maybe instead of (or in addition to) a disassembly, a
user could be pointed - a least in some cases - to the
original source code (Lisp or C)?

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> Maybe instead of (or in addition to) a disassembly, a
> user could be pointed - a least in some cases - to the
> original source code (Lisp or C)?

Are there such cases?  The place is not always well defined.

In the cited original thread, when you see

  org-file-apps-windowsnt is a variable defined in `org.el'.

in the C-h v popup you just click on the "org.el" button and are
directly guided to the source of the byte-code function.  We can't get
much better I guess since we don't save the exact position of every
lambda expression when compiling.

If the byte-code function is named, you can click on the name that will
likely be around.  And if it has not, it's probably not trivial to find
a related place of a definition (if there is one).

So, hard to answer without a real-life example where this would actually
be a real improvement.

Michael.

bug#55853: 28.1; Please document f#(...) syntax in Elisp manual

[Drew Adams]

> > Maybe instead of (or in addition to) a disassembly, a
> > user could be pointed - a least in some cases - to the
> > original source code (Lisp or C)?
> 
> Are there such cases?  The place is not always well defined.
> 
> In the cited original thread, when you see
> 
>   org-file-apps-windowsnt is a variable defined in `org.el'.
> 
> in the C-h v popup you just click on the "org.el" button and are
> directly guided to the source of the byte-code function.  We can't get
> much better I guess since we don't save the exact position of every
> lambda expression when compiling.
> 
> If the byte-code function is named, you can click on the name that will
> likely be around.  And if it has not, it's probably not trivial to find
> a related place of a definition (if there is one).
> 
> So, hard to answer without a real-life example where this would
> actually be a real improvement.

Certainly there are cases where there's no reasonable
way to locate where the thing was defined.  But when
there is a reasonable way it's good to point to the
definition/source code.

For cases where the name is displayed and you can
click it to go to some text with a link to the source,
there's no great problem (but perhaps getting there
could be more direct).

My point was that getting to the source code is what
a user wants more often than getting a disassembled
representation.