Require multiple sections in all simplates

[chadwhitacre]

Right now this is an error as a negotiated simplate (foo.spt):

Greetings, program!

Why? Can it not be? We should render and serve that as text/html (cf. #296).

[chadwhitacre]

Per May 2014 call, we're punting this until after we have more experience writing editor plugins.

[pjz]

I'm looking at refactoring simplates and this is at issue there.

Current state of things:

if is_bound (eg. file extension indicates a media type): 
    min_pages, max_pages = (1,4)
else: 
    min_pages, max_pages = (3,None)

Possibilty space:

OTP = 'one time python', PPP = 'per-pagehit-python'

Given a .spt:
1 page: PPP(per-page python)
2 pages: either OTP + PPP, or PPP + template
3 pages: either OTP + PPP + template or PPP + 2x template

Basically it seems to boil down to OTP{0,1}PPP{1}template{0,} which is a bit problematic to parse since there's no indicator of the PPP section or of the templates (b/c templates can be default media type using the default renderer so nothing needs to be specified in the header).

Ideas:

1. enforce regularity: (this is what we currently do): all pages MUST include OTP and PPP sections. Currently we also require a template, but we could just default to a 204 if they forget to raise something.
2. add more keywords/additional parsing hints. Just requiring a #python in the header of python sections would make it possible to disambiguate.

I'm currently in favor of option 1.

[Changaco]

+1 for option 1, my text editor can't highlight single-page simplates properly.

[pjz]

Right now there's the weird 'is_bound' exception to the parsing method - should we ditch that? How many pages on gratipay would that break?

[chadwhitacre]

1 page: PPP(per-page python)
2 pages: either OTP + PPP, or PPP + template
3 pages: either OTP + PPP + template or PPP + 2x template

The previous behavior was:

1 page: template
2 pages: PPP + template
3 pages: OTP + PPP + template

The design principle was (and is on this ticket) "progressive enhancement of the developer experience," so you could have an Aspen learning experience like this:

1. Make an index.spt with Greetings, program! and then python -m aspen and hit http://localhost:8080/—Yay!
2. Now change it to program = request.qs['program']\n[---]\nGreetings, {program}! and hit http://localhost:8080/?program=Python—Yay!
3. Now change it to import random\n[---]\nprogram = request.qs['program']\nextra_excitement = random.choice(range(10)) * '!'[---]\nGreetings, {program}!{extra_excitement}—Yay!

It's just a bit clunkier if step one is:

1. Make an index.spt with [---]\n[---]\nGreetings, program! and then python -m aspen and hit http://localhost:8080/—Yay!

The current status quo was for the sake of making editor plugins easier to write, which it sounds like may indeed be the case. I can live with that tradeoff.

[pjz]

Okay, to answer my own question, there are no pages on gratipay.com with less than three sections. (Actaully, they all have 3 sections, with 3 exceptions that have 4 sections). So going with option 1 and ditching the weird is_bound thing wouldn't have much effect.

[chadwhitacre]

there are no pages on gratipay.com with less than three sections.

How could there be? Requiring at least three sections is our current behavior.

ditching the weird is_bound thing wouldn't have much effect

is_bound is unrelated to the hard requirement on the first two (python) sections.

[pjz]

there are no pages on gratipay.com with less than three sections.

How could there be? Requiring at least three sections is our current behavior.

It's only our current behavior if NOT is_bound. See https://github.com/gratipay/aspen-python/blob/master/aspen/resources/simplate.py#L44 which I quoted at the top of this thread, which says (essentially):

if is_bound: 
  min_pages, max_pages = (1,4)
else: 
  min_pages, max_pages = (3,None)

Anyway, the fact that even you think it's okay to just require those top two sections means to me that it should be okay to actually do so and drop the conditional on is_bound.

[chadwhitacre]

Ah, I see now, sorry: we still implement the relaxed behavior for foo.html.spt. Yeah, I'm fine making that consistent regardless of is_bound.

!m @pjz

[pjz]

I like the relaxed behavior, but we need some way to know, when there are more than two sections, whether there are one or two python sections. Or is this not worth solving?

[chadwhitacre]

I think we should just go with requiring both initial Python sections, because it makes the semantics so much simpler.

[pjz]

Done in #481

[Changaco]

This was reverted by #516 and #517, reopening for discussion. Requiring 3 pages was simple and allowed straightforward syntax highlighting, why change? aspen.io could have been fixed easily by adding the required page separators.

[chadwhitacre]

allowed straightforward syntax highlighting

Ah, you're right! That's why we decided to forego the DWIM magic.

[pjz]

'Straightforward syntax hilighting' will still work if you have 3+ sections. The DWIM code is 1) convenient and 2) simplifies the code, actually, because from a simplate point of view it's now impossible to have an invalid simplate since it can now have any number of sections, which is a big win, IMO - it makes simplates a little more transparent.

[chadwhitacre]

'Straightforward syntax hilighting' will still work if you have 3+ sections.

@pjz Why is that true now but wasn't true two months ago?

[pjz]

That comment says 'single page' - and I said '3+ sections'. sections == pages. Still true.

[Changaco]

The question here is: should "at least 3 sections" be a rule enforced by aspen, or only a recommendation?

[chadwhitacre]

@pjz and I talked about this on the October, 2015 call (#507). I don't think we have enough experience writing editor plugins to make a good decision about this one way or another. As we're now suggesting, an individual or project can adopt an "at least three sections" convention. I think we should let this stand and revisit if/when we have more experience.

[Changaco]

Closing in favor of AspenWeb/simplates.org#1.