Introducing Master of Ceremonies, a package for presentations

Introducing Master of Ceremonies, a package for presentations

[Psionic K]

I use this package for making videos and presentations.  It's almost
ready for archives.

https://github.com/positron-solutions/master-of-ceremonies
https://github.com/positron-solutions/master-of-ceremonies.git

`mc-focus' is one of the most useful commands.  Select a region, call
it, and that region will be displayed full screen with appropriate
scaling.  You can highlight multiple regions by selecting and using
the "l" key.  The "." key will activate a "subtle" cursor that goes
away after a short number of blinks to assist highlighting without
needing to hide the cursor all the time.  There is a magit-style
interface for learning the rest of the modal bindings, available under
"h".

The `mc-kill-ring-save` command will save an expression that can play
back this display, making it rather easy to step through sequences of
highlights.  This produces high quality illustrations of code that
line up well with explanation.  When combined with dslide (on non-GNU
ELPA and MELPA), the two packages can create effective presentations
about code that are missing almost nothing from dedicated presentation
software.

Many of the tools for accomplishing this were valuable as standalone
modes for presentation
- `mc-quiet-mode' suppresses messages
- `mc-subtle-cursor-mode' is great for using the cursor like a
transient laser pointer
- `mc-face-remap' will remap many faces from presets.  I use this to
tweak faces for  MC Focus screenshots.
- `mc-fixed-frame' sets to preset resolutions for recording videos and
corrects the size when minor actions like resizing buffer text change
the size of the frame

Bindings for built-in Emacs behaviors like hiding the mode line are
provided.  I only need to add support for modifying the transient to
allow myself to add keycast toggling.

These tools have been combined into a one-stop interface, `mc-dispatch'.

The core code for `mc-focus' acquired numerous behaviors I was using
personally and so the code is rather off.  It needs to be
re-architectured for smoothly supporting rectangle selection,
whitespace trimming, and playback.  I have experimented with
translating overlays from the source into the text properties of the
display.

Numerous things work in numerous settings, so I have made it available
ahead of publishing on package archives.  Emacs conf participants may
find it of use for some last minute embellishment.

PRs and issues will be attended to.

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

I intend to submit Master of Ceremonies to Non-GNU ELPA.  I'm deciding what
changes are necessary to facilitate that and looking for low-hanging fruit
to improve user results.

- I'm likely to change the package file name and consequent naming over to
mc.  Please understand when this breaks use-package expressions.
- Autoloads are being made for 29.4 since there is no stable 30.x release
to target right now
- Mark several customize variables as safe local variables
- Generate a manual just to point users towards likely entry points like
`mc-focus' and `mc-present'
- More stable API for `mc-focus' playback

The following architecture and feature changes are planned (this is as much
rubber ducking as it is communication):

One disappointment of mine that affects both dslide and mc is the lack of
sufficient multi-monitor detection on XFCE even when xrandr is present.
The feature I want to implement is to display a frame or presentation
fullscreen on the "other" monitor because in dslide, the comments in the
base buffer are visible and can be used for narration.  At present, it
appears I would need to interpret xrandr itself since the high-level
interface Emacs ships with appears not to distinguish the two physical
monitors when they are treated as a single virtual screen.  Since we need a
new frame either way, I may just do that for now and later add customize
support to "guess" the correct location and fullscreen parameter of the new
frame.

All region selection for `mc-focus' will be re-architectured to normalize
onto the rectangle selection case.  The non-rectangle case will be
translated internally to work like the rectangle case.  The reason is that
I need to support trimming and to "do the right thing" when the user begins
the selection with indentation.  The rectangle case is more general to
every consequent problem.  This path may also adapt to handle visual lines
better, injecting newlines when the column exceeds the window column width.

I've realized a common mc workflow of mine is to hide some text completely
rather than just highlight substrings.  Subsequently, un-hiding creates the
effect of building up a larger expression with all text remaining fixed in
place, invaluable when presenting code.

The playback features of MC almost assuredly need keyword arguments.
Display can be affected by the string, its text properties, overlays, and
invisibility specs.  One option is to merge all of the properties and
overlays.  A more flexible option for interactive explanation of display
itself is to toggle the invisibility spec and overlays on the fly.  This is
unsupported during playback without retaining the "redundant" information
of unmerged properties and overlays etc.  I need to add support for
propagating overlay priorities.  Reducing all overlays is an option, but
the rules for overlays that are fully contained etc are a bit tricky and I
don't want to emulate all of the behavior within MC.

Images in theory can work.  The size of the image needs to be adjusted
according to the scale of the text overlay.  There could be edge cases.
Any specified space used for centering would need to be adjusted.  That
holds for text as well.

[-- Attachment #2: Type: text/html, Size: 3580 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Dmitry Gutov]

Hi!

On 04/12/2024 04:45, Psionic K wrote:
> - I'm likely to change the package file name and consequent naming over 
> to mc.  Please understand when this breaks use-package expressions.

Just FWIW, there is an existing package which effectively uses the 
prefix "mc" - just following it with "/", it's called multiple-cursors, 
and it's been pretty popular a number of years ago.

Probably remains so (2.3K stars on GH).

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

> Just FWIW, there is an existing package which effectively uses the
> prefix "mc" - just following it with "/", it's called multiple-cursors,
> and it's been pretty popular a number of years ago.

Thanks, I hadn't seen that on MELPA, only its mc-* derivatives.

`moc' was the fallback plan.  It does not trivially complete together with
any `mc' symbols.  Anyone object to that?

[-- Attachment #2: Type: text/html, Size: 569 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

* Psionic K <psionik@positron.solutions> [2024-12-03 19:03]:
> I use this package for making videos and presentations.  It's almost
> ready for archives.
> 
> https://github.com/positron-solutions/master-of-ceremonies
> https://github.com/positron-solutions/master-of-ceremonies.git

Thanks, very nice and totally useful.

But I do not need those 2 vertical lines left and right, I need it all over the screen.

I am to use it for displaying phone number and short notes or passwords which have to be observed.

Like (mc-focus "+123456678") but lines are only confusing.

-- 
Jean Louis

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

Help me understand the problem more.  The current implementation uses
window margins.  If your Emacs has obviously visible margins, then the
effect is less good.  Can you set window margins to zero to see if that's
the source of your "vertical lines"?

I can switch the implementation to using specified space to overcome this
if it is indeed what we're talking about.

If there's a communication issue, feel free to drop a screenshot on a
github issue.

I have updated the git and package prefix as part of my preparation for
Non-GNU ELPA and MELPA.

https://github.com/positron-solutions/moc
https://github.com/positron-solutions/moc.git


On Wed, Dec 4, 2024 at 6:17 PM Jean Louis <bugs@gnu.support> wrote:

> * Psionic K <psionik@positron.solutions> [2024-12-03 19:03]:
> > I use this package for making videos and presentations.  It's almost
> > ready for archives.
> >
> > https://github.com/positron-solutions/master-of-ceremonies
> > https://github.com/positron-solutions/master-of-ceremonies.git
>
> Thanks, very nice and totally useful.
>
> But I do not need those 2 vertical lines left and right, I need it all
> over the screen.
>
> I am to use it for displaying phone number and short notes or passwords
> which have to be observed.
>
> Like (mc-focus "+123456678") but lines are only confusing.
>
> --
> Jean Louis
>


-- 
Only the Future is Certain

[-- Attachment #2: Type: text/html, Size: 2463 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

Hello Philip,

I have updated the git and package prefix as part of my preparation for
Non-GNU ELPA and MELPA.  Unless someone has a good objection in the near
future, moc is the new prefix.  There has been a short time for discussion,
but my search indicates it's not a common substring except for completing
with "mock".

https://github.com/positron-solutions/moc
https://github.com/positron-solutions/moc.git

The current package lint shows no issues and the compile is clean.  I have
added a NEWS.org and moc.texi.  The overall scheme is similar to what I
used in dslide.

I have marked code I still consider unreliably unstable / experimental with
🚧 to note areas that should be ransacked by vandals at the first
convenience.

I'm currently working on adding some kind of anti-highlight to completely
obscure a bit of text and some trimming to try and stabilize the playback
API for use in dslide.

On Wed, Dec 4, 2024 at 6:55 PM Psionic K <psionik@positron.solutions> wrote:

> Help me understand the problem more.  The current implementation uses
> window margins.  If your Emacs has obviously visible margins, then the
> effect is less good.  Can you set window margins to zero to see if that's
> the source of your "vertical lines"?
>
> I can switch the implementation to using specified space to overcome this
> if it is indeed what we're talking about.
>
> If there's a communication issue, feel free to drop a screenshot on a
> github issue.
>
> I have updated the git and package prefix as part of my preparation for
> Non-GNU ELPA and MELPA.
>
> https://github.com/positron-solutions/moc
> https://github.com/positron-solutions/moc.git
>
>
> On Wed, Dec 4, 2024 at 6:17 PM Jean Louis <bugs@gnu.support> wrote:
>
>> * Psionic K <psionik@positron.solutions> [2024-12-03 19:03]:
>> > I use this package for making videos and presentations.  It's almost
>> > ready for archives.
>> >
>> > https://github.com/positron-solutions/master-of-ceremonies
>> > https://github.com/positron-solutions/master-of-ceremonies.git
>>
>> Thanks, very nice and totally useful.
>>
>> But I do not need those 2 vertical lines left and right, I need it all
>> over the screen.
>>
>> I am to use it for displaying phone number and short notes or passwords
>> which have to be observed.
>>
>> Like (mc-focus "+123456678") but lines are only confusing.
>>
>> --
>> Jean Louis
>>
>
>
> --
> Only the Future is Certain
>


-- 
Only the Future is Certain

[-- Attachment #2: Type: text/html, Size: 4346 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

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

* Psionic K <psionik@positron.solutions> [2024-12-04 12:57]:
> Help me understand the problem more.  The current implementation uses
> window margins.  If your Emacs has obviously visible margins, then the
> effect is less good.  Can you set window margins to zero to see if that's
> the source of your "vertical lines"?

See vertical lines on left and right side in attachment.

-- 
Jean Louis

[-- Attachment #2: 2024-12-04_20-50.png --]
[-- Type: image/png, Size: 31178 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

I don't know what display behavior creates the bars.  I think it's
margins, but let's find out.  I have added a branch, no-margins, which
uses specified space instead of margins.  Please let me know if it
fixes your problem.

Another critical bug fix is in both branches.  The state of
`moc-subtle-cursor-mode' was initialized to t during loading (visible
after restart) and `moc-focus' inferred that it needed to restore
`moc-subtle-cursor-mode' after the first call, leaving behind a very
much activated `moc-subtle-cursor-mode' for the user to clean up
manually.

Re: Introducing Master of Ceremonies, a package for presentations

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

The name "master of ceremonies" is poetical, but on practical grounds
it might be better to call it "presenter".  That is shorter, and would
make its purpose clear to everyone.


Bt "mc" is too terse -- it won't 
-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

* Psionic K <psionik@positron.solutions> [2024-12-05 04:26]:
> I don't know what display behavior creates the bars.  I think it's
> margins, but let's find out.  I have added a branch, no-margins, which
> uses specified space instead of margins.  Please let me know if it
> fixes your problem.

I tried new branch and I see same vertical bars.

It is caused by `set-window-margins' of course.

Point of displaying something large is to present it conclusively. If
you introduce visible margins and those margins will be also in
different colors in different themes. 

It makes the display inconclusive, it makes a bit confusing "what am I seeing there".

-- 
Jean Louis

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

I've updated the no-margins branch.

I reproduced your issue by setting a fringe face background different
than my default face background.  MoC now sets fringe face background
to nil and restores it after done.  While I did also resize the
fringes to zero, unless I can handle the echo area fringes and restore
those, I cannot be more surgical at this time.

Tangentially, the branch also contains overlay persistence and
playback I just added, which can help displaying fancy org modern
excerpts.  I hope this doesn't confound our effort.

Let me know if this helps.

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

* Psionic K <psionik@positron.solutions> [2024-12-05 11:29]:
> I've updated the no-margins branch.
> 
> I reproduced your issue by setting a fringe face background different
> than my default face background.  MoC now sets fringe face background
> to nil and restores it after done.  While I did also resize the
> fringes to zero, unless I can handle the echo area fringes and restore
> those, I cannot be more surgical at this time.

with

git branch --list

I see no branches now any more, but it was before.

And why you need branch? Just make it in the main.

-- 
Jean Louis

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

* Psionic K <psionik@positron.solutions> [2024-12-05 04:28]:
> I don't know what display behavior creates the bars.  I think it's
> margins, but let's find out.  I have added a branch, no-margins, which
> uses specified space instead of margins.  Please let me know if it
> fixes your problem.

It works now, and I didn't use any branch. Good there are no lines on screen.

I have now included it in RCD Notes & Hyperscope, The Dynamic
Knowledge Repository for GNU Emacs, as it is going to be heavily used
in demonstrations of phone numbers, email addresses, each time user
has to write something on the paper, or call by watching the number,
street address, zip code, the last killed information, and so on.

Here is the video demonstration:
https://gnu.support/images/2024/12/2024-12-05/2024-12-05-21:38:25.ogv

I think that longer lines shall be wrapped, you have to include word
wrap, as otherwise lines will become smaller thant the original line!

-- 
Jean Louis

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

> I think that longer lines shall be wrapped, you have to include word
> wrap, as otherwise lines will become smaller thant the original line!

It's true.  Especially with visual line mode, I need to decide how long the
lines are and inject newlines.

[-- Attachment #2: Type: text/html, Size: 326 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

Programming/git/moc/moc.el: Warning: ‘when-let’ is an obsolete macro (as of 31.1); use ‘when-let*’ or ‘and-let*’ instead. [3 times]
Programming/git/moc/moc.el: Warning: ‘if-let’ is an obsolete macro (as of 31.1); use ‘if-let*’ instead. [3 times]
Programming/git/moc/moc.el: Warning: ‘when-let’ is an obsolete macro (as of 31.1); use ‘when-let*’ or ‘and-let*’ instead. [2 times]
Programming/git/moc/moc.el: Warning: ‘if-let’ is an obsolete macro (as of 31.1); use ‘if-let*’ instead. [2 times]

-- 
Jean Louis

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

To be clear, Jean, are you conducting this review for Non-GNU ELPA?

> I think that longer lines shall be wrapped, you have to include word
> wrap, as otherwise lines will become smaller thant the original line!

Such a change is in progress.  I'm just about to stash some re-work of the
core logic for `moc-focus' to have general support for most cases.  It's
looking like 1k lines of rework and quite annoying.  I suspect there must
be a better way.

I can fit visual lines by using their horizontal and vertical height after
breaks to calculate what will provide the best aspect ratio.  Such a
calculation with reasonable accuracy can be done in one step without
troubling Emacs.  With some length of selection there is never anything I
can do to make the text big, but we can make it pretty.

The fundamental issue remains that translating overlays after such a reflow
is not so trivial.  That is unless I do the reflow within a buffer with
editing commands after copying all of the necessary information over
instead of stitching and welding overlays and strings together without the
aid of a buffer.  This would allow some savings by re-using editing logic
to preserve overlays and property applications to injected whitespace.
Instead of calculating things I can just read the final result of all the
edits.  This seems more robust and I think I will implement the easiest and
most relevant cases first:

- whitespace trimming of indentation
- whitespace injection to maintain column alignment of first line in source
- newline insertion to reflow long logical lines and match the target
aspect ratio

I might just need a break lol.

[-- Attachment #2: Type: text/html, Size: 1837 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Jean Louis]

* Psionic K <psionik@positron.solutions> [2024-12-07 15:03]:
> To be clear, Jean, are you conducting this review for Non-GNU ELPA?

For my software and for your improvement.

It is presenting well, but only short words. It should at least
present well sentences and paragraphs.

> > I think that longer lines shall be wrapped, you have to include word
> > wrap, as otherwise lines will become smaller thant the original line!
> 
> Such a change is in progress.  I'm just about to stash some re-work of the
> core logic for `moc-focus' to have general support for most cases.  It's
> looking like 1k lines of rework and quite annoying.  I suspect there must
> be a better way.

- calculate how many letters can fit in single line, for the maximum presentable width

- I would remove any double horizontal white space from sentences or paragraphs

- I would convert it to list of words

- then make new list of concatenated chunks of words that fit in the single line

- then concatenate maybe with new lines

- then present it

> I can fit visual lines by using their horizontal and vertical height after
> breaks to calculate what will provide the best aspect ratio.  Such a
> calculation with reasonable accuracy can be done in one step without
> troubling Emacs.  With some length of selection there is never anything I
> can do to make the text big, but we can make it pretty.

I think yes with word parsing and deciding how to fit it.

-- 
Jean Louis

Re: Introducing Master of Ceremonies, a package for presentations

[Psionic K]

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

I have pushed master with some packaging related fixups to make progress on
adding to MELPA / Non-GNU ELPA.  Among changes, I have adopted a new
strategy that leans on Emacs text editing.  The result is much more
satisfactory than the overlay stitching and translation I had started work
on in another stash which will now be deleted.

As a benefit, we finally have some basic whitespace cleanup and indentation
preservation when selections do not begin at a line beginning, such as can
be required if the preceding text is not whitespace.

What remains is an implementation of rectangle trimming and following up on
my continuation strategy, I will describe below.

> remove any double horizontal white space from sentences or paragraphs

User responsibility.  I can't make everyone or a reliable majority happy
with either decision and input text expresses these decisions or should.

> It is presenting well, but only short words. It should at least
> present well sentences and paragraphs.

The new `:continuation` key in `moc-focus` replay arg plist reveals my
strategy for this.  I read the state of `visual-line-mode` and
`adaptive-wrap-prefix-mode`.  I will default to truncation when these are
not active.  When they are active, I can calculate the right size as
described earlier and allow Emacs logic to wrap the text.  If in the future
text can be justified by an overlay or buffer-wide via a mode, it will be
easy to support, but I will not manually re-flow text because that is just
asking to re-implement and maintain the entire ball of yarn in Elisp, an
endeavour of very limited value to me and one that has workarounds for the
user:  Turn off read-only mode and make some edits.

When filling code with long lines and comments etc, the user's fill column
will usually be what they want.  I don't want to reflow Elisp code without
a lot more intelligence.  That is LLM work, not fiddly text editing rule
and heuristic based work.  Truncation is very robust at limiting the max
width.

For visual lines, along with the continuation strategy described above, I
am implementing a minimum character width, which is a heuristic to avoid
re-shaping text that is extremely short, below 30 characters or so.  Don't
want one word per line.

I can do manual justification, but honestly why not just do this with
specified space in Emacs and apply a text property if desired?  My
implementation will be useless by comparison in terms of coverage.  Images
can center.  Why not text?

[-- Attachment #2: Type: text/html, Size: 2963 bytes --]

Re: Introducing Master of Ceremonies, a package for presentations

[Philip Kaludercic]

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

Psionic K <psionik@positron.solutions> writes:

> Hello Philip,
>
> I have updated the git and package prefix as part of my preparation for
> Non-GNU ELPA and MELPA.  Unless someone has a good objection in the near
> future, moc is the new prefix.  There has been a short time for discussion,
> but my search indicates it's not a common substring except for completing
> with "mock".
>
> https://github.com/positron-solutions/moc
> https://github.com/positron-solutions/moc.git

[...]

Sorry for the delay in answering, it was a lot of code and I had less
time.  Either way, here are my comments; hope they are useful:


[-- Attachment #2: Type: text/plain, Size: 20681 bytes --]

diff --git a/moc.el b/moc.el
index 23d684a..a14c67f 100644
--- a/moc.el
+++ b/moc.el
@@ -1,11 +1,11 @@
-;;; moc.el --- Master of Ceremonies -*- lexical-binding: t; -*-
+;;; moc.el --- Master of Ceremonies                   -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2024 Positron Solutions <contact@positron.solutions>
 
 ;; Author: Positron Solutions <contact@positron.solutions>
 ;; Keywords: convenience, outline
 ;; Version: 0.6.3
-;; Package-Requires: ((emacs "29.4") (hide-mode-line "1.0.3") (transient "0.7.2"))
+;; Package-Requires: ((emacs "29.4") (hide-mode-line "1.0.3") (transient "0.7.2")) <- "hide-mode-line" is not a known package?
 ;; Homepage: http://github.com/positron-solutions/moc
 
 ;;; Copying:
@@ -58,8 +58,8 @@
 When using a transient cursor effect, the duration of cursor visibility
 is the product of this and `moc-subtle-cursor-interval'.
 
-\\[info] elisp::Cursor Parameters."
-  :type 'integer)
+See the Info node `(elisp) Cursor Parameters'."
+  :type 'natnum)
 
 (defcustom moc-subtle-cursor-interval 0.2
   "Length of cursor blink interval in seconds.
@@ -69,7 +69,7 @@ Values smaller than 0.013 will be treated as 0.013."
 (defcustom moc-focus-max-height-factor 0.75
   "Focused text maximum height fraction.
 This is never exceeded."
-  :type 'float)
+  :type 'float)				;what are the legal values?
 
 (defcustom moc-focus-max-width-factor 0.75
   "Focused text maximum width fraction.
@@ -92,7 +92,7 @@ When focusing extremely small regions, this value prevents the text from
 being scaled comically large.  If you just want to render single symbols
 or extremely short expressions, this setting can be used to control
 excessively large results."
-  :type 'float)
+  :type 'float)				;are fixnums really not acceptable?
 
 (defcustom moc-focus-default-remaps '(org-block-no-background)
   "A list of remap presets to apply to focused text.
@@ -105,7 +105,7 @@ The defaults will just be turned on to save time in the usual cases."
 ;; buffers are focus buffers.  Either scan, track, or don't bother.  Multiple
 ;; focus buffers are impossible without names.
 
-(defcustom moc-screenshot-dir #'temporary-file-directory
+(defcustom moc-screenshot-dir #'temporary-file-directory ;what about `xdg-cache-home'?
   "Directory path or function that returns a directory path.
 Directory path is a string."
   :type '(choice string function))
@@ -115,10 +115,20 @@ Directory path is a string."
 Options are same as supported by the backend, `x-export-frames' for now,
 either pdf (default), png, postscript, or svg.  Supported types are
 determined by the compile-time configuration of cairo."
-  :type '(choice (const :tag "PNG" png)
-                 (const :tag "Scalable Vector Graphics" svg)
-                 (const :tag "PDF" pdf)
-                 (const :tag "Postscript" postscript)))
+  :type
+  (eval-when-compile
+    (let ((choices '()))
+      (dolist (choice '((png . "PNG")
+			(svg . "Scalable Vector Graphics")
+			(pdf . "PDF")
+			(postscript . "Postscript")))
+	(when (condition-case nil
+		  (always (x-export-frames nil (car choice)))
+		(error nil))
+	  (push `(const :tag ,(cdr choice) ,(car choice))
+		choices)))
+      ;; FIXME: What if (null choices)?
+      `(choice ,@choices))))
 
 (defcustom moc-fixed-frame-sizes
   '((youtube-short . (1080 . 1920))
@@ -136,10 +146,10 @@ Form is one of:
 NAME is a symbol, WIDTH and HEIGHT are integers, and FULLSCREEN
 is valid value for the `fullscreen' frame parameter.
 
-\\[info] elisp::Frame Parameters"
-  :type '(cons symbol
-               (choice (cons number number)
-                       symbol)))
+See the Info node `(elisp) Frame Parameters'."
+  :type '(repeat (cons symbol		;or `alist'
+		       (choice (cons number number)
+			       symbol))))
 
 (defcustom moc-face-remap-presets
   '((bold . ((default :weight bold)))
@@ -152,7 +162,7 @@ element of PRESET is a cons of FACE SPECS where SPECS is one of the
 forms understood by `face-remap-add-relative'.
 
 \\[info] elisp::Face Remapping"
-  :type 'alist)
+  :type 'alist)				;you can further specialise this type with :key-type and :value-type
 
 (defcustom moc-frame-text-scale-step 1.05
   "The factor of increase or decrease.
@@ -260,7 +270,7 @@ KEEP-EXISTING"
                    (or (moc--read-remap remap)
                        (user-error "Remapping not found"))
                  remap)))
-    (mapc (lambda (r)
+    (mapc (lambda (r)			;dolist is cheaper
             (let ((face (car r))
                   (specs (cdr r)))
               (push (face-remap-add-relative face specs)
@@ -273,7 +283,7 @@ KEEP-EXISTING"
 
 (define-minor-mode moc-hide-cursor-mode
   "Make cursor completely hidden."
-  :group 'moc
+  :global nil
   (cond
    (moc-hide-cursor-mode
     (if (minibufferp)
@@ -294,20 +304,20 @@ scale and deactivating it resets their original scale.
 
 This mode is not aware of other mechanisms of tracking the frame's text
 scale and conflicting modes will clobber each other."
-  :group 'moc
   :global t
   (cond
    (moc-frame-text-scale-mode
     (cl-loop
      for f in (frame-list)
-     do (when-let ((step (frame-parameter f 'moc--frame-text-scale)))
-          (let* ((orig (or (frame-parameter f 'moc--frame-text-scale-orig)
-                           (face-attribute 'default :height f))))
-            (set-face-attribute
-             'default f :height
-             (round (* orig (expt moc-frame-text-scale-step step))))))))
+     do (when-let* ((step (frame-parameter f 'moc--frame-text-scale))
+		    (orig (or (frame-parameter f 'moc--frame-text-scale-orig)
+                              (face-attribute 'default :height f))))
+          (set-face-attribute
+           'default f :height
+	   ;; I infer that `orig' cannot be nil, as you are multiplying it here?
+           (round (* orig (expt moc-frame-text-scale-step step)))))))
    (t
-    (cl-loop
+    (cl-loop				;this seems like it would also be simpler with a dolist.
      for f in (frame-list)
      do (when-let ((orig (frame-parameter f 'moc--frame-text-scale-orig)))
           (set-face-attribute 'default f :height orig))))))
@@ -315,11 +325,11 @@ scale and conflicting modes will clobber each other."
 (defun moc--frame-text-scale-cleanup-when-done ()
   "Self-explanatory.
 If no frames have a non-zero step value, turn off the mode."
-  (unless (cl-loop
-           for f in (frame-list)
-           when (when-let ((step (frame-parameter f 'moc--frame-text-scale)))
-                  (not (= 0 step)))
-           return f)
+  (unless (catch 'found			;just a suggestion if you want to get rid of cl-lib
+	    (dolist (frame (frame-list))
+	      (when-let* ((step (frame-parameter f 'moc--frame-text-scale))
+			  ((/= 0 step)))
+                (throw 'found frame))))
     (moc-frame-text-scale-mode -1)))
 
 (defun moc-frame-text-scale-increase ()
@@ -392,8 +402,8 @@ PROMPT will be used as a prompt.  INITIAL is an initial value.
 Shocking."
   (let ((str (read-from-minibuffer
               prompt
-              (when initial (number-to-string initial)) nil nil nil)))
-    (if (string-match-p "^-?[0-9]*$" str)
+              (and initial (number-to-string initial)) nil nil nil)))
+    (if (string-match-p "^-?[0-9]+$" str) ;or is the empty string a valid number?
         (string-to-number str)
       (user-error "Could not read number: %s" str))))
 
@@ -428,11 +438,11 @@ blink if appropriate."
     (internal-show-cursor nil (not (internal-show-cursor-p))))
   ;; Suspend counting blinks when the w32 menu-bar menu is displayed,
   ;; since otherwise menu tooltips will behave erratically.
-  (or (and (fboundp 'w32--menu-bar-in-use)
-           (w32--menu-bar-in-use))
-      ;; XXX guarding this expression upsets the blink count and I don't know
-      ;; how it's supposed to work.
-      (setq moc-subtle-cursor-blinks-done (1+ moc-subtle-cursor-blinks-done)))
+  (unless (and (fboundp 'w32--menu-bar-in-use)
+               (w32--menu-bar-in-use))
+    ;; XXX guarding this expression upsets the blink count and I don't know
+    ;; how it's supposed to work.
+    (setq moc-subtle-cursor-blinks-done (1+ moc-subtle-cursor-blinks-done)))
   ;; Each blink is two calls to this function.
   (when (and (> moc-subtle-cursor-blinks 0)
              (>= moc-subtle-cursor-blinks-done (* 2 moc-subtle-cursor-blinks)))
@@ -454,8 +464,8 @@ Returns whether we have any focused non-TTY frame."
          (while frame-list
            (let ((frame (pop frame-list)))
              (when (and (display-graphic-p frame) (frame-focus-state frame))
-               (setf any-graphical-focused t)
-               (setf frame-list nil))))
+               (setq any-graphical-focused t) ;you use `setq' everywhere else
+               (setq frame-list nil))))
          any-graphical-focused)))
 
 (defun moc-subtle-cursor-check ()
@@ -489,6 +499,8 @@ found active.
       (blink-cursor-mode -1))
     (when moc-hide-cursor-mode
       (moc-hide-cursor-mode -1))
+    ;; Can you explain why you are advising the function behind the
+    ;; symbol instead of setting the function?
     (add-function :after after-focus-change-function
                   #'moc-subtle-cursor-check)
     (add-hook 'after-delete-frame-functions #'moc-subtle-cursor-check)
@@ -522,8 +534,7 @@ found active.
 (define-minor-mode moc-quiet-mode
   "Inhibit messages in the echo area.
 ⚠️ Inhibiting messages is a bit dangerous.  If anything fails, because messages
-are disabled, there may be no obvious user feedback ☠️"
-  :group 'moc
+are disabled, there may be no obvious user feedback ☠️" ;I think it would be better to avoid emojis, as not everyone has the fonts installed.
   :global t
   (cond
    (moc-quiet-mode
@@ -543,7 +554,7 @@ are disabled, there may be no obvious user feedback ☠️"
   "Clean up hook if not guarding any more frames."
   (let ((frames (frame-list))
         guarded)
-    (while (and frames (not guarded))
+    (while (and frames (not guarded))	;I'd use `dolist'+`catch' here again
       (when (frame-parameter (pop frames) 'moc--fixed-frame-notify)
         (setq guarded t)))
     (unless guarded
@@ -630,7 +641,7 @@ parameter for `fullscreen'."
   (if (consp size)
       (unless (and (= (car size) (frame-pixel-width frame))
                    (= (cdr size) (frame-pixel-height frame)))
-        (let ((frame-resize-pixelwise t))
+        (let ((frame-resize-pixelwise t)) ;what happens in TUI Emacs?
           (set-frame-parameter nil 'fullscreen nil)
           (set-frame-size nil (car size) (cdr size) t)
           (message "set size: %sw %sh"
@@ -667,12 +678,10 @@ these behaviors may become more consistent."
          (new (cond
                (revert
                 (frame-parameter (selected-frame) 'moc--fixed-frame-revert))
-               ((stringp frame-size)
-                (cdr (assoc-string frame-size moc-fixed-frame-sizes)))
-               ((symbolp frame-size)
-                (cdr (assq frame-size moc-fixed-frame-sizes)))
+               ((or (symbolp frame-size) (stringp frame-size))
+                (cdr (assoc frame-size moc-fixed-frame-sizes)))
                ((consp frame-size) frame-size)
-               (t (error "Unrecognized size: %s" frame-size))))
+               ((error "Unrecognized size: %s" frame-size))))
          (current (if-let* ((fullscreen (frame-parameter nil 'fullscreen)))
                       fullscreen
                     (cons (frame-pixel-width)
@@ -718,10 +727,10 @@ Used in suffix command."
 (defun moc--dispatch-cursor-mode ()
   "Return cursor state for use in info class."
   (if-let* ((cursor (if (consp cursor-type)
-                       (car cursor-type)
-                     (if (eq cursor-type t)
-                         (frame-parameter nil 'cursor-type)
-                       cursor-type))))
+                        (car cursor-type)
+                      (if (eq cursor-type t)
+                          (frame-parameter nil 'cursor-type)
+                        cursor-type))))
       (if moc-subtle-cursor-mode
           (propertize (format "subtle %-4s" cursor)
                       'face 'transient-value)
@@ -741,7 +750,7 @@ Use in suffix command."
 
 (defun moc--dispatch-frame-text-scale ()
   "Return current frame text scale for info class."
-  (if-let ((step (frame-parameter (selected-frame) 'moc--frame-text-scale)))
+  (if-let* ((step (frame-parameter (selected-frame) 'moc--frame-text-scale)))
       (propertize (format "frame scale: %s" step)
                   'face 'transient-value)
     (propertize "off" 'face 'shadow)))
@@ -749,7 +758,7 @@ Use in suffix command."
 (defun moc--dispatch-frame-text-scale-p ()
   "Return if current frame has a non-zero text scale."
   (when-let ((step (frame-parameter (selected-frame) 'moc--frame-text-scale)))
-    (not (eq 0 step))))
+    (not (eq 0 step))))			;why `eq'?
 
 (defun moc--dispatch-text-scale ()
   "Return current text scale for info class."
@@ -761,9 +770,9 @@ Use in suffix command."
 (defun moc--dispatch-quiet-mode ()
   "Return description and quiet mode state for suffix."
   (format
-   "quiet %s"
+   "quiet %-3s"
    (if moc-quiet-mode
-       (propertize "on " 'face 'success)
+       (propertize "on" 'face 'success)
      (propertize "off" 'face 'shadow))))
 
 ;;;###autoload (autoload 'moc-dispatch "moc" nil t)
@@ -828,7 +837,7 @@ This just provides minor conveniences like pre-configured save path with
   (let* ((timestamp (format-time-string "%F-%T" (current-time)))
          (filename (format "screenshot-%s.svg" timestamp))
          (dir (moc--screenshot-save-dir))
-         (path (concat dir filename))
+         (path (file-name-concat dir filename))
          (data (x-export-frames nil moc-screenshot-type)))
     (unless (file-exists-p dir)
       (make-directory dir t))
@@ -906,14 +915,14 @@ into Emacs text flow logic in the first place.
 checking the final text size before adjusting the horizontal and
 vertical offset in `moc-focus-replay'."
   (cond
-   ((member 'truncate-lines continuation)
+   ((memq 'truncate-lines continuation)
     (set-window-margins window
                         (max 0 (- (window-width)
                                   (ceiling (* fill-column scale)))))
     (toggle-truncate-lines 1)
     (prog1 (window-text-pixel-size window)
       (set-window-margins window nil)))
-   ((member 'visual-line-mode continuation)
+   ((memq 'visual-line-mode continuation)
     (visual-line-mode 1)
     (set-window-margins window
                         (max 0 (- (window-width)
@@ -939,7 +948,7 @@ another window will likely leave something to be desired."
     (kill-buffer old))
   (let* ((base (current-buffer))
          (buffer (get-buffer-create "*MoC Focus*"))
-         (text (plist-get args :text))
+         (text (plist-get args :text))	;perhaps you'd like `map-let'?
          (overlay-specs (plist-get args :overlays))
          (invisibility-spec (plist-get args :invisibility-spec))
          (continuation (plist-get args :continuation))
@@ -1105,10 +1114,8 @@ Preserves total ordering of highlighted spans."
     (while-let ((h (pop highlights)))
       ;; If BEG and END include either or both ends of a highlight, we have to
       ;; modify spans.
-      (let ((h-beg-interior (and (>= (car h) beg)
-                                 (<= (car h) end)))
-            (h-end-interior (and (>= (cdr h) beg)
-                                 (<= (cdr h) end)))
+      (let ((h-beg-interior (not (< beg (car h) end)))
+            (h-end-interior (not (< beg (cdr h) end)))
             (h-beg-before (< (car h) beg))
             (h-end-after (> (cdr h) end)))
         (cond
@@ -1228,7 +1235,7 @@ OCCLUDES is a list of conses of BEG END to be occluded."
   "Raise user error if commands are called in wrong mode."
   (if-let* ((buffer (get-buffer "*MoC Focus*")))
       (set-buffer buffer)
-    (user-error "No MoC buffer found")))
+    (user-error "No MoC buffer found"))) ;this is really the mistake of the user?
 
 (defun moc-focus-highlight-clear ()
   "Delete all highlights and occludes."
@@ -1272,7 +1279,7 @@ to make occluded regions visible again."
   (moc--focus-assert-mode)
   (moc--focus-occlude beg end)
   ;; unnecessary to deactivate the mark when called any other way
-  (when (called-interactively-p 't)
+  (when (called-interactively-p t)
     (deactivate-mark))
   (moc--focus-apply-occludes moc--focus-occludes))
 
@@ -1286,7 +1293,7 @@ The shadow face will be added to the region between BEG and END."
   (moc--focus-un-highlight beg end)
   (moc--focus-un-occlude beg end)
   ;; unnecessary to deactivate the mark when called any other way
-  (when (called-interactively-p 't)
+  (when (called-interactively-p t)
     (deactivate-mark))
   (moc--focus-apply-highlights moc--focus-highlights)
   (moc--focus-apply-occludes moc--focus-occludes))
@@ -1297,8 +1304,7 @@ This enables independent demonstration of the effect of source overlays."
   (interactive nil moc-focus-mode)
   (moc--focus-assert-mode)
   (if moc--focus-overlays
-      (progn (mapc #'delete-overlay
-                   moc--focus-overlays)
+      (progn (mapc #'delete-overlay moc--focus-overlays)
              (setq moc--focus-overlays nil))
     (moc--focus-apply-overlays
      ;; whenever toggling overlays, a space exists at the 1 position, so we need
@@ -1362,7 +1368,7 @@ It is assumed that BUFFER was offset by BEG."
   (let ((old (current-buffer)))
     (set-buffer buffer)
     (goto-char 1)
-    (insert (make-string padding 32))   ; 32 is space
+    (insert (make-string padding ?\s))
     (set-buffer old)))
 
 (defun moc--focus-trim-rect (buffer _rect _offset)
@@ -1384,9 +1390,10 @@ extract the rectangle and then trim each line down to it's span."
   "Move forward through all whitespace.
 Do not exceed LIMIT.  Optional MULTILINE will also move forward through
 newlines."
-  (if multiline
-      (re-search-forward "[^[:space:]\t\n\r]" limit t)
-    (re-search-forward "[^ \t]" limit t))
+  (re-search-forward (if multiline
+			 "[^[:space:]\t\n\r]"
+		       "[^ \t]")
+		     limit t)
   (goto-char (match-beginning 0)))
 
 (defun moc--focus-backward-whitespace (limit &optional multiline)
@@ -1396,7 +1403,7 @@ newlines."
   (while (and (> (point) limit)
               (not (bobp))
               (looking-back (if multiline
-                                "[[:space:]]+"
+                                "[[:space:]\n]+" ;i assume?
                               "[ \t]+")
                             limit t))
     (goto-char (match-beginning 0))))
@@ -1503,8 +1510,7 @@ PROPS is a list returned from `overlay-properties'."
 
 ;; TODO customization
 (defun moc--focus-filter-overlay (o)
-  (unless (eq (overlay-get o 'face) 'region)
-    o))
+  (and (not(eq (overlay-get o 'face) 'region)) o))
 
 (defun moc--focus-extract-overlays (buffer)
   "Grab and serialize overlays from BUFFER."
@@ -1580,14 +1586,14 @@ ARGS contains the following keys:
                                      " *MoC Processing*")
                             :warning))
          (let* ((buffer (get-buffer-create " *MoC Processing*"))
-                (rect (when rectangle-mark-mode
-                        (extract-rectangle-bounds (region-beginning)
-                                                  (region-end))))
+                (rect (and rectangle-mark-mode
+                           (extract-rectangle-bounds (region-beginning)
+                                                     (region-end))))
                 (beg (region-beginning))
                 (end (region-end))
                 before)
            (when (string= (buffer-name) " *MoC Processing*")
-             (user-error "Cannot process the processing buffer: %S"
+             (user-error "Cannot process the processing buffer: %S" ;here the same as above: is this the mistake of a user who is never interested in a backtrace?
                          (buffer-name)))
            (goto-char beg)
            (beginning-of-line)
@@ -1728,9 +1734,9 @@ Used in suffix."
   "Modal controls for focus windows."
   :interactive nil)
 
-(provide 'moc)
-;;; moc.el ends here
-
 ;; Local Variables:
 ;; outline-regexp: ";; \\(*+\\)"
 ;; End:
+
+(provide 'moc)
+;;; moc.el ends here

[-- Attachment #3: Type: text/plain, Size: 194 bytes --]


Otherwise, an .elpaignore file would be nice again.

I see you have a NEWS.org file that I presume you want to use, but what
about the manual?  Should we use the .texi file or build from .org?