Duck syntax

On Thu, 2014-12-04 at 18:14 +0100, Frederic Peters wrote:
> Hi Shaun,
> 
> Shaun McCance wrote:
> > Some of you know I've toyed around with a non-XML syntax for Mallard.
> > I'm going to start tossing out what's been in my head in the hopes that
> > others can follow along.
> 
> It's been some time but I have finally got the opportunity to present
> this at work, the public was two person with familiarity to wiki
> syntaxes and some knowledge of mallard (they wrote pages, mostly by
> copying and filling templates).

Thanks.

> The most important thing will be to get duck support into yelp, for
> now I explained how to use the ducktype converter.

I'd actually prefer to avoid doing this. What's the use-case? Is it for
installed help, or to use yelp as a local preview? For installed help, I
think if the build tools can automatically handle the conversation, it
shouldn't matter.

For local preview, I get it. It's nice to write mallard and have yelp
open to see your changes each time you save. What I'd thought about
doing is adding a --watch option to the converter to make it rebuild
page files each time duck files change. Then yelp would pick up the
changes in the page files. Would that be sufficient?

> > Unlike many other languages, indentation matters. A lot. Similarly to
> > Python, indentation indicates where you are. So if I start a bulleted
> > list using a leading "* ", then I'm inside that list item as long as I
> > maintain that indentation.
> 
> About indentation the complaints were that tabulations couldn't be
> used, and that the number of required spaces was not always evident
> (this was seriously aggravated by the use of a non-monospace font).

Hum, OK. I guess I assumed everybody used a monospace font when editing
these kinds of files. Without using indentation, the only ways to get
arbitrary testing is with some sort of braces or some sort of closing
tags. And then, why not just write XML?

I kind of took a page out of the Python playbook here. Python does allow
tabs instead of spaces (or comingled even), though PEP8 strongly advises
you not to use them. We could do that. Not sure I want to, but we could.

Regarding the number of spaces, You can use however many you like to
start a block, and that's the number you need to stay in the block. You
can even use more in subsequent lines, but never less. The one caveat
here is that the shorthand syntaxes like "* " for list items implicitly
start you at a two-space indent. So if you like a one-space indent,
you're going to have a hard time. If you like four spaces, you can do
that. I like two spaces, personally.

> > [note style="tip"]
> > 
> > Except let's go ahead and not require quotes if there's no space.
> > 
> > [note style=tip]
> 
> The current parser doesn't allow for spaces around the equal sign,
> this caused a few problems with varying behaviours,
>   [note style = "tip"] → SyntaxError
>   [note style=tip] → <note type="tip">

Right, I was wondering if anybody was going to complain about this. XML
allows space around the =, whereas ducktype currently does not. I never
see anybody put spaces around = in XML, so I figured it would be a
non-issue.

The reason I did this is that ducktype allows bare words. So when the
parser sees this:

[note style]

It turns it into this:

<note type="style">

Without allowing spaces around =, the parser immediately knows when it
hits a space that it has a bare word. With spaces around =, it has to
keep it in a limbo state until the next token. Bear in mind that spaces
include newlines, and the parser parses line at a time, so that means
extra state.

Absolutely not impossible to allow this. It just requires extra work,
and I'm lazy in the absence of a strong demand.

> (in the example that was given back then)
> > :xi:include:[href="legal.xml"]
>
> I forgotten about this (and didn't try it) but there was a request for
> a way to use includes (that's probably a comment relevant to your mail
> about directives).

With the current attribute syntax, it's:

@xi:include[href="legal.xml"]

Except you have to declare the xi prefix, which requires directives,
which aren't done yet. This isn't even a ducktype feature. It's just
leveraging XInclude in the output XML. Maybe it's worth adding an
inclusion mechanism that happens at parse time. Maybe not.

Thanks a lot for test-driving this on people. Feedback from actual
potential users is valuable.

--
Shaun