Duck syntax

On Tue, 2014-10-14 at 07:39 -0500, Jim Campbell wrote:
> Hi Shaun,
> 
> I know I've been quiet on this matter, but I have been thinking about
> it. Thank you for your initial work on this. I have two main sets of
> comments - first just looking at design goals, and then discussing a bit
> of the syntax.
> 
> As I've reviewed your initial comments and samples, I wanted to make
> sure that I understood a few of your initial design goals. 
> 
> = Some Notes
> 
> == Inspired by Mallard but not Mallard
> The main thing is that, although I can see some syntactical similarities
> between Duck and Mallard, it doesn't appear as though Duck has Mallard
> as its primary output format. Is that right? That is, it looks like the
> syntax is inspired by Mallard, but it doesn't look like you're expecting
> that the flow would go from Duck > Mallard XML > $output_format.

Actually, my primary use case is for it to go straight to Mallard XML,
and to use all the XML-based tools that currently exist. I think you
could do something similar for DocBook or DITA, but that's not my goal.
My goal is a more palatable syntax for Mallard that can take advantage
of Mallard's linking, metadata, and organizational features.

> == Designed to Solve Problems
> Because you are cool, I assume that you're looking to use this both
> within GNOME and eventually outside of GNOME. I mention that because
> although we use Mallard extensively within GNOME, it hasn't seen much
> uptake outside of GNOME (yet?? there is still hope . . .). I like
> Mallard very much, and like to use it, but I know that there are some
> problems that Mallard doesn't address (partly by design). Nonetheless,
> some people use the stuff that Mallard doesn't intend to cover. So we
> should have in mind what Duck is intended to do.

Yes indeed. There are two environments that I'm primarily looking at.
One is API documentation embedded in code comments. Even I don't think
it's pleasant to write XML inside code comments. The other is setups
where people throw MD or RST files on GitHub and have commit hooks that
auto-publish HTML. Basically as close as you can get to a wiki without
using a wiki.

Mallard has some compelling features. When I talk to people doing this
kind of stuff, I hear them talk about problems they have that I know
they wouldn't have with Mallard. But they don't want to hand-write XML,
so I can't even get to the cool features.

> == Some possible goals
> This is a starting point for discussion. I'm not saying that Duck has to
> do all of this, but we should decide what we want to pursue and not
> pursue.
> - Developers will not yell if they have to use it. reStructuredText,
> asciidoc and Markdown already solve this. DocBook and DITA make most
> developers run away. Mallard doesn't make GNOME developers run away, but
> other developers see XML and run away anyway.

+1

> - Allow for translations. XML rules here. You and I discussed on IRC how
> XML is still an intended output of sorts.

Yes. I don't intend to write a duck2po program. Convert your duck to XML
and use itstool.

> - Allow non-linear, topic-based help (i.e., not designed to be
> explicitly ordered). Mallard solves this, as does DITA and DocBook's
> version 5.1 (still under development)

It is just a shorthand syntax for Mallard, so we get all that goodiness
for free.

> - Allow for linear, book-like help. Docbook, DITA, Python-Sphinx, and
> others address this.

This is something Mallard isn't great at. I think it's worth looking at
(though it's not something that interests me personally a whole lot),
but it's something that should be looked at for Mallard in general.

> - In our brief discussion on IRC you discussed some nesting of syntax
> elements that can't really be handled by other syntaxes. I don't have
> access to the specifics at the moment, though.

* Here is a list item.
  * Here is a list item inside that item.

    And this is another paragraph still inside that list item.

[note]
  Here is a note.

  * And this list is still in the note.

  [screen]
  And so is this screen.

A lot of lightweight syntaxes have a really hard time with this kind of
stuff. In fact, I was just talking to a tech writer over the weekend who
mentioned this as something that kept biting her in Markdown.

> - Content re-use. DITA and the DocBook 5.1 testing candidate handle
> this. Python-Sphinx handles this to an extent.

Mallard's content re-use story is decent. Not great, but decent. There
are a number of things I'd like to work on to address this. First among
them is some sort of manifest/map/assembly file that specifies which
pages to grab from where. Right now, you just have to mv/cp/ln the files
you want into the right directory. Other things that would make content
re-use easier are link pools and a more flexible versioning system for
page status.

> - Output formats. PDF, ePub, and HTML come to mind initially.

Our PDF export story ain't great.

> - Other possible design goals. Please mention other things that this
> could *possibly* do. We can discuss and narrow-down a list of particular
> design goals after we get at what's important.

For me, the most important design goal is that people find it fairly
pleasant to write. We already have some really great features. Most of
our other opportunity areas we can address with extensions or new core
features. The point is to get people past the syntax.

Having played with it for a while, I'm fond of the header syntax and the
block syntax. I like the @info tags better than the :info: tags that I
first proposed. I like having a list-based table syntax, because tables
are a pain. I'm not entirely sold that &inline() is a good syntax. I'd
like feedback. Bear in mind that the inline syntax is the one place
where duck is still requiring quite a bit more typing than MD or RST,
because it's still using the semantic tags.

--
Shaun