Duck syntax

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.
Similarly, is there any intention to go from Duck > DITA XML or DocBook
> $output_format? I'm not saying that you *should* or *shouldn't* go the
Duck > XML > $output_format way - I'm just trying to make sure I
understand where you're coming from.

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

== 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.
- Allow for translations. XML rules here. You and I discussed on IRC how
XML is still an intended output of sorts.
- 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)
- Allow for linear, book-like help. Docbook, DITA, Python-Sphinx, and
others address this.
- 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.
- Content re-use. DITA and the DocBook 5.1 testing candidate handle
this. Python-Sphinx handles this to an extent.
- Output formats. PDF, ePub, and HTML come to mind initially.
- 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.

Although it's a bit orthogonal to just introducing the syntax, I'd
probably also recommend taking a look at both Pelican- and Hugo [1, 2]
(or other) static-site generators in terms of how they do things. For
example, some of how they handle front matter could be useful [3, 4]. At
first pass TOML seems like it would neatly give us what we need with
regards to how we handle much of our front matter [5]. Also, having a
"config" file to set various documentation options (e.g., desired output
formats, documentation theme / css info, etc.) would helpful, too.

This is just a start on things. Thanks very much for taking the time to
work through some initial concepts.

Jim


[1] http://getpelican.com
[2] http://gohugo.io
[3] http://gohugo.io/content/front-matter/
[4] http://docs.getpelican.com/en/3.4.0/content.html#file-metadata
[5] http://npf.io/2014/08/intro-to-toml/

On Wed, Sep 10, 2014, at 04:45 PM, Petr Kovar wrote:
> On Thu, 04 Sep 2014 16:31:39 -0400
> Shaun McCance <shaunm at gnome.org> wrote:
> 
> > On Sat, 2014-08-30 at 00:09 -0400, Shaun McCance wrote:
> > > Then there's info elements. I don't have this fully fleshed out yet, but
> > > I'd like to do something like asciidoc's use of :tagname: lines after
> > > headers. So something like this:
> > > 
> > > :revision:[pkgversion=3.7.1 version=0.2 date=2012-11-16 status=outdated]
> > > :credit:[type=editor]
> > >   :name:(Michael Hill)
> > >   :email:[its:translate=no](mdhillca at gmail.com)
> > 
> > After manually converting lots of pages, I've decided I really don't
> > like this. The colon before and after is tedious to write, and it just
> > doesn't look natural. Instead, I propose an @ notation:
> > 
> > @revision[pkgversion=3.7.1 version=0.2 date=2012-11-16 status=outdated]
> > @credit[type=editor]
> >   @name Michael Hill
> >   @email[its:translate=no] mdhillca at gmail.com
> 
> Yeah, I agree this looks simpler... and better.
>  
> > An @ tag can optionally have an attribute list inside [], just like
> > inline tags. When you use an @ tag, one of four things happens:
> > 
> > 1. It's empty because the next non-blank line is either another @ tag or
> > the start of the normal text.
> > 
> > 2. It has other @ tags as children, which must be indented.
> > 
> > 3. It has block content as children, which must be indented. (Note that
> > this is different from block children, which can skip the indent if
> > there's only one block child.)
> > 
> > 4. It has inline content as children, which must start on the same line,
> > and must be indented if it takes multiple lines.
> > 
> > Example of (1) is the @revision tag above. Example of (2) is the @credit
> > tag above. Examples of (3) are the @name and @email tags. Exmple of (4)
> > is the @license tag:
> > 
> > @license
> >   This work is licensed under CC-BY-SA 3.0.
> > 
> >   And here's another paragraph, just for fun.
> > 
> > This means that a @desc must always start on the same line. This is a
> > bit unfortunate, because this is rather pleasant to write:
> > 
> > @desc
> >   Here is a long description that needs two lines to be readable,
> >   And it just felt better to start it on the next line.
> > 
> > Instead, you have to do this:
> > 
> > @desc This is a long description that needs two lines to be readable,
> >   and we had to start it on the same line.
> > 
> > I fear the distinction between block and inline won't stick in people's
> > heads, and they'll accidentally do the wrong thing.
> 
> Agreed.
> 
> > We could special
> > case some elements.
> 
> +1
> 
> > But there needs to be a reliable default behavior
> > for extension elements.
> > 
> > I do have other ideas for special casing. For example, we know that
> > @credit takes info children (@ tags). So if it gets inline content, we
> > can do something special. This is pleasant to write:
> > 
> > @credit Shaun McCance <shaunm at gnome.org>
> > 
> > Not sure about special casing. Need to balance syntactic sugar with
> > having a predictable and reliable syntax.
> 
> FWIW, I'm for sugar. :) But I understand this can get tricky.
> 
> Cheers,
> pk
> _______________________________________________
> mallard-list mailing list
> mallard-list at projectmallard.org
> http://projectmallard.org/mailman/listinfo/mallard-list