Subject: bug#30139: 25.3; Passing callback to align-region raises an error when using `justify` rule

From: Eli Zaretskii <[email-masked]>
Date: Sat, 24 Feb 2018 12:21:04 +0200

> Date: Wed, 21 Feb 2018 20:30:00 +0200
> From: Eli Zaretskii <[email-masked]>
> Cc: [email-masked]
> 
> > From: Michał Kondraciuk <[email-masked]>
> > Date: Tue, 20 Feb 2018 22:07:10 +0100
> > 
> > is there any news on the status of this bug? Should I just send the 
> > patch to emacs-devel?
> 
> Sorry for the delay, I will look at the patch soon.

John, could you please have a look at this?

Btw, I find the documentation in align.el hard to understand.  It
sounds like a very powerful feature, but I would have difficulties
using it, with the doc strings as my only guidance.  Some examples of
unclear or confusing documentation:

 . align-region-separate has this to describe the 'group' method:

     Each contiguous set of lines where a specific alignment occurs is
     considered a section for that alignment rule.

   What is a "contiguous set of lines"?  Does it mean non-empty lines,
   i.e. that groups are separated by empty lines (that's what the
   example seems to imply)?

 . align-rules-list has this to describe the 'group' attribute:

     [...]  For alignment rules, these are the characters that will be
     deleted/expanded for the purposes of alignment.  The "alignment
     character" is always the first character immediately following
     this parenthesis group.  This attribute may also be a list of
     integers, in which case multiple alignment characters will be
     aligned, with the list of integers identifying the whitespace
     groups which precede them.  The default for this attribute is 1.

   Which "this parenthesis group" is being alluded to here?  Also, it
   leaves unexplained how characters are specified by integers, and
   the meaning of the default value of 1 is thus unclear.

So patches to clarify the documentation in align.el are most welcome.