Duck syntax

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.

An explicit design goal is to not have too many syntactical constructs.
One of the nice thins about XML is that you know that < and & are the
only things that are syntactically significant in the middle of text.
Drives me nuts when I have to remember which non-alphanums will turn my
text flashing magenta, and how to escape that particular thing. It also
drives me nuts when I have to escape my own last name.

Another design goal is to not arbitrarily limit what you can put inside
other things. Mallard is perfectly fine with inline markup inside code
blocks, or list items inside table cells, or whatever. These are things
that are often impossible in lightweight languages.

Like other lightweight languages (markdown, asciidoc, rst, wikis),
paragraphs are implicit from an empty line. Note that there are only
three blocks in Mallard that take inline text: para, code, and screen.
That'll be relevant later. But when you're just writing paragraphs, you
make new ones the same way I do in this email.

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.

* This is a paragraph inside the list item.
  This is still the same paragraph.

  This is a new paragraph because of the empty line, but it's
  still inside the same list item because of the indentation.

Page and section headers start with a leading "= ", "== ", "=== ", etc.
I'm not going with the style of "underlining" with "===", "---", "~~~",
etc for two reasons: One, I dislike having to look at the next line to
parse the line I'm on. Two, I can never remember which fancy character
indicates which level.

Any type of block other than a paragraph uses an opening tag with square
brackets, like so:

[note]
This is a note.

This is reminiscent of section groupings in config files. I played with
a few different syntaxes, manually converting bunches of pages, and I
really liked this one. Note that, unless it's [code] or [screen], you
implicitly get a paragraph, unless the next line is another opening
block tag.

If you don't indent, as in the example above, you just get the following
paragraph (or tagged block). If you want a multi-paragraph block, use
indentation, like so:

[note]
  This is a note.

  This is a new paragraph in the note.

  * What the heck,
    now we have a bulleted list item in the note too.

Sometimes those tags need attributes. We can add them the same way we do
for opening XML tags:

[note style="tip"]

Except let's go ahead and not require quotes if there's no space.

[note style=tip]

Except while we're at it, let's go ahead and introduce a shortcut for
style hints, because they get used a bunch.

[note.tip]

And for IDs (pending block IDs making it into Mallard 1.1):

[note#thisnoteid]

If you need a block title, it goes on the line after the block opening
with a leading ". ".

[note]
. The note title
This is the note

This is stolen from asciidoc. I like stealing pieces of syntax.

For terms lists, list items themselves can have titles. Do these with a
leading "- ".

[terms]
- term 1 title
* term 1 description
- term 2 title
* term 2 description

Inline markup looks like &gui(Button Name). You can escape an ampersand
with &&. You can escape [ with &[ if you need to use [ at the beginning
of a line. And you can do XML entities like &aacute; and &#x00E1;. But
the character sequence "& " is literally ampersand, space, so you don't
have to escape it for normal prose use. Yes, this means escaping for C
and other language code blocks. I'm open to something like CDATA.

If you want to do attributes on inlines, put them in [] between the
element name and the content in parens. &gui[style="button"](OK). Same
shortcuts for style hints. &gui[.button](OK). And let's add a shortcut
for linking, so &gui[xref=ok-buttons](OK) is &gui[>ok-buttons](OK).

(I'm open to suggestions on changing any of these special characters.
Some I've grown rather fond of in playing around with different ideas.
Some are just what happen to be in some of my test files right now. Not
sure ">" for "xref=" is my favorite, TBH.)

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)

This needs to be fleshed out more. One problem I came across when trying
to convert non-trivial pages was that, in info elements, we don't know
quite as easily when we're moving into inline text. What happens when
arbitrarily complex block and inline elements make their way into info?
It can happen inside license elements. It's a staple of my long-dormant
experimental glossary extension.

Extensions get tricky, because there's no telling when to implicitly
insert a paragraph. For core Mallard, we know not to for code and screen
blocks. But look at Mallard+TTML. You should be using the tt:p elements,
and those get mixed content. Maybe once you leave the core namespace,
you don't get paragraphs for free, but have to explicitly mark them with
an opening tag [para]? Not sure yet.

For your viewing pleasure, I've attached a duck syntax conversion of a
(possibly old and outdated) gnome-user-docs page.
-------------- next part --------------
= Open applications for devices or discs
  [style=task]
:link:[type=guide >media#photos]
:link:[type=guide >media#videos]
:link:[type=guide >media#music]
:link:[type=guide >files#removable]
:revision:[pkgversion=3.7.1 version=0.2 date=2012-11-16 status=outdated]
:revision:[pkgversion=3.9.92 date=2013-10-04 status=review]
:credit:[type=author]
  :name:(GNOME Documentation Project)
  :email:[its:translate=no](gnome-doc-list at gnome.org)
:credit:[type=editor]
  :name:(Michael Hill)
  :email:[its:translate=no](mdhillca at gmail.com)
:credit:[type=editor]
  :name:(Shobha Tyagi)
  :email:[its:translate=no](tyagishobha at gmail.com)
:xi:include:[href="legal.xml"]
:desc:(Automatically run applications for CDs and DVDs, cameras,
audio players, and other devices and media.)

You can have an application automatically start when you plug in a device
or insert a disc or media card. For example, you might want your photo
organizer to start when you plug in a digital camera. You can also turn this
off, so that nothing happens when you plug something in.

To decide which applications should start when you plug in various
devices:

[steps]
* Open the &gui[>shell-terminology](Activities) overview and
  start typing &gui(Details).

* Click on &gui(Details) to open the panel.

* Click &gui(Removable Media).

* Find your desired device or media type, and then choose an application
  or action for that media type. See below for a description of the different
  types of devices and media.

  Instead of starting an application, you can also set it so that the
  device will be shown in the file manager. When that happens, you will be
  asked what to do, or nothing will happen automatically.

* If you don't see the device or media type that you want to change in the
  list (such as Blu-ray discs or E-book readers), click &gui(Other Media)
  to see a more detailed list of devices. Select the type of device or media
  from the &gui(Type) drop-down and the application or action from the
  &gui(Action) drop-down.

  [note.tip]
    If you don't want any applications to be opened automatically, whatever
    you plug in, select &gui(Never prompt or start programs on media
    insertion) at the bottom of the Removable Media window.

== Types of devices and media
   [#files-types-of-devices]

[terms]
- Audio discs
* Choose your favorite music application or CD audio extractor to handle
  audio CDs. If you use audio DVDs (DVD-A), select how to open them under
  &gui(Other Media). If you open an audio disc with the file manager,
  the tracks will appear as WAV files that you can play in any audio player
  application.

- Video discs
* Choose your favorite video application to handle video DVDs. Use the
  &gui(Other Media) button to set an application for Blu-ray, HD DVD,
  video CD (VCD), and super video CD (SVCD). If DVDs or other video discs
  do not work correctly when you insert them, see :link:[video-dvd].

- Blank discs
* Use the &gui(Other Media) button to select a disc-writing
  application for blank CDs, blank DVDs, blank Blu-ray discs, and blank HD
  DVDs.

- Cameras and photos
* Use the &gui(Photos) drop-down to choose a photo-management
  application to run when you plug in your digital camera, or when you insert
  a media card from a camera, such as a CF, SD, MMC, or MS card. You can also
  simply browse your photos using the file manager.

  Under &gui(Other Media), you can select an application to open Kodak
  picture CDs, such as those you might have made in a store. These are regular
  data CDs with JPEG images in a folder called &file(PICTURES).

- Music players
* Choose an application to manage the music library on your portable music
  player, or manage the files yourself using the file manager.

- E-book readers
* Use the &gui(Other Media) button to choose an application to
  manage the books on your e-book reader, or manage the files yourself
  using the file manager.

- Software
  Some discs and removable media contain software that is supposed to be
  run automatically when the media is inserted. Use the &gui(Software)
  option to control what to do when media with autorun software is
  inserted. You will always be prompted for a confirmation before software
  is run.

  [note.warning]
    Never run software from media you don't trust.