About #2276: Allow section references with different delimiters

[Edward K. Ream]

I have just edited the first comment of #2276.  This issue suggests a potentially dangerous addition to Leo. I think it best to repost the comment here, so more people will be likely to see it.

===== Start first comment of #2276 =====

Section delimiters ``<<`` and ``>>`` should be configurable.

EKR: there must not be any setting associated with this issue. Such a setting would be way too dangerous.

The design of the @section-delims directive

The `@section-delims` directive (the directive, for short) specifies the delimiters to be used in section references. Section definition nodes are not affected.  That is, regardless of this directive, the headlines of section definition nodes *always* have the form

    `<< section name >>`.

Only `@file` nodes may contain this directive. This directive is not valid in `@clean`, `@auto`, etc.

For each external file, this directive must appear:

- only in the body of  the `@file` node itself, not in any descendant node.
- only once in the `@file` node.
- before the first section reference in the `@file` node (or other nodes in the `@file` tree).

The format of the `@section-delims` directive will be:

    @section-delims <opening delim><one or more spaces><closing delim>

Blanks will not be allowed within delims.  Only whitespace will be allowed before the opening delim or after the closing delim.  Correct:

    @section-delims <<<<   >>>>

Wrong. For safety, nothing is allowed after the closing delim:

    @section-delims <!< >!>   # Change the delims

Code level details

The write logic will be changed as follows:

- Leo's write logic will refuse to write any `@file` node containing an erroneous or out-of-place `@section-delims` directive.

- The write logic will use the delims specified by `@section-delims` when *recognizing* section references.

- The write logic will write the `@section-delims` itself as usual.

The read logic will not change in any way!  Indeed:

- fast_at.scan_header sets **delims**, the comments delims used to represent *all* sentinels.

- fast_at.scan_lines doesn't know anything about the format of sections.

Summary

The `@section-delims` directive will specify the form of section references. Section definitions nodes will remain unchanged. This directive will be valid *only* in `@file` nodes, not in `@auto', `@clean`, etc.

Only Leo's write logic needs to change. The FastAtRead class will not change in any way.

Leo's write logic will refuse to write any `@file` node containing an erroneous or out-of-place `@section-delims` directive.

===== End first comment of #2276 =====

That's it.  All comments are welcome.

Please comment here, not in the issue itself.

Edward

[tbp1...@gmail.com]

I'm just wondering if this will fully meet the O.P.'s needs, because there will still be the angle brackets in the sentinals for the headlines.  I'm not saying there should be a way to change them too, I'm only concerned that angle brackets will still be in the @file as written, in case that would cause problems for the original use case.

[Edward K. Ream]

On Mon, Oct 25, 2021 at 8:35 AM tbp1...@gmail.com <tbp1...@gmail.com> wrote:

I'm just wondering if this will fully meet the O.P.'s needs, because there will still be the angle brackets in the sentinals for the headlines.

Headlines won't be a problem because in the external file headlines live in @+node sentinels.

Edward