What could a "spoiler tag" extension look like?


#41

@mofosyne I’ve come to like that as well (added your example). Maybe we’re soon converging on something here? Let’s hear some more people on the block style…


#42

I considered both fenced and indented styles for containers. I think, both are good, and selection depends on content, editor, and personal preferences. Probably, it worth to have both in the end. Whe only reason, why i mentioned fences - because it’s less “conflicting” with other markup and possible to finish in short time. Personally, i’d prefer fenced, but will agree with indented too. Any choice will be better than pushing blockquotes “as is” everywhere.

As far as i know, current fences spec allows to indent the whole block. This identation will be substracted later. Fencing do not force you to make identation, but allow to use it, if you wish to make result more trackable. Nested blocks are resolved by fences length.

May be fences concept needs some polish, but i don’t see fatal clashes in it.

My target community is “ordinary forum users”. They will be more comfortable with markdown (though they don’t know yet about it :slight_smile: ). I don’t pretend on right understanding of markdown spirit, but hope that my suggestions are not destructive for it. Selecting alternative text markup is not acceptable for me.

I don’t see problems with readability for indented style. But note, that editor depends on enviroment. On web that can be just a textbox. Also, i’m not sure that regular users have descent editors. I think that’s a question “what markdown spirit is?” in general - does it allow some visibility tradeoff for more simple and comfortable typing.

No prob, i understand. Nobody wish to be responsible for scary standard. IMHO, we could decide first, if we needed 2 styles (fenced + indented), or only one should stay in the end. If we select both, then we can set less conflicting to top priority. I’m realistic with timeline estimates for standards. 1 year is very optimistic for full final spec. That’s too long. So, it worth to range priorities, setting the most painful parts to top. IMHO block container is this one. Because it locks too much.

Tables, math & spans are also “painful”, but not locking other things as much as block container does.


#43

+++ Vitaly Puzrin [Oct 30 14 18:12 ]:

I don’t see problems with readability for indented style. But note, that editor depends on enviroment. On web that can be just a textbox. Also, i’m not sure that regular users have descent editors. I think that’s a question “what markdown spirit is?” in general - does it allow some visibility tradeoff for more simple and comfortable typing.

One of the essential guiding ideas in Markdown, as articulated in Gruber’s original documentation, is that it should be easy and natural to read. This sets it apart from, for example, Textile, which is just as easy as Markdown to write but less esay to read. So I think that the spirit of Markdown recommends favoring ease of reading when there is a tradeoff between ease of reading and ease of writing. This comes out clearly if you compare the way Markdown handles lists with the way most other lightweight markup systems (excluding reStructuredText) do. In Markdown, inclusion of continuation paragraphs and sublists is indicated by indentation, whereas in AsciiDoc and most wiki formats, you use duplicated list markers (**, ***, e.g.) for sublists, and a special connecting symbol (+) to join paragraphs to an existing list item. Compare this example from the AsciiDoc documentation

1. List item one.
+
List item one continued with a second paragraph followed by an
Indented block.
+
.................
$ ls *.sh
$ mv *.sh ~/tmp
.................
+
List item continued with a third paragraph.

2. List item two continued with an open block.
+
--
This paragraph is part of the preceding list item.

a. This list is nested and does not require explicit item continuation.
+
This paragraph is part of the preceding list item.

b. List item b.

This paragraph belongs to item two of the outer list.
--

with the Markdown equivalent:

1.  List item one.

    List item one continued with a second paragraph followed by an Indented
    block.

        $ ls *.sh
        $ mv *.sh ~/tmp

    List item continued with a third paragraph.

2.  List item two continued with an open block.

    This paragraph is part of the preceding list item.

    a.  This list is nested and does not require explicit item
        continuation.

        This paragraph is part of the preceding list item.

The Markdown version (technically, pandoc Markdown, because of the a. list item) looks a lot like the rendered version; you can see the nesting clearly. Not so with the AsciiDoc version – but the AsciiDoc version is easier to write, since you don’t have to worry about indenting things. So you can see these two different syntaxes as making different tradeoffs between ease of reading (by a human) and ease of writing.


#44

A solution here might be to improve Markdown editors instead of adding additional syntax options. For example, on this forum I’ve never manually typed the full quote syntax (e.g. [quote="jgm, post:43, topic:767"]) because it is easier to highlight a passage of text and click “quote reply”. The same might be applicable to lists, blockquotes, and other repetitive aspects of Markdown.


#45

Could you summarize pending problems of fenced markup? It allows identation (based on marker offset), and should provide user choice for both cases:

  • indented style for readability (or if you like it and have descent editor)
  • not indented style for easy typing in any enviroment.

Also it allows resolving nested blocks and possible cases are already investigated & covered in spec (as fenced blocks for code).

Someone can dislike need of tailing marker, but it’s not a big price for universality and ability to accept this markup in reasonable time. Also, it will not pervent to add pure indented style later if required.


#46

Quotes should not be edited, that’s an edge case. Improving editors can solve problem, but it’s unsafe to assume that all users always have editor with good indented style support.


#47

Just some thoughts.

  • Note that attribute blocks for side-marked blocks should not be inside the sidemarks, this precedent was set by Kramdown to avoid clashing with attributes on paragraphs within the side-marked content. But this could work:

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

    However, here it’s clearer to what the attribute belong to:

      :::::::::::::::: { .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 you’d probably rarely use a div without attributes.

  • For very long or nested content, the side-lined syntax seem to have the edge again.

      ::::::::::::: {#outer}
      blah
      blah
      blah
    
      ::: {#inner}
      ok
      ::::::::::::
    
      blah
      blah
      blah
      ::::::::::::::::::::::
    

    vs.

      : blah
      : blah
      : blah
      :
      : : ok
      : {#inner}
      :
      : blah
      : blah
      : blah
      {#outer}

#48

Yea I can see some convergence in regards to ::: . The difference tho is that I see it more as a block/div version of the inline/span []{}. Thus my logic is that since !extName[](){} is grammatically Verb/act + content/arg for inline, the same logic should apply for block directives as !extName: + content/arg. This allows for easily converting an existing block of content into a directive block. e.g.

This is spoiler text

Can be acted upon as

!spoiler:
This is spoiler text

Which is good for single paragraph content.

While for multi paragraph blocks, the ::: fence kicks in as:

!spoiler:
:::
This is a spoiler

With a second paragraph.
:::

I do not intend this to be a directive as it doesn’t have a block directive signifier !spoiler:. It’s just a div with classname .spoiler. E.g. you might want a warning, or notice box, and that would be rather overkill with directives

:::::::: Spoiler ::::::::::::::
Just a normal div container
:::::::::::::::::::::::::::::::

#49

I’ve handwritten and edited quotes numerous times. For example, when writing down a quote that is in printed material, embedded in an image or heard in spoken audio.

Agreed that we cannot make the assumption that the writer is using a specific editor. If the writer is quoting large blocks of text, perhaps they are an advanced user and likely to be using a more sophisticated editor? It would be good to see some use cases for long quotes. From my experience in academia it was generally frowned upon to quote more than a few paragraphs at a time; long quotes are at the expense of original content (perhaps @jgm would like to weigh in here).

With line blocks for song lyrics I can see a potential issue for marking up lengthy multi-paragraph songs.

If it is decided that a block syntax is necessary, perhaps we could use the same marker for familiarity, similar to how fenced code blocks use the same backtick as inline code:

>>>
This is a blockquote

Covering three paragraphs

Final paragraph
>>>

This could be an alternative to:

> This is a blockquote
>
> Covering three paragraphs
>
> Final paragraph

And for line blocks:

|||
This is a line block

Covering three paragraphs

Final paragraph
|||

This could be an alternative to:

| This is a blockquote
|
| Covering three paragraphs
|
| Final paragraph

I’m not entirely convinced of the need for this but it’s worth looking at options.


Should new lines start new paragraphs?
#50

At this point, I see a block directive as basically a div that in addition to containing block elements, has:

  1. inline content
  2. a name (could be rendered as a HTML5 custom tag)

In absence of a filter or something handling a directive, a div is a natural fallback.


#51

To quickly recap the arguments in favour of each div-syntax proposal (nobody seems to like indented syntax):

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

#52

I’d say, both should be supported at the end. Because side-marking is nice for small peaces of text. But, side-marking needs much work. Surround-marking is fenced-blocks like, and can be accepted very easy.

For me, it’s more management question, how to reorder spec priorities. Having one well working DIV markup is much better than having zero. I don’t count blockquotes, because i think those are unusable in current state.


#53

I agree. And the longer I think about it, the more I’m convinced that we should go for surround-marking for now. An alternative side-marking syntax could still be implemented later if needed.


#54

+++ Vitaly Puzrin [Nov 03 14 13:25 ]:

For me, it’s more management question, how to reorder spec priorities. Having one well working DIV markup is much better than having zero. I don’t count blockquotes, because i think those are unusable in current state.

Blockquotes are just a form of side-marking, and you don’t seem to be against side-marking in principle. Blockquotes can already contain arbitrary block elements. Why are they “unusuable” (supposing a mechanism was provided to add attributes)?


#55

I’ve written, that those are unuseable in current state, not unuseable at all. It was in context of comparison “what is more simple”: (a) finilize attributes spec a then consider fenced style divs or (b) consider fenced style divs and then work with attributes.


#56

It would be good to see some real world examples of where the current syntax is unusable.


#57

We mentioned it multiple times in different topics. In all cases, where container content needs different styling & still should have markup:

  • collapsable spoiler, with title (layout, style)
  • spoiler with hidden visibility (style)
  • sidenotes, epigraphs, … (style)
  • lyrics in text (style) (if you keep \n, hard breaks can be forced vith CSS for specific divs)
  • forum quotes (source post & user info, layout, style)

That’s not complete list, only examples that i can remember immediately. But it’s enougth to demonstrate, that problem is not in single case.

Under style i mean everything, that can be done via CSS. That means, such blocks should have custom CSS class. All examples above need markup in content and can’t be implemented via fenced blocks (at least, without dirty hacks). Also, those need metadata (custom class name at least) and can’t be implemented via blockqoutes now.

I don’t see big technical problem to quickly add such blocks support to remarkable, but don’t like to introduce one more syntax and split community one more time. With plans about my own projects i can wait about 1-2 months, if there is any hope that at least 1 type of “normal” DIV will appear in spec. At least in draft state.


#58

Agreed. This discussion about <div> block syntax sounds related to Content Block/Inline Syntax

I haven’t seen any objection for fenced ::: as the <div> block syntax. And I think it’s also a good candidate for fencing generic detectives that can fall back as normal content.

Since github does (where ‘ruby’ is a css class name I think):

```ruby
require 'redcarpet'
markdown = Redcarpet.new("Hello World!")
puts markdown.to_html
```

then a direct eqv using the spoiler example for div would be:

:::spoiler
spoiler content here
:::

to which we can prettify it like so (perhaps classnames should have no spacing):

:::::::spoiler::::::::
spoiler content here
::::::::::::::::::::::

What do you think about this approach @vitaly ?


#59

I don’t think we should be rushing new syntax additions, even if draft state, based on other project requirements. Refer to @codinghorror’s comment in the strikethrough topic; extensions are not the priority over the next six months.

My suggestion is that you use raw HTML in the meantime which is already included in the spec.


#60

Most of these wouldn’t require a div. They could be marked up with either blockquotes or line blocks (pre), plus additional markup for the extra data. Here’s what I suggest:

  • Collapsable spoiler, with title. Use the blockquote syntax with a class for spoiler. Set a parser rule to make a heading and/or link directly before the blockquote the collapsable title.
  • Spoiler with hidden visibility. Blockquote with spoiler CSS class.
  • Sidenotes, epigraphs. The proposed line block syntax (|) with a specific class.
  • Lyrics in text. Line blocks again.
  • Forum quotes (source post & user info). Perhaps a blockquote/definition list combination, I’m not sure. Discourse solves this very specific requirement by using a custom tag instead of Markdown. Blockquote seems like the right element to use in any case.

The problem with using the div tag is that is contains no semantic meaning other than being a container. The HTML5 spec even advises against using it (emphasis added):

Authors are strongly encouraged to view the div element as an element of last resort, for when no other element is suitable. Use of more appropriate elements instead of the div element leads to better accessibility for readers and easier maintainability for authors.

This is a strong indicator that the div element should not have it’s own Markdown syntax, even as an extension. We should aim to add more semantic elements on a case by case basis instead.