syntax for generic spans and divs

syntax for generic spans and divs

[John MacFarlane]

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

Re: syntax for generic spans and divs

[Joseph Reagle]

On 08/14/2013 01:46 PM, John MacFarlane 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).

That's awesome and exciting! I don't have any thoughts on syntax other 
than to ask is there anything worth borrowing from elsewhere? (I don't 
think so, the closest would probably be rst's container synatx....)

Re: syntax for generic spans and divs

[Daniel Staal]

--As of August 14, 2013 10:46:42 AM -0700, John MacFarlane is alleged to 
have said:

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

--As for the rest, it is mine.

I like the blockquote extension - it makes sense to me.  I note the 
surround-marking with underlines ends up being an extension of the 
horizontal rule syntax (which already allows underlines) - Which I also 
think makes sense, in a way.  ('A horizontal rule starts a new div, which 
can have an attribute added to it.')

If I have to pick one, I'd pick blockquote.  It's fairly easy to read, and 
a decent text editor can mark up large stretches of text with it fairly 
quickly.  (It also allows 'divs in divs', at least in theory, which might 
be useful.)

Daniel T. Staal

---------------------------------------------------------------
This email copyright the author.  Unless otherwise noted, you
are expressly allowed to retransmit, quote, or otherwise use
the contents for non-commercial purposes.  This copyright will
expire 5 years after the author's death, or in 30 years,
whichever is longer, unless such a period is in excess of
local copyright law.
---------------------------------------------------------------

Re: syntax for generic spans and divs

[Joseph Reagle]

On 08/14/2013 02:31 PM, Daniel Staal wrote:
> If I have to pick one, I'd pick blockquote.  It's fairly easy to read,
> and a decent text editor can mark up large stretches of text with it
> fairly quickly.  (It also allows 'divs in divs', at least in theory,
> which might be useful.)

As most editors are not quite decent, I would hesitate to trust many of 
them with wrapping the lines nicely, particularly in nested cases.

Re: syntax for generic spans and divs

[Shahbaz Youssefi]

[-- Attachment #1: Type: text/plain, Size: 2974 bytes --]

About divs: the block quote looks pretty nice. Doing it with ! has the
benefit of not getting mistaken with the normal quote.

About spans: I'm going to actually argue against it. Markdown was made so
the plain text would be readable and with minimal markup (hence the name).
Adding span means a lot of [extra]{#id .class key="value"}
[unnecessary]{#id .class key="value"} [clotter]{#id .class key="value"}. I
don't know what is pandoc's strategy. If it wants to become another LaTeX,
then adding all these formatting may be fine. However, if it wants to stay
along the same idea as markdown, probably it's best to not go overboard
with such features.

As an alternative, I'd like to suggest some improvements that can
immediately take effect, without having to change any document. For
example, there could be divs generated on many things, for example tables
so they could be better organized. A syntax like :this: could be used for
span and generally the HTML could be generated with many more extra
elements for better customizablility.


On Wed, Aug 14, 2013 at 8:46 PM, Joseph Reagle <joseph.2011-T1oY19WcHSwdnm+yROfE0A@public.gmane.org>wrote:

> On 08/14/2013 02:31 PM, Daniel Staal wrote:
>
>> If I have to pick one, I'd pick blockquote.  It's fairly easy to read,
>> and a decent text editor can mark up large stretches of text with it
>> fairly quickly.  (It also allows 'divs in divs', at least in theory,
>> which might be useful.)
>>
>
> As most editors are not quite decent, I would hesitate to trust many of
> them with wrapping the lines nicely, particularly in nested cases.
>
>
> --
> 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@**googlegroups.com<pandoc-discuss%2Bunsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org>
> .
> To post to this group, send email to pandoc-discuss@googlegroups.**com<pandoc-discuss-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org>
> .
> To view this discussion on the web visit https://groups.google.com/d/**
> msgid/pandoc-discuss/520BD095.**9060902%40reagle.org<https://groups.google.com/d/msgid/pandoc-discuss/520BD095.9060902%40reagle.org>
> .
>
> For more options, visit https://groups.google.com/**groups/opt_out<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/CALeOzZ8%2BNZTr4BdLjuachvie24wkpDyfAWYazUy5%3DpZTR7Y5rg%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 4043 bytes --]

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Shahbaz Youssefi [Aug 14 13 22:22 ]:
>    About divs: the block quote looks pretty nice. Doing it with ! has the
>    benefit of not getting mistaken with the normal quote.
>    About spans: I'm going to actually argue against it. Markdown was made
>    so the plain text would be readable and with minimal markup (hence the
>    name). Adding span means a lot of [extra]{#id .class key="value"}
>    [unnecessary]{#id .class key="value"} [clotter]{#id .class
>    key="value"}. I don't know what is pandoc's strategy. If it wants to
>    become another LaTeX, then adding all these formatting may be fine.

Markdown already has a way to add this kind of information, namely:

    <span id="id" class="class" key="value">extra clutter</span>

And this is fine if you're just targeting HTML.  My thought was to
provide a way to group inline elements and attach labels and attributes
to them that would work for all output formats, as a way of making
customization easier.  So, maybe you're writing a book in markdown,
and everything is great, except that in one chapter you need some
words to be in SillyFont.  I'd like to make it possible to do

   [some words]{.silly}

and write a small script to transform this into the appropriate LaTeX
commands for PDF output.  Of course, you wouldn't have to use the
spans at all if you never need customization.

This reminds me, though, that there is an option for span syntax
I didn't consider, namely <span>...</span>.  Currently pandoc
would parse that as

    [RawInline "html" "<span>", ..., RawInline "html" "</span>"]

but it could be taught to parse it as

    Span (attributes) ...

which would be much nicer to work with in scripts.  A big advantage of
this approach is that it would render perfectly in standard
markdown parsers.  But

    [some words]{.silly}

looks nicer to me than

    <span class="silly">some words</span>.

Not sure about this tradeoff.  Of course, HTML div tags could be used
to generate Div elements too.

>    However, if it wants to stay along the same idea as markdown, probably
>    it's best to not go overboard with such features.
>    As an alternative, I'd like to suggest some improvements that can
>    immediately take effect, without having to change any document. For
>    example, there could be divs generated on many things, for example
>    tables so they could be better organized. A syntax like :this: could be
>    used for span and generally the HTML could be generated with many more
>    extra elements for better customizablility.

You should probably start a new thread, or a github issue, for
discussion of these suggestions.  Pandoc already has a way to put
sections in divs (--section-divs), though detection of the end of
a section is not absolutely reliable in documents with raw HTML.
If there are other things that should be in divs, I'm open to the
suggestion.  I'm not sure how putting a table inside a div helps,
though.  Having an identifier would help, but that could be put directly
on the table tag.

Re: syntax for generic spans and divs

[Daniel Staal]

--As of August 14, 2013 8:16:02 PM -0700, John MacFarlane is alleged to 
have said:

> which would be much nicer to work with in scripts.  A big advantage of
> this approach is that it would render perfectly in standard
> markdown parsers.  But
>
>     [some words]{.silly}
>
> looks nicer to me than
>
>     <span class="silly">some words</span>.
>
> Not sure about this tradeoff.  Of course, HTML div tags could be used
> to generate Div elements too.

--As for the rest, it is mine.

A big point of Markdown is that it's supposed to be 'text email like'; 
starting to try to support full HTML constructs really gets away from that 
in my opinion.  However...

Extending that thought a bit further, there *is* a habit in emails of using 
pseudo-HTML entities: `<snark>`, `<geek>`, etc.  Could that be used? 
Obviously it's a bit hard to parse random words while still letting through 
actual HTML (especially if you try to allow for future changes in the HTML 
spec), but perhaps with the addition of CSS selector prefixes: 
`<.snark>snarky text</snark>` or `<#snark>snarky text</snark>`.  (Class and 
ID, respectively.)

If that can work, it could be used for both spans and divs - if it starts a 
block, it's a div, if it's inside a block, it's a span.

Daniel T. Staal

---------------------------------------------------------------
This email copyright the author.  Unless otherwise noted, you
are expressly allowed to retransmit, quote, or otherwise use
the contents for non-commercial purposes.  This copyright will
expire 5 years after the author's death, or in 30 years,
whichever is longer, unless such a period is in excess of
local copyright law.
---------------------------------------------------------------

Re: syntax for generic spans and divs

[Jesse Rosenthal]

Hello All,

Sorry for joining the discussion so late.  I'd just like to chime in
with my support for the concept, at least, of Daniel's suggestion below:

On Thu, 15 Aug 2013, Daniel Staal <DStaal-Jdbf3xiKgS8@public.gmane.org> wrote:
> Extending that thought a bit further, there *is* a habit in emails of
> using pseudo-HTML entities: `<snark>`, `<geek>`, etc.  Could that be
> used?  Obviously it's a bit hard to parse random words while still
> letting through actual HTML (especially if you try to allow for future
> changes in the HTML spec), but perhaps with the addition of CSS
> selector prefixes: `<.snark>snarky text</snark>` or `<#snark>snarky
> text</snark>`.  (Class and ID, respectively.)

That actually seems the most markdown-like, because it comes by far the
closest to being able to parse existing mailing-list emails. I would
even go so far as to suggest that we could allow leaving off the leading
period and number-sign, and let "class" be the default. It would be up
to the author to avoid existing html, but that is the case with current
emails anyway. Forward compatibility could be maintained by a command
line switch (`--read-tag-as-custom=snark`). Or perhaps html standards
changes are rare enough that authors could just update their files.

> If that can work, it could be used for both spans and divs - if it
> starts a block, it's a div, if it's inside a block, it's a span.

The above is part of the reason I like this approach. It doesn't add
unnecessary structural (span vs. div) when that should be clear from the
markdown layout. It just provides some legible semantic info on top.

The objection might be that raised that it would be xml-ish---but, as
was suggested, the balance between custom-tags and readability is
something that is already struck in emails. If authors want to make
their own works further illegible, I suppose that's their right. (You
*could* legally put a `<span class=...>`around every letter in a
markdown file. Doesn't mean you should.)

There might well be something wrong with this approach. But it's the
first one that occurred to me when this was first raised, and it's the
still the most attractive option, after a week of mulling.

Best,
Jesse

Re: syntax for generic spans and divs

[John Gabriele]

[-- Attachment #1: Type: text/plain, Size: 2326 bytes --]

On Mon, Aug 19, 2013 at 7:13 AM, Jesse Rosenthal <jrosenthal-4GNroTWusrE@public.gmane.org> wrote:

>
> On Thu, 15 Aug 2013, Daniel Staal <DStaal-Jdbf3xiKgS8@public.gmane.org> wrote:
> > Extending that thought a bit further, there *is* a habit in emails of
> > using pseudo-HTML entities: `<snark>`, `<geek>`, etc.  Could that be
> > used?  Obviously it's a bit hard to parse random words while still
> > letting through actual HTML (especially if you try to allow for future
> > changes in the HTML spec), but perhaps with the addition of CSS
> > selector prefixes: `<.snark>snarky text</snark>` or `<#snark>snarky
> > text</snark>`.  (Class and ID, respectively.)
>
> That actually seems the most markdown-like, because it comes by far the
> closest to being able to parse existing mailing-list emails.


Yes, that does work pretty nicely:

    <.snark>some text</snark>

But you could save the writer from having to repeat "snark":

    <.snark>some text</>

And then maybe put the most important part (the text) first:

    <>some text</.snark>

And for consistency with fenced blocks (and headings), switch to curlies:

    {}some text{/.snark}

but then we're pretty much back to

    [some text]{.snark}


> > If that can work, it could be used for both spans and divs - if it
> > starts a block, it's a div, if it's inside a block, it's a span.
>
> The above is part of the reason I like this approach. It doesn't add
> unnecessary structural (span vs. div) when that should be clear from the
> markdown layout. It just provides some legible semantic info on top.
>

Some nice things about using side-marked div blocks is that they look good
as plain text, and would be especially nice when you've got nested blocks.

-- 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-/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/CAO9PwMVhb6%3DwXGobJW-6qsMH10_zzaNKChxAYdbBeH8AVsMTag%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 3496 bytes --]

Re: syntax for generic spans and divs

[Daniel Staal]

--As of August 19, 2013 10:31:24 AM -0400, John Gabriele is alleged to have 
said:

> Yes, that does work pretty nicely:
>
>     <.snark>some text</snark>
>
> But you could save the writer from having to repeat "snark":
>
>     <.snark>some text</>
>
> And then maybe put the most important part (the text) first:
>
>     <>some text</.snark>
>
> And for consistency with fenced blocks (and headings), switch to curlies:
>
>     {}some text{/.snark}
>
> but then we're pretty much back to
>
>     [some text]{.snark}

--As for the rest, it is mine.

*All* of the options we are discussing are technically equivalent: They do 
the same thing, after all.  (Though I note your simplifications don't nest 
as well - a computer could work it out, but it might be hard for a human on 
long stretches.)  That's not really the point.

I like the first because it looks like something I've seen before in plain 
text - in emails, and on forums.  It has meaning to me, even without 
knowing anything about markdown or any other markup language.  (Even HTML: 
It's common enough at this point that it stands alone, in my opinion.) 
Whereas the last one is 'consistent' with current markdown syntax - in that 
it is a straightforward expansion of it.  As a programmer and a computer 
guy, it makes sense - but I don't think it has the same feel of 'inherent 
meaning' that the first does.

Personal opinion, of course.  And, after all, I was the one who came up 
with top suggestion.  ;)

Daniel T. Staal

---------------------------------------------------------------
This email copyright the author.  Unless otherwise noted, you
are expressly allowed to retransmit, quote, or otherwise use
the contents for non-commercial purposes.  This copyright will
expire 5 years after the author's death, or in 30 years,
whichever is longer, unless such a period is in excess of
local copyright law.
---------------------------------------------------------------

-- 
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/199F253FC5D7B557A1175999%40%5B192.168.1.50%5D.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[Shahbaz Youssefi]

[-- Attachment #1: Type: text/plain, Size: 1698 bytes --]

On Thu, Aug 15, 2013 at 5:16 AM, John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>wrote:

> I'm not sure how putting a table inside a div helps,
> though.  Having an identifier would help, but that could be put directly
> on the table tag.
>
>
I'd gather my thoughts and open a GitHub issue. Just to answer this at
least, having a div around the table makes it possible to get the table to
not have 100% width and still be centered. This is quite analogous to
usefulness of div around figure.

--
> 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/20130815031601.GB13193%40Johns-MacBook-Pro.local
> .
> 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/CALeOzZ9PU7F199tJvCw2HRodP71-oQA_aDSLC%2B_CHa--_0aJdg%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 2866 bytes --]

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Shahbaz Youssefi [Aug 15 13 15:42 ]:
>    On Thu, Aug 15, 2013 at 5:16 AM, John MacFarlane
>    <[1]fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 
>      I'm not sure how putting a table inside a div helps,
>      though. Having an identifier would help, but that could be put
>      directly
>      on the table tag.
> 
>    I'd gather my thoughts and open a GitHub issue. Just to answer this at
>    least, having a div around the table makes it possible to get the table
>    to not have 100% width and still be centered. This is quite analogous
>    to usefulness of div around figure.

You can't do this by applying css attributes directly to the table?

Re: syntax for generic spans and divs

[Dirk Laurie]

2013/8/14 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

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

I look at that. Then I re-read the John Gruber quote in
the Pandoc documentation.

       A Markdown-formatted document should be  publishable  as-is,  as
       plain  text,  without looking like it's been marked up with tags
       or formatting instructions.  -- John Gruber

Then I continue looking at one, and then the other, and try to
reconcile them. Without success so far.

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Dirk Laurie [Aug 15 13 08:56 ]:
> 2013/8/14 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> 
> > [this is a *span*, which can contain [links](/url) and
> >     other inline elements]{#id .class key="value"}
> 
> I look at that. Then I re-read the John Gruber quote in
> the Pandoc documentation.
> 
>        A Markdown-formatted document should be  publishable  as-is,  as
>        plain  text,  without looking like it's been marked up with tags
>        or formatting instructions.  -- John Gruber
> 
> Then I continue looking at one, and then the other, and try to
> reconcile them. Without success so far.

How about a special, realistic case (language tagging):

    En janvier, toutes les boutiques de Londres affichent des panneaux
    [SALE]{lang="en-GB"} mais en fait ces magasins sont bien
    propres!

It seems to me that this is more readable than the method Gruber's
original markdown supplies for this purpose, namely:

    En janvier, toutes les boutiques de Londres affichent des panneaux
    <span lang="en-GB">SALE</span>, mais en fait ces magasins sont bien
    propres!

Of course, you needn't use language tagging at all if you don't want to.

But maybe the thing to do, at least initially, is to just let the html
span and div tags themselves trigger Span and Div elements in the pandoc
AST.  This would degrade very gracefully in standard markdown, though it
would make the source documents less "human friendly."

Re: syntax for generic spans and divs

[Dirk Laurie]

2013/8/15 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:

> How about a special, realistic case (language tagging):
>
>     En janvier, toutes les boutiques de Londres affichent des panneaux
>     [SALE]{lang="en-GB"} mais en fait ces magasins sont bien
>     propres!
>

How would the LaTeX writer handle that?

> It seems to me that this is more readable than the method Gruber's
> original markdown supplies for this purpose, namely:
>
>     En janvier, toutes les boutiques de Londres affichent des panneaux
>     <span lang="en-GB">SALE</span>, mais en fait ces magasins sont bien
>     propres!

I prefer the second version. It is honest. One is invoking an HTML feature
and it is recognizable as HTML.

> But maybe the thing to do, at least initially, is to just let the html
> span and div tags themselves trigger Span and Div elements in the pandoc
> AST.  This would degrade very gracefully in standard markdown, though it
> would make the source documents less "human friendly."

Yes, let's see how many writers can render those.

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Dirk Laurie [Aug 15 13 19:54 ]:
> 2013/8/15 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> 
> > How about a special, realistic case (language tagging):
> >
> >     En janvier, toutes les boutiques de Londres affichent des panneaux
> >     [SALE]{lang="en-GB"} mais en fait ces magasins sont bien
> >     propres!
> >
> 
> How would the LaTeX writer handle that?

The LaTeX writer would output simply

SALE

But it would be easy to write a pandoc filter (just a few lines of python
or Haskell) that would do whatever you like with it.  For example,

\foreignlanguage{english}{SALE}

using the Babel package.  (This is a pretty silly example, but if the
text was longer, this might affect hyphenation.)

> > It seems to me that this is more readable than the method Gruber's
> > original markdown supplies for this purpose, namely:
> >
> >     En janvier, toutes les boutiques de Londres affichent des panneaux
> >     <span lang="en-GB">SALE</span>, mais en fait ces magasins sont bien
> >     propres!
> 
> I prefer the second version. It is honest. One is invoking an HTML feature
> and it is recognizable as HTML.

My thought is that the idea of adding attributes to a span of inlines
is not HTML-specific.  It's something that makes sense in a number of
output formats (though typically one might need to write a script to
determine how the span is treated in a given format).  The second
version makes your document SEEM HTML-specific, when in fact it isn't.

> > But maybe the thing to do, at least initially, is to just let the html
> > span and div tags themselves trigger Span and Div elements in the pandoc
> > AST.  This would degrade very gracefully in standard markdown, though it
> > would make the source documents less "human friendly."
> 
> Yes, let's see how many writers can render those.

Currently all writers (except HTML writers) just "pass through" the
contents of a Div or Span element.  So they can all render them.
Again, the point is to make it easier to customize pandoc for special
purposes.

Re: syntax for generic spans and divs

[Dirk Laurie]

2013/8/15 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> Currently all writers (except HTML writers) just "pass through" the
> contents of a Div or Span element.  So they can all render them.
> Again, the point is to make it easier to customize pandoc for special
> purposes.

So all it boils down to is that the construction [text]{instruction} means
that if [instruction] makes sense to some writer, it will be applied to all
of [text], otherwise [text] will be regarded as plain content.

In that case one might as well save one keystroke and make
other writers recognize the existing Pandoc feature of LaTeX syntax.
\langEng{SALE} and leave the customizable style files to handle it.
Span, Div etc just reduce to special cases of a more general construct.

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Dirk Laurie [Aug 16 13 04:22 ]:
> 2013/8/15 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> > Currently all writers (except HTML writers) just "pass through" the
> > contents of a Div or Span element.  So they can all render them.
> > Again, the point is to make it easier to customize pandoc for special
> > purposes.
> 
> So all it boils down to is that the construction [text]{instruction} means
> that if [instruction] makes sense to some writer, it will be applied to all
> of [text], otherwise [text] will be regarded as plain content.
> 
> In that case one might as well save one keystroke and make
> other writers recognize the existing Pandoc feature of LaTeX syntax.
> \langEng{SALE} and leave the customizable style files to handle it.
> Span, Div etc just reduce to special cases of a more general construct.

One could do that.  But I don't see it as obviously better than

    <span lang="en">SALE</span>

which also has the advantage of being standard markdown (unlike
the LaTeX).  And for some applications, it's helpful to have the
extra structure you get from key-value attributes.  (LaTeX itself
sometimes resorts to these in optional arguments.)

There's something a bit awkward, also, about using either an HTML
or a LaTeX construction for something that is supposed to work
for all output formats.

I think the conservative thing to do, for now, might be to have
pandoc parse material inside HTML span and div tags as
pandoc Span and Div objects.  This would be nicely
standard-markdown-compatible, while still providing scripting
flexibility.  That wouldn't be incompatible with also offering
a "markdownish" way of doing it in the future.

Re: syntax for generic spans and divs

[Dirk Laurie]

2013/8/16 John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>:
> +++ Dirk Laurie [Aug 16 13 04:22 ]:

> I think the conservative thing to do, for now, might be to have
> pandoc parse material inside HTML span and div tags as
> pandoc Span and Div objects.  This would be nicely
> standard-markdown-compatible, while still providing scripting
> flexibility.  That wouldn't be incompatible with also offering
> a "markdownish" way of doing it in the future.

I'll go along with that.

Re: syntax for generic spans and divs

[John Gabriele]

[-- Attachment #1: Type: text/plain, Size: 10327 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 12718 bytes --]

Re: syntax for generic spans and divs

[BP Jonsson]

[-- Attachment #1: Type: text/plain, Size: 11638 bytes --]

(I'm en route and writing on my phone. Apologies for responding to all and
everyone in a single top-post!)

I definitely prefer surround marking since as mentioned editors may not
always do the right thing. The argument that it makes copying/pasting
easier holds good not only for code in my opinion. After all when people
copy-paste quotes into emails, as opposed to when the mail program does it
automatically, they often use some surround delimiter!
I like Daniel's suggestion that div syntax could be an extension of
horizontal rule syntax since the latter marks a division in the text. The
one minor disadvantage I can see with that is that it would require some
discipline on the part of the human writer and reader to discriminate
between actual horizontal rules and div end markers, unless the latter must
end with an empty pair of braces. I use rules very seldom even in free form
prose but if it might be a concern for someone it should be considered.

A good thing with allowing several different `surround markers for divs
would be that it would be easier to nest divs, provided the pandoc reader
can take both the number and the choice of symbols into account. I like the
idea that the choice of symbol can be made meaningful to a script. One
advantage of the possibility of marking nested divs with a different symbol
as well as with a different number of symbols is that one wouldn't need to
count symbols when nesting. The case is somewhat different from code
blocks: if a code block is going to contain something which looks like a
code block marker you just can mark off the block with a longish delimiter
(`40i~<ESC>yypO` in vim!) and then not need to count tildes inside the
block; with nested divs you'ld need to actually keep minute count of how
many symbols you'd used on each level, and which level you're on, and at
least with my eyesight that might get tricky pretty soon!

Without necessarily sharing Shahbaz's and Dirk's concern about the CSS-ish
rather than markdownish span attribute syntax I quite understand it, and I
got an idea for a hopefully more 'prose-like' alternative syntax:

    [[class: text]]

    [[#id: text]]

    [[.class: text]]

    [[attr=val: text]]

    [[text]]

    [[: text]]

    [[#id .class a=v: text]]

    [[#id, .class, a=v: text]]

    [[class class: text]]

    [[class, class: text]]

That is:

1.    A span is surrounded by double angle brackets. These might be double
braces instead to make it easier to parse spans inside link text (would
anyone really need that?) but that would IMO immediately look less prosey!
2.    Everything up to the first colon + optional whitespace if any would
be attributes.
3.    Otherwise attribute syntax would be like section attribute syntax
except that:
    a)    Classes may be barewords or anything HTML would accept as a class
without a preceding period; with a keen eye to semantic markup this could
look very proselike if a bit telegrammatic:

            Classical third declension [[Lat: _caput_]] became second
declension [[VL: _capum_]].

    b)    To relieve any angst when sending markdown like this to a
markdown/pandoc innocent one could instantly turn this notation into almost
or entirely normal prose by replacing `[[` and `]]` with ordinary single
brackets, parentheses or emphasis, or if one can use regular expressions
even removing the attributes and brackets entirely. If one is co-editing a
markdown document as such then presumably everyone involved would have or
come to have pandoc installed and know about the syntax, so reverse
conversion would hardly be an issue.
    c)    Perhaps it could be allowed to separate attributes with commas to
make multiple bareword classes read more naturally.
4.    Perhaps the pandoc reader should ignore, or could be asked to ignore,
whitespace between brackets delimiting nested spans or links to make
replacing them per (3.b) easier?

Also or alternatively, regardless of which syntax is chosen, pandoc could
strip attribute blocks and replace span delimiters with ordinary emphasis
if invoked with

    pandoc -w markdown-attrs[+spans_as_emph|+spans_as_strong]

to achieve the same goal as in (3b) above. Come to think of it it would be
nice if one could simply use

    pandoc -t plain+feature

    to control which markdown constructs to preserve in plain output. I'ld
use `+emphasis` a lot!

Lastly two more immediately subject-relevant wishes:

1.    Unless you have already done so could you please make code attributes
accept attr=value pairs.
2. It would be nice if in case the entire content of a span is some inline
element -- most probably emphasis -- the span gets normalized away in HTML
output so that instead of

        <span class="foo"><em>bar</em></span>

    one gets

        <em class="foo">bar</em>

    and conversely when one reads HTML.

/bpj

Den torsdagen den 15:e augusti 2013 skrev John Gabriele:

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


-- 
/BP

-- 
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/CAFC_yuRxxxCDDv0MuF6s8MiMigSvVseu0wFH%2Bn3TCf3tVv%3DX5w%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 14237 bytes --]

Re: syntax for generic spans and divs

[John MacFarlane]

+++ John Gabriele [Aug 15 13 10:24 ]:

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

They are also used for images -- that's why they seem to me a natural
choice for an inlines-container.  The brackets group the inlines;
the rest of the construction tells you either that this is a link
label or that this is an image alt text or that it's a span.

>    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

I'm against breaking existing documents.  And using `|` for spans will
cause problems with pipe tables.

Re: syntax for generic spans and divs

[John Gabriele]

[-- Attachment #1: Type: text/plain, Size: 2581 bytes --]

On Thu, Aug 15, 2013 at 11:41 AM, John MacFarlane <fiddlosopher-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>wrote:

> +++ John Gabriele [Aug 15 13 10:24 ]:
>
> >    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.
>
> They are also used for images -- that's why they seem to me a natural
> choice for an inlines-container.  The brackets group the inlines;
> the rest of the construction tells you either that this is a link
> label or that this is an image alt text or that it's a span.
>

Hm. Seems to me that inlines are most commonly grouped (delimited) by a
character, for example: *italics*, `code`, ^superscript^, etc. That's why
pipes seemed to me possibly good for a generic inline/span marker.

But, yes, it seems difficult to do better than [your suggested
syntax]{.new-syntax}.

>    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
>
> I'm against breaking existing documents.  And using `|` for spans will
> cause problems with pipe tables.
>
>
Ok. If that's the case, then I suggest using the semicolon for the div
side-marking character:

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

It's:

  * unobtrusive,
  * easy to type (on us keyboards anyway),
  * has no strong connotation otherwise (such as "\*" for italics, or ":"
for definitions), and
  * has a nice vertical line-like appearance (moreso than dot)

-- 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-/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/CAO9PwMUhnVELm1Oe%2B2w0JVgCLAWXPGE41%3DEOk-bMmPcrEkLZjg%40mail.gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 3825 bytes --]

Re: syntax for generic spans and divs

[Gilles Pérez]

Hello,

Le 14/08/13 19:46, John MacFarlane a écrit :
> 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).
Yes!
> 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]{}
Yes, very good ideas. For now, I abuse some other syntax but a standard 
means to specify a span is good. And I think the [] notation is a good 
one: legible, markdown-like. It certainly conflicts with the goal of 
markdown to have a non-obstructing markup but it is less visually 
disturbing than a html or latex command.

If you decide to go for a html or latex construct, please provide an 
option for those who prefer a []{} notation.
> 2. DIVS
>
>     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.
I agree.
>      __________________________________________ {.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 like this one too.
> I'm eager to hear thoughts about these proposals.
I need very much a notation for a span element and I really don’t like 
the <html> or \latex syntax in md: it’s confusing for users.

Thank you,

Gilles.

-- 
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/520DF300.7030807%40gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[David Sanson]

I don't object to the [bracket syntax for spans]{.this}, but I slightly prefer simply using <span class=".this">the HTML syntax</span>, because it degrades gracefully.

It is uglier to write, but this isn't proposed as a core feature of pandoc's markdown syntax that makes a difference to stock conversions, but a syntax that enables custom scripting.

In the same spirit, I'd prefer the interpretation of <div> tags over the other proposed delimited block syntax proposals, which all look rather ugly to me. 

As for a sidemarked block syntax, I like the degradability of the blockquote proposal. But the <div> syntax degrades better. And I don't like blocking the future possibility of applying attributes to blockquotes. And I guess I don't see the need for a sidemarked syntax, so long as an easy delimited syntax is available.

And, again, the use of HTML tags fits, to my mind, with the intended use of these elements. It also undermines the force of the markdown-is-supposed-to-be-plain-and-now-you-are-recreating-HTML/LaTeX argument.

So my vote would be---at least at first---for the HTML tag solution for both spans and blocks. If these elements become more central to the behavior of stock pandoc conversions, then one could always add a "native" syntax later. 

David

-- 
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/35fe9b44-eb55-4b24-ad68-c958718684e7%40googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[Matthias Hüning]

[-- Attachment #1: Type: text/plain, Size: 932 bytes --]



Am Samstag, 17. August 2013 16:44:19 UTC+2 schrieb David Sanson:
>
>
> So my vote would be---at least at first---for the HTML tag solution for 
> both spans and blocks. If these elements become more central to the 
> behavior of stock pandoc conversions, then one could always add a "native" 
> syntax later.
>

I would like to second this.

Matthias 

-- 
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/569131ac-aae7-4237-9745-133133ce72f5%40googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 1343 bytes --]

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Matthias Hüning [Aug 19 13 00:14 ]:
> 
> 
> Am Samstag, 17. August 2013 16:44:19 UTC+2 schrieb David Sanson:
> >
> >
> > So my vote would be---at least at first---for the HTML tag solution for 
> > both spans and blocks. If these elements become more central to the 
> > behavior of stock pandoc conversions, then one could always add a "native" 
> > syntax later.
> >
> 
> I would like to second this.

I've now implemented parsing of <span> and <div> tags as
pandoc Span and Div elements in github master.

This has the GREAT advantage of full compatibility with standard
markdown.  People seem to have wildly differing (and sometimes
pretty strong) opinions about all the other options, so I think
for this release I'll content myself with this minimal change,
which gives people the flexibility to do some pretty fancy things
if they want to.

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-/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/20130819171309.GI563%40dhcp-128-32-252-6.lips.berkeley.edu.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[Nick Moffitt]

John MacFarlane:
> +++ Matthias Hüning [Aug 19 13 00:14 ]:
> > Am Samstag, 17. August 2013 16:44:19 UTC+2 schrieb David Sanson:
> > > So my vote would be---at least at first---for the HTML tag
> > > solution for both spans and blocks. If these elements become more
> > > central to the behavior of stock pandoc conversions, then one
> > > could always add a "native" syntax later.
> > I would like to second this.
> I've now implemented parsing of <span> and <div> tags as pandoc Span
> and Div elements in github master.
> 
> This has the GREAT advantage of full compatibility with standard
> markdown.  People seem to have wildly differing (and sometimes pretty
> strong) opinions about all the other options, so I think for this
> release I'll content myself with this minimal change, which gives
> people the flexibility to do some pretty fancy things if they want to.

I think this is a great compromise for now, and I am glad that we have
not ruled out something more ASCII-art-ish for the future.

I did feel that the blockquote syntax was a great visual cue, and fit my
assumptions of how I might delimit something div-like.  I found both
that and some kind of header for an indented block fit the e-mail
ęsthetic.  I understand if other requirements (markup noise, poor editor
support) moot those, but they just *felt* right in some way.

As for the problem of "this leaves some markup goop in the source text
that doesn't look right", I'd point up to the quoted material I included
above (trimmed sparingly to illustrate my point).  We are quite used to
quoted blocks having attribution lines above.  They nearly always
include the name of the block's author, and frequently they have a date
or date-and-time stamp.  They are, however, free-form.

I'm sure that standardising them for attribution markup has been
discussed before, but I haven't gone back to look at the history to be
sure.  Could we make attribution lines that support names, dates, and
arbitrary classes?  Perhaps some special syntax that could clearly
indicate that what follows is a <div> and not a <blockquote>?

-- 
"If you carefully examine the intercal package (which
was not available for a month despite emails about it
being a 404), you will discover that . is in ESR's
PATH."   -- Joey Hess

-- 
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/20130819180634.GB24194%40zork.net.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[John MacFarlane]

+++ Nick Moffitt [Aug 19 13 18:06 ]:
> I did feel that the blockquote syntax was a great visual cue, and fit my
> assumptions of how I might delimit something div-like.  I found both
> that and some kind of header for an indented block fit the e-mail
> ęsthetic.  I understand if other requirements (markup noise, poor editor
> support) moot those, but they just *felt* right in some way.

Note:  It's still going to be easy to use a script to capture the
following sort of thing and treat it specially:

> # Warning
>
> This is my warning.
>
> It's a bunch of blocks in a blockquote, starting with a header with
> text 'Warning'.

Or:

> # Watch out! {.warning}
>
> This is another approach.


-- 
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/20130819230642.GB14374%40dhcp-128-32-252-6.lips.berkeley.edu.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[BP Jonsson]

2013-08-19 19:13, John MacFarlane skrev:
> +++ Matthias Hüning [Aug 19 13 00:14 ]:
>>
>>
>> Am Samstag, 17. August 2013 16:44:19 UTC+2 schrieb David Sanson:
>>>
>>>
>>> So my vote would be---at least at first---for the HTML tag solution for
>>> both spans and blocks. If these elements become more central to the
>>> behavior of stock pandoc conversions, then one could always add a "native"
>>> syntax later.
>>>
>>
>> I would like to second this.
> 
> I've now implemented parsing of <span> and <div> tags as
> pandoc Span and Div elements in github master.
> 
> This has the GREAT advantage of full compatibility with standard
> markdown.  People seem to have wildly differing (and sometimes
> pretty strong) opinions about all the other options, so I think
> for this release I'll content myself with this minimal change,
> which gives people the flexibility to do some pretty fancy things
> if they want to.

It's better than nothing but personally I don't like that at all. The
reason I started to use Markdown/Pandoc to begin with is that I find
both HTML and TeXish markup extremely ugly and disturbing to read -- I
have to render them to see the text as text at all! I actually dislike
HTML slightly more because of the *paired* textual tags, so the
suggestion (Dirk's?) to have pandoc render a TeXish `\command{text}`
into HTML as `<span class="command">text</span>` would be slightly
preferable to me -- I even experimented with a text filter doing just
that at one point.

John, are you averse to in the future supporting more than one
syntax each if people's preferences differ too widely, e.g. both
a surround marking and a side marking style for divs? After all
we already have several syntaxes for tables!

(Note: I wrote the following yesterday before seeing John's mail
which I'm replying to.  Perhaps it can [still] contain something
useful. I'm afraid I was my usual verbose self, for which I apologize!)

While I agree that the suggested `[text]{.class}` syntax stretches the
limits of readability-as-text[^1] but it *does* connect nicely with the
existing `[linktext](url)` and `` `code`{.class} `` syntaxes.[^2] It
certainly isn't the most pretty or compact syntax imaginable, it is more
compact than the corresponding HTML, it does build on existing syntax
and it's no *more* ugly than that existing syntax.

It's definitely also an advantage if the attribute syntax for headings,
code(blocks) spans and divs is the same. That's also one reason why I
think that a surround marking style for div blocks would be preferable:
it would be closely similar to fenced code blocks, including the way
attributes are attached to them, and not to be confused with anything
esle like blockquotes; if they can be degraded to mere horizontal rules
by just stripping the attributes so much the better!

I briefly had the thought that since spans are a form of emphasis
maybe they should render as `_emphasized text_{.with attr=ibutes}`,
so that for the most part one could handle graceful degradation
with `s/_\zs{.\{-}}//g`{.vim} or its equivalent, but the question
is how emphasis inside spans should then be marked, but since
there are two alternative markers for emphasis that should be
solveable. Similarly `s/^\s*[_-*]\{4,}\zs\s*{.\{-}}\s*$/`{.vim}
should degrade divs if they look like 'horizontal rules with attributes'.

One way of getting around `[some]{.long .unsightly attribute=chains}`
would be to have a syntax for 'reference attributes' analogous to
reference links and similar to footnote syntax for use when one reuses
the same cluster of attributes several times in the same document, which
is often enough the case!

    This is a text with [some]{^a} noticeable word and then
    [another]{^a} equally noticeable word, and a then 
    still a [third]{^a #tertius} with some distinction 
    of its own.

    {^a}: .long .unsightly attribute=chains

Finally one could even *use scripting* if one feels a need to convert
markdown with these constructs into markdown with something sightlier!

/bpj

[^1]: That's why I suggested an alternative `[[class: text]]` or even
    `{class: text}` syntax in the hope that it would remain more
    readable-as- text even when left as-is or with the brackets replaced
    by ordinary parentheses.

    The best would certainly be if one could run

        pandoc -t markdown-spans-divs

    and get 'plain' markdown if one thinks that is sightlier or even

        pandoc -t markdown+spans_as_em+divs_as_quotes

    or

        pandoc -t markdown+spans_as_em+divs_as_rules

    if one still wants them marked in *some* way.

[^2]: In fact I have for a while used a perl program which modifies the
    pandoc AST via JSON so that a `` `text`{.foo.} `` (note the trailing
    period!) is converted to a raw inline
    `<span class="foo">text</span>` or `\foo{text}` depending on the
    desired output format, or a corresponding 'codeblock' \>
    div/environment, the routine recursively calling itself on the
    content of `text`. While it has its limitations -- e.g. you can't
    really use footnotes inside such a block! -- it actually is a
    general scripting tool: the script is just a wrapper around a
    module, and you can write your own script and define a subclass with
    methods so that for any `` `text`{.hook.} `` if your subclass has a
    method `hook_handler` it is called with an object as argument which
    contains the text, hook, other classes, id and type (inline/block)
    of the 'code' element (and in fact the default behavior is handled
    by an overridable `default_html` or `default_latex` method in the
    base class.) You then construct the html/latex text -- calling the
    pandoc wrapper method if necessary -- and then call a method on the
    element object to eat the brains of the AST hashref containing the
    code element, converting it to a raw element in place. It seems like
    this is pretty much the same as John has in mind with python
    scripting, except that I had to hook into pandoc's code syntax since
    it was the only element which supported attributes.

-- 
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/5218D585.20702%40gmail.com.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[John MacFarlane]

+++ BP Jonsson [Aug 24 13 17:47 ]:
 
> John, are you averse to in the future supporting more than one
> syntax each if people's preferences differ too widely, e.g. both
> a surround marking and a side marking style for divs? After all
> we already have several syntaxes for tables!

I could in principle do this, since we now have a system whereby
markdown extensions can be enabled or disabled piecemeal.  But I'd
like to move slowly, and I think it's good not to fragment the markdown
ecosystem even further.

I still kind of like [this syntax]{.class} for spans, and may implement
it in the future.

Re: syntax for generic spans and divs

[Bernhard Weichel]

[-- Attachment #1: Type: text/plain, Size: 2204 bytes --]

I know I am a bit late ...

Am Mittwoch, 14. August 2013 19:46:42 UTC+2 schrieb fiddlosopher
>
>
> 1. SPANS 
>
>     [this is a *span*, which can contain [links](/url) and 
>     other inline elements]{#id .class key="value"} 
>
>
For me It looks too much like a reference for me. So it appears a bit 
confusing.

In my Wortsammler application (e.g. 
https://github.com/bwl21/wortsammler/wiki/wortsammler-syntax#eingebettete-grafiken) 
I decided to use the striketrough markup for this. If a processor does not 
support the syntax, it will simply appear as strikethrough. In this case I 
loose the strikethrough which is not used in my documents either.

 

> 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 
>
>
My preferences would be

1. surround-marking
2. side-marking
3. indent-marking - I dislike that so much that I even won't call this an 
alternative
 
in Wortsammler, i use fenced code blocks for this.

for example to embed plantuml:

    ~~~~ {.plantuml}
        @startuml authentification.png

        Alice -> Bob: Authentication Request
        Bob --> Alice: Authentication Response
        @enduml 
    ~~~~

    ![Authentification](authentification.png)

 But the use case might be a bit different, since I am using a specific 
processor for a specifiic syntax in the code block.
I guess the intended DIV would still be regular markup.

I'm eager to hear thoughts about these proposals. 
>
> John 
>
>
Thanks again for all your effort and care you spend for pandoc.

-b 

-- 
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/461b4dd3-d4fe-423d-88cb-27245da856f7%40googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[-- Attachment #2: Type: text/html, Size: 3942 bytes --]

Re: syntax for generic spans and divs

[Pablo Rodríguez]

On 08/14/2013 07:46 PM, John MacFarlane 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).

Man thanks for this implementation, John.

> 1. SPANS
> [...]
> 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]{}

I’d ask for a way of marking natural languages:

    [Übereinstimmung]{:de}

As explained in https://github.com/jgm/pandoc/issues/895, :grc, :en-GB
and other should be valid languages.

So special marking (other than key=value) would be:

    {.class #id :language}

Would this marking also work with other inline elements, such as in
"_Übereinstimmung_{:de}"?

> 2. DIVS
> 
> 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).

Please, use surround-marking (at least). This is clear both the user and
the editor program.

Sure any decent editor can handle side-marking, but the problem here are
we indecent users :-). If I need vi or emacs to use pandoc, the barrier
entry is too high for me (and other average users).

I have a sample code that I had to introduce using a standard editor
(l3afpad, gedit or geany, just in case you wonder):

> 2. first paragraph
with many lines
>
>     a. other paragraph
with many lines
>
>     a. other paragraph
with many lines
>
>         1. other paragraph
with many lines
>
>         1. other paragraph
with many lines
>
> 3. other paragraph
with many lines
>
>      paragraph
>
>      a. new paragraph
other lines
>
>      a. one line
>
>      a. last paragraph
two lines

This is a quotation from a copyright act. It was impossible for me to
type directly as markdown code (I tried), so I wrote the HTML code and I
converted it with http://johnmacfarlane.net/pandoc/try/ and then I
pasted it within my markdown document.

Surround-marking is the easiest way to mark a block, the clearer to the
user and it can be “scaled” (one can add more elements) in a much easier
way.

These are my two requests.

Many thanks for your help,


Pablo
-- 
http://www.ousia.tk

-- 
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/52122B54.4020101%40web.de.
For more options, visit https://groups.google.com/groups/opt_out.

Re: syntax for generic spans and divs

[mb21]

[-- Attachment #1: Type: text/plain, Size: 9616 bytes --]

As jgm just posted a link to this topic here on _CommonMark discuss_, let 
me revive it:

1. The span syntax makes absolute sense to me.
2. About the div syntax: Side-marking (as with markdown block quotes) and 
indented block (as with lists and footnotes) have both the disadvantage of 
being very hard to work with, when you want to wrap a lot of existing stuff 
into a div, and you’re not using an code editor (like vim/emacs).

As such, I favour surround-marking (as with fenced code blocks), 
particularly with colons (because they look the best to me):

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

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

This syntax can be expanded a tad further to generic directives. Feel free 
to join the discussion at 
http://talk.commonmark.org/t/generic-directives-plugins-syntax/444

Cheers


On Wednesday, August 14, 2013 7:46:42 PM UTC+2, fiddlosopher 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-/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/381057ba-1977-4ae5-8fe7-efc880e7aa4b%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 11959 bytes --]

Re: syntax for generic spans and divs

[mb21]

[-- Attachment #1: Type: text/plain, Size: 1871 bytes --]

I quickly went through this thread and counted the “votes” for a native div 
syntax.

- Daniel Staal: If I have to pick one, I'd pick blockquote.
- Shahbaz Youssefi: About divs: the block quote looks pretty nice.
- John Gabriele: I think side-marking is the right choice for divs 
- BP Jonsson: I definitely prefer surround marking
- Bernhard Weichel: My preferences would be 1. surround-marking 2. 
side-marking
- ousia: use surround-marking
- Nick Moffitt: I did feel that the blockquote syntax was a great visual cue
- me (mb21): I favour surround-marking

*The result*:
- blockquote/side-marking: 4
- surround-marking: 4
- (Plus two or three advocating for HTML-syntax for now)

Note that no-one is a fan of indented-blocks. Some arguments in favour of 
each idea:

Side-marking:
- more readable for long sections (because it’s always obvious that you’re 
in a div-environment, even if the section is longer than the height of your 
screen)
- more local (removing one line doesn’t change large parts of your document)

Surround-marking:
- more readable for short sections (because of the almost-line-long 
surrounding markers)
- doesn’t require a decent editor to write easily
- better for copy’n’pasting / wrapping existing stuff in a div

-- 
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/3c0e9819-64b6-485c-ba43-2ad1cf092435%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 2529 bytes --]

Re: syntax for generic spans and divs

[Matthew Pickering]

[-- Attachment #1.1: Type: text/plain, Size: 2127 bytes --]

See my latest comment here <https://github.com/jgm/pandoc/issues/168>. I am 
personally for surround-marking with carets.

On Sunday, November 2, 2014 4:16:54 PM UTC, mb21 wrote:
>
> I quickly went through this thread and counted the “votes” for a native 
> div syntax.
>
> - Daniel Staal: If I have to pick one, I'd pick blockquote.
> - Shahbaz Youssefi: About divs: the block quote looks pretty nice.
> - John Gabriele: I think side-marking is the right choice for divs 
> - BP Jonsson: I definitely prefer surround marking
> - Bernhard Weichel: My preferences would be 1. surround-marking 2. 
> side-marking
> - ousia: use surround-marking
> - Nick Moffitt: I did feel that the blockquote syntax was a great visual 
> cue
> - me (mb21): I favour surround-marking
>
> *The result*:
> - blockquote/side-marking: 4
> - surround-marking: 4
> - (Plus two or three advocating for HTML-syntax for now)
>
> Note that no-one is a fan of indented-blocks. Some arguments in favour of 
> each idea:
>
> Side-marking:
> - more readable for long sections (because it’s always obvious that you’re 
> in a div-environment, even if the section is longer than the height of your 
> screen)
> - more local (removing one line doesn’t change large parts of your 
> document)
>
> Surround-marking:
> - more readable for short sections (because of the almost-line-long 
> surrounding markers)
> - doesn’t require a decent editor to write easily
> - better for copy’n’pasting / wrapping existing stuff in a div
>

-- 
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/01312d37-bd7d-4d61-958d-c04f6d709e4a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 2879 bytes --]

Re: syntax for generic spans and divs

[Bernhard Weichel]

[-- Attachment #1.1: Type: text/plain, Size: 1421 bytes --]



Am Sonntag, 7. Dezember 2014 13:09:47 UTC+1 schrieb Matthew Pickering:
>
> See my latest comment here <https://github.com/jgm/pandoc/issues/168>. I 
> am personally for surround-marking with carets.
>
> I am asking myself why we should invent new markup special character 
semantics all the time.

Wouldn't it be better to use a generic markup for such special cases:

HTML

<div class=".TIP">

</div>

or <div data-pandoc=".TIP">

XML combined with block attributes

<pandoc>{.TIP}

</pandoc>

XML pure

<pandoc class="TIP">
</pandoc>



I still use Strikethrough for personal enhancements like this.

~~edition slides~~

or fenced code blocks

~~~~ {.plantuml}
    @startuml     ../ZGEN_uml/test1.png
 
   box "Internal Service" #LightBlue
    participant Bob
    participant Alice
   end box

        
    @enduml
~~~~





<div>{.TIP}
</div>


-- 
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/f8ed3b3c-5ed0-4edc-847d-5100314cbc2f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #1.2: Type: text/html, Size: 4874 bytes --]

Re: syntax for generic spans and divs

[Daniel Staal]

--As of December 8, 2014 3:01:31 AM -0800, Bernhard Weichel is alleged to 
have said:

> Wouldn't it be better to use a generic markup for such special cases:
>
> HTML
>
> <div class=".TIP">
>
> </div>
>
> or <div data-pandoc=".TIP">
>
> XML combined with block attributes
>
> <pandoc>{.TIP}
>
> </pandoc>
>
> XML pure
>
> <pandoc class="TIP">
> </pandoc>

--As for the rest, it is mine.

Which brings us back to my suggestion for this: <CLASSNAME>Text to be 
styled.</CLASSNAME>

The only question is how to distinguish from normal HTML tags which are 
also allowed.  A list could be built in to pandoc for HTML that should be 
passed through, or some small distinguishing marker: <.CLASSNAME>Text to be 
styled.</CLASSNAME>  (I'd make the marker optional but allowed in the 
closing bracket.)

It goes back to one of the original inspirations for Markdown - text 
emails, where markers like <snark>snarky text</snark> are fairly common.

Daniel T. Staal

---------------------------------------------------------------
This email copyright the author.  Unless otherwise noted, you
are expressly allowed to retransmit, quote, or otherwise use
the contents for non-commercial purposes.  This copyright will
expire 5 years after the author's death, or in 30 years,
whichever is longer, unless such a period is in excess of
local copyright law.
---------------------------------------------------------------

Re: syntax for generic spans and divs

[BPJ]

[-- Attachment #1: Type: text/plain, Size: 2880 bytes --]

But surely we all use Markdown because we find HTML and/or LaTeX noisy or
even ugly, and want to make markup less intrusive by basing it on
punctuation?

tisdag 9 december 2014 skrev Daniel Staal <DStaal-Jdbf3xiKgS8@public.gmane.org>:

> --As of December 8, 2014 3:01:31 AM -0800, Bernhard Weichel is alleged to
> have said:
>
>  Wouldn't it be better to use a generic markup for such special cases:
>>
>> HTML
>>
>> <div class=".TIP">
>>
>> </div>
>>
>> or <div data-pandoc=".TIP">
>>
>> XML combined with block attributes
>>
>> <pandoc>{.TIP}
>>
>> </pandoc>
>>
>> XML pure
>>
>> <pandoc class="TIP">
>> </pandoc>
>>
>
> --As for the rest, it is mine.
>
> Which brings us back to my suggestion for this: <CLASSNAME>Text to be
> styled.</CLASSNAME>
>
> The only question is how to distinguish from normal HTML tags which are
> also allowed.  A list could be built in to pandoc for HTML that should be
> passed through, or some small distinguishing marker: <.CLASSNAME>Text to be
> styled.</CLASSNAME>  (I'd make the marker optional but allowed in the
> closing bracket.)
>
> It goes back to one of the original inspirations for Markdown - text
> emails, where markers like <snark>snarky text</snark> are fairly common.
>
> Daniel T. Staal
>
> ---------------------------------------------------------------
> This email copyright the author.  Unless otherwise noted, you
> are expressly allowed to retransmit, quote, or otherwise use
> the contents for non-commercial purposes.  This copyright will
> expire 5 years after the author's death, or in 30 years,
> whichever is longer, unless such a period is in excess of
> local copyright law.
> ---------------------------------------------------------------
>
> --
> 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/F9A02579C87697FEFF7442EA%40%5B192.168.1.50%5D.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
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/CADAJKhAFiJ8KGNkHOJg__KO9RN0uhr1ajsgQc%2BvReNm_%3D8dVuQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

[-- Attachment #2: Type: text/html, Size: 4099 bytes --]