Duck syntax

Shaun McCance wrote:

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

The use case is indeed local previewing, I think a --watch option
would be fine, the burden was mostly on having to run the converter
script to see how a modification went, and even that was mostly worked
around with a gedit plugin that did the conversion then opened yelp.


> > 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'm with you on this, the syntax is fine at the moment and it's just a
matter or $EDITOR configuration to get it to use spaces when using the
tab key.  (I promised to relay all comments)


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

The exact moment when number of spaces became an issue is when I was
asked how to add attributes to the <page>, e.g.

  = My First Topic
    [type="topic"]
  @link[guide >index]

[type="topic"] has to be two spaces and I couldn't tell for sure
without testing.  Honestly that's not an important matter, I just
didn't have it clear when I was asked if the number of spaces was
relevant ("well, I don't know, try something else? it fails? ok, you
need to have two spaces").


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

Again, just relaying.  I thought about looking at the code and
providing patches for the demands but they were not even strong enough
for me to go that length, and they're coworkers of mine...


I didn't stress enough that the overall impression was really good,
and the comments were just little glitches along the way, nothing
blocking, and for me much easier to keep people interested in the
underlying ideas (topic-oriented documentation, small pages, etc.).


        Fred