Hi John,

I think side-marking is the right choice for divs --- though, the character used to begin each line should be tall enough to provide some visual sense of a vertical marker for the block, but not take up too much space (so, for example, "%" would be out). Exclamation points make it look like yelling, or a warning or important notice. Periods/dots are too small. Colons are already used for definition lists...

Neither the surround-marking nor indented blocks are desirable for divs, IMO. Surround-marking makes too many horizontal lines across the document (we have enough already, what with hr's, tables, and headings). Indented blocks say "code", or else next paragraph of a bullet-list-item. And bullet-syntax is already used nicely with 3 kinds of lists and most definitely says "this is some kind of list" to the reader --- not a div.

As for spans, the only thing that bothers me about [this]{.foo} is that square brackets are "linky" in markdown. The reader and writer of the text associates square brackets with links.

It would be really nice for consistency if we could use the same character for spans as for divs...

So:

If you were willing to make a small breaking change, I think it would be very symmetrical to use |this|{.foo} for spans, and

| {.foo}
| this for divs

and then (the breaking change), change Pandoc to use some other character for line blocks, for example:

; line block
; now like
; this

-- John




On Wed, Aug 14, 2013 at 1:46 PM, John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
I've finally added a generic Div and Span element to pandoc, to which
attributes may be added.  Most of the writers just treat these
transparently, printing their contents (though in HTML span and div
containers are used).

I'd like to introduce a markdown syntax for these.  Together with the
new scripting capabilities, this will make pandoc markdown very
easy to customize and extend.  The question is what syntax to use.


1. SPANS

For inline spans, I think the best approach is to use the bracket
containers currently used for link labels and image alt text:

    [this is a *span*, which can contain [links](/url) and
    other inline elements]{#id .class key="value"}

The attribute syntax would be the same as currently in code blocks
and headers.  An attribute block would be required, but could be
empty:

    [plain span]{}


2. DIVS

For block containers (div), I have a number of ideas, and I'm not sure
what is best.  So I'd be curious to get feedback, though I don't expect
convergence.

There are three general approaches:  side-marking (as with markdown block
quotes), surround-marking (as with fenced code blocks), and indented
block (as with lists and footnotes).


2.1 SIDE-MARKING

The simplest side-marking approach would be just to use the current
blockquote syntax.  A block quote beginning with attributes
would be marked up as a generic div rather than a block quote:

    Blah blah blah.

    > {.TIP}
    >
    > # Don't use closed-source tools!
    >
    > You can't change them and you can't count on them
    > being around in the future.

    More regular text.

One advantage of this approach would be that it would degrade gracefully
in standard markdown parsers that don't support this syntax extension.
The "tip" above would render as a block quote with some funny stuff
at the beginning.  Existing syntax highlighting would also work.

An alternative would be to introduce a side-marking syntax that works
like block quotes, but with a different symbol.  The best choices
choices would be period (.) and exclamation mark (!).  (None of these
would occur at the beginning of the line, followed by a space, in
regular text.  And none would be confused with other markdown syntax.)

    Blah blah blah.

    . {.TIP}
    .
    . # Don't use closed-source tools!
    .
    . You can't change them and you can't count on them
    . being around in the future.

    More regular text.  Blah blah blah.

    ! {.TIP}
    !
    ! # Don't use closed-source tools!
    !
    ! You can't change them and you can't count on them
    ! being around in the future.

    More regular text.

I think I like the exclamation mark version best.


2.2 SURROUND-MARKING

The second approach is a surround-marking approach.  It would work like
fenced code blocks, with nesting handled by the rule that a block is
closed by a line at least as long as the one that started the block.
There are many possibilities here.

    We could use underline:

    __________________________________________ {.TIP}
    # Don't use closed-source tools!

    You can't change them and you can't count on them
    being around in the future.
    __________________________________________________

    The low position on the line looks a bit bad, though.
    Or colons:

    :::::::::::::::::::::::::::::::::::::::::: {.TIP}
    # Don't use closed-source tools!

    You can't change them and you can't count on them
    being around in the future.
    ::::::::::::::::::::::::::::::::::::::::::::::::::

    Or periods:

    .......................................... {.TIP}
    # Don't use closed-source tools.

    You can't change them and you can't count on them
    being around in the future.
    ..................................................

    In addition, the attribute could be allowed to occur
    inside the block:

    _________________________________________________
    {.TIP}
    # Don't use closed-source tools!

    You can't change them and you can't count on them
    being around in the future.
    __________________________________________________

    And maybe we'd want to allow a bare word to count
    as a class attribute, as with github-style fenced
    code blocks:

    .......................................... TIP
    # Don't use closed-source tools.

    You can't change them and you can't count on them
    being around in the future.
    ..................................................

    Perhaps it should even be allowed in the middle:

    .......................................... TIP ...
    # Don't use closed-source tools.

    You can't change them and you can't count on them
    being around in the future.
    ..................................................

I think a case can be made that the side-marking approach is
more markdownish, since it just follows an existing markdown
block-container (block quotes).  Delimited blocks make sense
for code, since you want it to be easy to cut and paste, but
less so for regular text.  But arguably the surround-marking
approach is easier to read and write.

One could also allow several different symbols to be used
(say, period, colon, exclamation mark, underline), and store
the symbol used in the attributes.  So the last example above
would be parsed as a Div with class "TIP" and symbol=".".
This would allow scripts to treat differently-delimited blocks
differently, so that authors could avoid using explicit
attributes to distinguish (say) sidebars from tips.  The same
goes for the side-marking proposal.


2.3 INDENTED BLOCKS

One idea (which would also degrade gracefully) would be to overload
existing bullet list syntax.  A bullet list item starting with an
attribute block would be treated as a div.

    Blah blah blah.

    *   {.TIP}

        # Don't use closed-source tools!

        You can't change them and you can't count on them
        being around in the future.

    More regular text.  Blah blah blah.

The nice thing about this is that it would display as a regular
bullet list item (which is a block container after all) in
"regular" markdown processors, which wouldn't look too bad
(whereas the side-marking and surround approaches with special
symbols would just be a mess).

Alternatively, one could overload definition list syntax:

    Blah blah blah.

    {.TIP}
    :   # Don't use closed-source tools!

        You can't change them and you can't count on them
        being around in the future.

    More regular text.  Blah blah blah.

Or one could avoid confusion with existing syntax by using a
special marker:

    Blah blah blah.

    !   {.TIP}

        # Don't use closed-source tools!

        You can't change them and you can't count on them
        being around in the future.

    More regular text.  Blah blah blah.

Or one could require no marker, letting the attributes itself
do the work:

    Blah blah blah.

    {.TIP}

        # Don't use closed-source tools!

        You can't change them and you can't count on them
        being around in the future.

    More regular text.  Blah blah blah.

These last two options would not degrade as well.

I'm eager to hear thoughts about these proposals.

John

--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org.
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/20130814174642.GA28736%40protagoras.phil.berkeley.edu.
For more options, visit https://groups.google.com/groups/opt_out.



--
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To post to this group, send email to pandoc-discuss-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CAO9PwMXmsEJhW_pKpb_9pQqRHxM1RHhhm2Widgdqyc1OvU4bnQ%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.