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

From: John Wiegley <[email-masked]>
Date: Mon, 19 Mar 2018 17:43:07 -0700

>>>>> "EZ" == Eli Zaretskii <[email-masked]> writes:

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

It refers to this:

group one
group one
group one

group two
group two

That is, groups of lines separated by at least one blank line.

>  . 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.

This refers to regexp groups. So if the align regexp were:

    \( +\)=

Then regexp group 1 is the text that align should feel free to delete, or fill
with spaces, in order to line up all the equal signs.

>    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.

It just means that the default is to use the first regexp quote in the
matching string.

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

Not sure when I'll have time to do this, but I'll add it to my list.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2