Version 4

[Gazook89]

Opening this discussion to collect ideas in a 'next big version'. There are other discussion threads that focus on more specific aspects of Homebrewery, which I'll link to, but for things that don't have or need their own thing, here we go:

a. Typescript
b. Responsive/Mobile UI (and codemirror 6?)
c. Two-way interaction between renderer and editor (d3.js?)

[5e-Cleric]

AFAIK, CSS layers and brew themes are coming with v4, aren't they?

I'll add to this the idea for the editor modes(pop out editor, or being able to change it to the right of the brew) as it is related to the responsive design. #2780

And if we can, Less and Sass support would be nice to have too, as well as CSS Folding. #2793

[calculuschild]

Themes are intended for v3. Just waiting for bits of cleanup and getting links to custom themes working.

[dbolack-ab]

a. Typescript

Like a full refactor?

b. Responsive/Mobile UI (and codemirror 6?)

Do people do this? try to author on phones or is there something I don't understand?

[calculuschild]

a) I'm actually pretty uneasy about Typescript. Every time i have used it, it adds so much bloat and boilerplate that any stability gained from typing is overwhelmed by illegibility. I would vote no on this.

b) Yeah... I am always surprised but people do try to edit on mobile with some frequency.

[ericscheid]

d) simultaneous editing by multiple authors

[5e-Cleric]

This i've wanted for sooo long, i tend to do my best worldbuilding when i have someone to bounce crazy ideas off.

[5e-Cleric]

e) spellcheck.
AFAIK, you can't use browser's spelling features in an element that is not editable(exc. using duplication of elements).
But we could add a js library for spellchecking
it could even be a toggle spellcheck, if it takes too much memory.

F) snippet preview?

G) FontAwesome icon picker Done

H) All selectable fonts as snippet to add Done

I) OUR OWN PDF RENDERING, i want bookmarks

J) adding comments as if html comments didn't exist

K)BLEEDING

[calculuschild]

I think F, G, and H could be part of V3 if we want. H would actually be really easy and already kind of exists in the Table -> Rune Table snippet.

So yes I agree these would all be nice. But if they would work with V3 in a way that doesn't break anything, we don't have to wait to implement them. V4 would be more for changes that would break V3 (i.e., bleeding would require a lot of redesign of the CSS that would break existing documents, etc).

[dbolack-ab]

I have been beating my head on the PDF thing for a while. I've gotten close - but it honestly looks like it may require a proper markdown to PDF tool.

I'm still trying to get around that.

[ericscheid]

For adding comments to brews I simply use html comments.

<!-- this is a comment -→

There's even a keyboard shortcut for it, and it is easy to select whole brew paragraphs (etc) and then comment them out.

(It does mean it still shows in the rendered html source. I'm OK with that.)

[ericscheid]

Here is my // comment // that is inline

In javascript, everything following the // is a comment. Not just the bit between the pair of //.

If you want an inline comment, it would be like this.

Here is my /* comment */ that is inline

So .. that's two forms of markup for comments.

[Gazook89]

Yeah, that's why i said "semi-javascript". I just like repeating a single character twice rather than complicating it.

However, I very truly do not have a horse in this race. HTML comments seem fine to me. They are visually distinctive from other text (which to me is a bonus for comments), and the others reasons i mentioned.

[5e-Cleric]

i just hate the fact that to comment something i need 5 keystrokes (< Shift+1 - -) for

And before anyone says why don't you use the shortcut, it is not possible with my keyboard, i need shift for outputting /

[dbolack-ab]

It has been discovered recently that:

marked provides <? ?> for comments
marked-smartypants provides <! which can run unenclosed until the end of a text block.

[5e-Cleric]

must point out, some of these produce empty p elements with the comments inside, instead of just the comment.

[5e-Cleric]

As talked about in Gitter today, we might want to add/change writing syntax for some things, like adding underline syntax:

_this text would be underlined_ as syntax
and the shortcut could be Ctrl + u
in the html as <u>this text would be underlined</u>

also italics could use <i> if it doesnt already, and bold should probably use <b>, since we don't care for readers anyway.

• Highlight text syntax?

L. Copy button next to Code blocks

[dbolack-ab]

Italics and bold use <em> and <strong> respectively. My understanding ( which may be wrong or outdated ) is that emphasis doesn't have a specific requirement for how emphasis is applied - just that the standard practice is italics in many/most language setups. strong is similarly weakly defined. As such, the only thing making *Thing* Italicize Thing is the style sheet. :)

I am rather loosey-goosey on the whole notion of changing things in potentially brew-breaking ways but changing the meaning of _ and __ seems pretty reasonable. I'm not sure that many folks who do a lot fo markdown use it over * patterns. Is there any way to survey? Scan actual brews?

[5e-Cleric]

The thing is that em and strong are usually better practice because you want screen readers to pick it up as strong or emphasized, but that is not an issue here, although there isnt much difference.

We tend not to want changing brew-breaking stuff, specially if there is no significant improval. But for v4 it'd be fine i reckon.

[5e-Cleric]

Based on the discussion on Gitter chat, the next syntax ideas might be the ones actually used in v4:

ELEMENT	v3 SYNTAX	v4 SYNTAX
headers	# to ###### header	# to ###### header
italics	*italics*	*italics*
bold	**bold**	**bold**
italicsbold	***italicsbold***	***italicsbold***
underline	<u>underline</u>	_underline_
strikethrough	~strikethrough~ OR ~~strikethrough~~	~strikethrough~ OR ~~strikethrough~~
link	[link](href)	[link](href)
right aligned text	{{text-align:right right aligned text}}	-: right aligned text
left aligned text	{{text-align:left left aligned text}}	:- left aligned text
center aligned text	{{text-align:center center aligned text}}	:-: center aligned text
list element	- list element OR * list element OR + list element	- list element (unsure if we should leave *)
ordered list element	x. list element OR i list element	x. list element OR i list element
📕	:book:	:book:
vertical space	::::	::::
line break	two spaces or \ at end of sentence, or <br>	two spaces or \ at end of sentence, or <br>
horizontal          space	horizontal :>>>>>>>> space	horizontal :>>>>>>>> space
inline term definition	Inline term::definition	Inline term :: definition (enforce spaces around ::)

---

Not agreed upon yet

ELEMENT	v3 SYNTAX	v4 PROPOSED SYNTAX
- caption	{{text-align:right -- caption}}	~caption

In all of these cases the syntax can be somehow achieved using curly spans or block syntax, i don't want to add it every time or this table would be big as hell.

If i have left something out, be sure to comment so i can edit this table.

[dbolack-ab]

Added #3909 For evaluating the non-breaking space token.

[5e-Cleric]

Regarding the * mode for ULs. I personally come to that pattern from word-processing which is probably where this comes from in the spec. I can't remember the last one I used that didn't convert some version of /^*/ into a bulleted list.

I expect removing that would cause more confusion than removing the other two modes would ( not that I have strong feelings about doing that instead )

I don't care the one we change, but - is the only one in my keyboard i can use without additional keys.

[dbolack-ab]

I don't care the one we change, but - is the only one in my keyboard i can use without additional keys.

Unless we wish to reuse one or more of those tokens elsewhere I don't think this is a valuable change.

[Gazook89]

I think we keep all three syntaxes for the lists. But I also see that i already said that in the next comment thread below this one, where Eric explains why.

[5e-Cleric]

i say again, i see why anyone would want 2, just don't see where the third one comes in handy. but alright, i'm not going to force this change.

[ericscheid]

Using - and + as alternative bullet list forms is actually useful .. because they get rendered as separate <ul>.

This brew source..

+ item
+ item
+ item

- item
- item

.. renders to

<ul>
  <li>item</item>
  <li>item</item>
  <li>item</item>
</ul>

<ul>
  <li>item</item>
  <li>item</item>
</ul

This is useful. I have used this when writing up long bullet list outlines where I want to keep different sections separate.

[ericscheid]

Mostly not.

Unless I'm using CSS like .page#p2 ul:nth-of-kind(3) .. because it's now all one huge bullet list with some <div class=blank> inserted inside list items.

I would have to resort to hacking up my source with {{curly-blocks}} to get the separation. A step backwards.

[Gazook89]

I am doubtful of how often this functionality gets used, but even so I think I am with Eric on this one. To match the current output we'd have to create more CSS and otherwise twist around to get the desired effect...and any effort spent doing that isn't worth breaking from the commonmark spec. And, the list syntax isn't +item, it's with the space + item....so I'm not sure that we gain anything from dropping those other list indicators anyway.

[dbolack-ab]

That is unfortunate.

[5e-Cleric]

i still don't think we need three separate syntaxes for the same thing.

[dbolack-ab]

i still don't think we need three separate syntaxes for the same thing.

Need? No. But lacking a reason to remove them, we maybe shouldn't?

[dbolack-ab]

What about adding thumbnail generation? It is fairly easy.

[5e-Cleric]

you mean outputting the first page of a brew as a png?

[dbolack-ab]

Essentially

[calculuschild]

A couple more possibilities:

Index Markers (already in #3133)

Basically #label (no space after #) to indicate an entry that should appear in an index, plus some sugar added on to indicate synonyms/parent/child relationships between entries. #index | synonym or similar if I recall.

Which makes me think perhaps we can extend headers in a similar way to guide TOC generation instead of relying upon CSS --excludeTOC tags? Given that indices and table of contents fall into a similar class of "auto-generated structure".

TOC Markers

Some permutation of # Header @ where @ is some symbol or string we devise to indicate that a header should be excluded/included from the Table of Contents.

[dbolack-ab]

TOC Markers

Some permutation of # Header @ where @ is some symbol or string we devise to indicate that a header should be excluded/included from the Table of Contents.

Currently, the ToC generator runs entirely via DOM scraping, so anything like this would need to override the header parsing and add this field as a HTML attribute on the <H#> in question. I don't think this is a bad idea, but I'm unsure if this might interfere with the HeaderID addon?

[5e-Cleric]

I am not sure we want to pursue this route at all. I think, that indexes should be done by hand, once the brew is done. Same for ToC, is it a lot of work? absolutely. Could we help users with it? sure. But no feature is going to be perfect for any user. I think we should choose whatever method based on:

• ease of use
• ease to code
• flexibility of the method to create different outputs.

Perhaps the best thing we could do is some widget to let the user look for instances of a word in the text, like the search text feature, then collect the instances. Not while writing and cluttering the syntax, but later looking for that text programatically. And let me clarify that, ONLY when generating, not constantly.

@dbolack-ab @calculuschild What do you think?

[dbolack-ab]

I am not sure we want to pursue this route at all. I think, that indexes should be done by hand, once the brew is done. Same for ToC, is it a lot of work? absolutely. Could we help users with it? sure. But no feature is going to be perfect for any user. I think we should choose whatever method based on:

I'm at a loss here, particularly when the code has been done for months....

[5e-Cleric]

I do see how my comment would sound like nonsense

[dbolack-ab]

I do see how my comment would sound like nonsense

No, It doesn't come across as nonsense. However, it is antithetical to the idea of the Rich Indexes code.

That said a "simple" index that operated in this way might also be useful. If I was to select one or the other, I would, as a user, find the simple option very disappointing on a product that needed an index..

[Gazook89]

Table column width syntax as talked about here #1528

[5e-Cleric]

Do we need to wait till v4 for that? as long as we assume no numbers as the current behaviour we should be able to do this without breaking, no?

[dbolack-ab]

Working version: calculuschild/marked-extended-tables#456