docutils-develop

[Docutils-develop] Keep/drop emacs variables in documentation sources?

[Guenter M. <mi...@us...>]

Dear Docutils Co-Developers,

our Project Policies state in section `Documentation Conventions`__

  * Add an Emacs "local variables" block in a comment at the end of the
    document. See the end of this document for an example.

__ https://docutils.sourceforge.io/docs/dev/policies.html#documentation-conventions

In praxi, the "local variables" block is preceded by a FORM FEED character::

  
  ..
     Local Variables:
     mode: indented-text
     indent-tabs-mode: nil
     sentence-end-double-space: t
     fill-column: 70
     End:

This clashes with the the "trailing-whitespace" `pre-commit` hook
(cf. https://pre-commit.com).

The hook prevents trailing whitespace from entering the repository files
during a git commit (works fine with a local repo based on `git svn`).

This helps to avoid needless fixes/diffs.
It does, however, also remove the FORM FEED!

So my question is:

* Do we want to keep the emacs variables block?
  Is anyone using emacs?

* If yes, do we need the FORM FEED character
  (it shows as ^L in my text editor).

If no, I would activate the "trailing-whitespace" hook for documentation.

(Otherwise I may have to write a "trailing-whitespace-except-form-feed" hook
some day...)


Regards,

Günter

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[G. B. R. <g.b...@gm...>]

At 2024-04-24T19:06:23-0000, Guenter Milde via Docutils-develop wrote:
> So my question is:
> 
> * Do we want to keep the emacs variables block?
>   Is anyone using emacs?

I tend to use Vim, but occasionally use emacs.

> * If yes, do we need the FORM FEED character
>   (it shows as ^L in my text editor).

As far as I know, this is not necessary.  As I recollect, GNU Emacs
scans backward through the last 3,000 bytes of the file attempting to
match the "Local variables:" pattern; the lack of a form feed character
before that text does not frustrate the search.

Try out the attached file.

Regards,
Branden

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[Guenter M. <mi...@us...>]

Dear Branden,

On 2024-04-24, G. Branden Robinson wrote:
> At 2024-04-24T19:06:23-0000, Guenter Milde via Docutils-develop wrote:
>> So my question is:

>> * Do we want to keep the emacs variables block?
>>   Is anyone using emacs?

> I tend to use Vim, but occasionally use emacs.

>> * If yes, do we need the FORM FEED character
>>   (it shows as ^L in my text editor).

> As far as I know, this is not necessary.  As I recollect, GNU Emacs
> scans backward through the last 3,000 bytes of the file attempting to
> match the "Local variables:" pattern; the lack of a form feed character
> before that text does not frustrate the search.

thanks for checking this out.

AFAIK, the ^L (FORM FEED) is intended to hide the local variables away
(maybe as a marker for some emacs-special functionality or simply by pushing
the following lines out of view).

The FORM FEED is converted to a SPACE prior to parsing as rST by Docutils.
The local variables are invisible in the output because they are in a
comment block.

The Policies mention the comment block but not the FORM FEED 
(rsp. only indirectly via the source serving as example).


If there are no objections, I would sacrifice the FORM FEED 
in favour of a simple commit test for trailing whitespace.


Günter

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[Karl O. P. <ko...@ka...>]

On Fri, 26 Apr 2024 10:56:53 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> Dear Branden,
> 
> On 2024-04-24, G. Branden Robinson wrote:
> > At 2024-04-24T19:06:23-0000, Guenter Milde via Docutils-develop
> > wrote:  
> >> So my question is:  
> 
> >> * Do we want to keep the emacs variables block?
> >>   Is anyone using emacs?  
> 
> > I tend to use Vim, but occasionally use emacs.  
> 
> >> * If yes, do we need the FORM FEED character
> >>   (it shows as ^L in my text editor).  
> 
> > As far as I know, this is not necessary.  As I recollect, GNU Emacs
> > scans backward through the last 3,000 bytes of the file attempting
> > to match the "Local variables:" pattern; the lack of a form feed
> > character before that text does not frustrate the search.  
> 


> AFAIK, the ^L (FORM FEED) is intended to hide the local variables away
> (maybe as a marker for some emacs-special functionality or simply by
> pushing the following lines out of view).

> If there are no objections, I would sacrifice the FORM FEED 
> in favour of a simple commit test for trailing whitespace.

I am no expert; note the emacs docs say:

The start of
the local variables list should be no more than 3000 characters from the
end of the file, and must be on the last page if the file is divided
into pages.
<snip>
   If some unrelated text might look to Emacs as a local variables list,
you can countermand that by inserting a form-feed character (a page
delimiter, see Pages) after that text.  Emacs only looks for
file-local variables in the last page of a file, after the last page
delimiter.

So my guess is that the line feed is a "guard" that allows RST
files to end in something that looks to emacs like a local variable
list, but is intended to be document text.  This does sound like
it could be useful in special edge cases.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[Guenter M. <mi...@us...>]

On 2024-04-26, Karl O. Pinc wrote on Fri, 26 Apr 2024
> Guenter Milde via <doc...@li...> wrote:
>> On 2024-04-24, G. Branden Robinson wrote:
>> > At 2024-04-24T19:06:23-0000, Guenter Milde wrote:

>> >> So my question is:

>> >> * Do we want to keep the emacs variables block?

...

>> If there are no objections, I would sacrifice the FORM FEED
>> in favour of a simple commit test for trailing whitespace.

> I am no expert; note the emacs docs say:

...

><snip>
>    If some unrelated text might look to Emacs as a local variables list,
> you can countermand that by inserting a form-feed character (a page
> delimiter, see Pages) after that text.  Emacs only looks for
> file-local variables in the last page of a file, after the last page
> delimiter.

> So my guess is that the line feed is a "guard" that allows RST
> files to end in something that looks to emacs like a local variable
> list, but is intended to be document text.  This does sound like
> it could be useful in special edge cases.

Sounds reasonable. 

How about this change then:

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 6798300a3..ca66796b4 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -5147,8 +5147,8 @@ models of the following elements: `\<abbreviation>`_,
 .. _table of compatible image formats: rst/directives.html#image-formats
 
 
-
-..
+.. Emacs settings
+
    Local Variables:
    mode: indented-text
    indent-tabs-mode: nil


Regards,

Günter

Re: [Docutils-develop] Keep/drop emacs variables in documentation sources?

[Karl O. P. <ko...@ka...>]

On Sat, 27 Apr 2024 11:04:09 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> On 2024-04-26, Karl O. Pinc wrote on Fri, 26 Apr 2024
> > Guenter Milde via <doc...@li...> wrote:  
> >> On 2024-04-24, G. Branden Robinson wrote:  
> >> > At 2024-04-24T19:06:23-0000, Guenter Milde wrote:  

> >> If there are no objections, I would sacrifice the FORM FEED
> >> in favour of a simple commit test for trailing whitespace.

> ><snip>
> >    If some unrelated text might look to Emacs as a local variables
> > list, you can countermand that by inserting a form-feed character
> > (a page delimiter, see Pages) after that text.  Emacs only looks for
> > file-local variables in the last page of a file, after the last page
> > delimiter.  
> 
> > So my guess is that the line feed is a "guard" that allows RST
> > files to end in something that looks to emacs like a local variable
> > list, but is intended to be document text.  This does sound like
> > it could be useful in special edge cases.  

> How about this change then:
> 
> diff --git a/docutils/docs/ref/doctree.txt
> b/docutils/docs/ref/doctree.txt index 6798300a3..ca66796b4 100644
> --- a/docutils/docs/ref/doctree.txt
> +++ b/docutils/docs/ref/doctree.txt
> @@ -5147,8 +5147,8 @@ models of the following elements:
> `\<abbreviation>`_, .. _table of compatible image formats:
> rst/directives.html#image-formats 
>  
> -
> -..
> +.. Emacs settings
> +
>     Local Variables:
>     mode: indented-text
>     indent-tabs-mode: nil

Makes sense to me.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein