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.