Control characters in doc strings

Control characters in doc strings

[Eli Zaretskii]

With the current master I see the following warnings:

  In toplevel form:
  progmodes/cc-langs.el:682:18: Warning: docstring contains control char #x0d (position 15)
  progmodes/cc-langs.el:704:18: Warning: docstring contains control char #x0d (position 10)
  progmodes/cc-langs.el:841:18: Warning: docstring contains control char #x0c (position 9)
  progmodes/cc-langs.el:841:18: Warning: docstring contains control char #x0d (position 11)
  progmodes/cc-langs.el:1836:18: Warning: docstring contains control char #x0d (position 9)

However, I don't think I see any such control characters there, at
least not when I invoke "C-h v".

Re: Control characters in doc strings

[Mattias Engdegård]

24 feb. 2024 kl. 11.58 skrev Eli Zaretskii <eliz@gnu.org>:

> With the current master I see the following warnings:
> 
>  In toplevel form:
>  progmodes/cc-langs.el:682:18: Warning: docstring contains control char #x0d (position 15)
>  progmodes/cc-langs.el:704:18: Warning: docstring contains control char #x0d (position 10)
>  progmodes/cc-langs.el:841:18: Warning: docstring contains control char #x0c (position 9)
>  progmodes/cc-langs.el:841:18: Warning: docstring contains control char #x0d (position 11)
>  progmodes/cc-langs.el:1836:18: Warning: docstring contains control char #x0d (position 9)
> 
> However, I don't think I see any such control characters there, at
> least not when I invoke "C-h v".

It's from a macro whose expansion includes (lambda () VALUE), and if VALUE is a string it will be interpreted as a doc string. It is easy to suppress (now done), but perhaps we should change the old compiler logic so that a single string literal isn't both a doc string and return value.

Re: Control characters in doc strings

[Emanuel Berg]

Eli Zaretskii wrote:

> progmodes/cc-langs.el:682:18: Warning: docstring contains
> control char #x0d (position 15)

That is carriage return (cr), or ^M (not the actual char).

C-x 8 RET d RET

> control char #x0c (position 9)
> progmodes/cc-langs.el:841:18: Warning: docstring contains

That is form feed (ff), or ^L.

C-x 8 RET c RET

-- 
underground experts united
https://dataswamp.org/~incal

Re: Control characters in doc strings

[Basil L. Contovounesios]

What about these?

progmodes/verilog-mode.el:12424:2: Warning: docstring contains control char #x0c (position 2845)
progmodes/verilog-mode.el:12875:2: Warning: docstring contains control char #x0c (position 1187)

It looks like verilog-mode intentionally uses form feed characters to
section large docstrings.  Perhaps these are used as a source for
generating external (e.g. HTML) docs (if not of verilog-mode then
conceivably of other packages).  Perhaps we should continue to allow
such usage?  (These are the only in-tree instances, BTW.)

Thanks,
-- 
Basil

Re: Control characters in doc strings

[Alfred M. Szmidt]

   What about these?

   progmodes/verilog-mode.el:12424:2: Warning: docstring contains control char #x0c (position 2845)
   progmodes/verilog-mode.el:12875:2: Warning: docstring contains control char #x0c (position 1187)

I'd think it is fair to consider this specific usage "just wrong;
don't do it" -- if you narrow to a page you will get something that is
not correct and will screw Lisp indentation and all kind of things!

\f
;;; Auto creation:
;;

(defun verilog-auto-arg-ports (sigs message indent-pt)
  "Print a list of ports for AUTOARG.
Takes SIGS list, adds MESSAGE to front and inserts each at INDENT-PT."
[...])

(defun verilog-auto-arg ()
  "Expand AUTOARG statements.
Replace the argument declarations at the beginning of the
module with ones automatically derived from input and output
statements.  This can be dangerous if the module is instantiated
using position-based connections, so use only name-based when
instantiating the resulting module.  Long lines are split based
on the `fill-column', see \\[set-fill-column].

[...]
\f
Where the list of inputs and outputs came from the inst module.
\f
For more information see the \\[verilog-faq] and forums at URL
`https://www.veripool.org'."
  (save-excursion
[...]))