RFC Markdown sections

[hayd]

This is on the top of #9852 (whitespace changes to Markdown) so please excuse the large diff in the first commit.

This adds methods for sections and subsections in the terminal, as a partial fix for #9850.

julia> Base.Markdown.parse("#Title")
                                                           Title
                                                          -=====-

julia> Base.Markdown.parse("##Section")
                                                          Section
                                                         -–––––––-

julia> Base.Markdown.parse("###Subsection")
Subsection
––––––––––

I don't feel strongly about what these actually are (very happy to amend), but thought I would put this out there.

cc @one-more-minute

[ivarne]

I merged #9852, so hopefully the diff will be smaller soon. Maybe github needs a forced push in order to get clean up this PR?

[hayd]

@ivarne rebased. (Thanks for merging #9852!)

[hayd]

TBH/my 2 cents: I don't particularly like/find it hard to read centered... personally I would prefer if they were all left-aligned. e.g.

julia> Base.Markdown.parse("#Title")
 Title
-=====-

julia> Base.Markdown.parse("##Section")
 Section
-–––––––-

julia> Base.Markdown.parse("###Subsection")
 Subsection
------------

[nalimilan]

I agree left-aligned is more readable.

[timholy]

I also like left-aligned.

[MichaelHatherly]

+1 for left-aligned.

[MikeInnes]

:( Well, I'm a bit sad to see my nice centred titles going, but the community giveth and the community taketh away. Feel free to left-align everything.

Personally I also think

 Title
=======

looks nicer than

 Title
-=====-

[jiahao]

Centrism is so 1980s.

[hayd]

Updated, it's now a little simpler (as @one-more-minute suggested):

julia> Markdown.parse("# Title")
 Title
=======

julia> Markdown.parse("## Section")
 Section
–––––––––

julia> Markdown.parse("### SubSection")
 SubSection
------------

[MikeInnes]

I see what you're going for here but I think it would look cleaner to do min(2+length(text), columns÷2).

[hayd]

That would do something different. This does the following for multiline titles:

 This title is longer that the column width
 so underline last line
========================

I think using div here would get some surprising/unstable/ugly behaviour.

[MikeInnes]

Sure, but it leads to weird behaviour if the last line happens to be short:

 This title is longer that the column width so underline last
 line
======

which looks a bit off to me, or even actively confusing since it's less obvious that it's a title.

The div code makes things more stable because the length of the underline will always be halfway across the terminal for long titles (and behaves the same way for short ones):

 This title is longer that the column width so underline last
 line
====================================

(Now I think about it, 2/3s the way across might look better, but that's a detail)

[hayd]

I'm kinda "meh" on both (I think both can look weird in some cases) but personally I prefer my way! :p

Edit (pressed enter too early): I wonder if anyone else has solved this problem (of what looks nicer).

[MikeInnes]

Well, it looks quite nice when it's all centred ;)

How about a mix of both – as long as the last line, but no shorter than 2/3s, for example?

[hayd]

Well, it looks quite nice when it's all centred ;)

true! ok, i'm gonna try either 1/2 or 1/3, see what looks "nicest", and we can change it later.

[elextr]

Some issues on underlining of titles that have bitten in the past on other projects:

1. non-monospaced fonts, and more and more terminals are coming with those
2. even in monospaced fonts, count graphemes, not code points, to account for composing characters
3. varying width unicode chars

Unfortunately libmojibake doesn't seem to handle the last two

Whilst this doesn't say "don't try to align underlines" just be aware that they won't work in some cases.

[hayd]

@elextr IMO if you use a non-monospace font you're going to have a bad terminal experience.

this doesn't say "don't try to align underlines" just be aware that they won't work in some cases.

+1.

[hayd]

@one-more-minute hopefully this last commit is a nice compromise :) force pushed a rebase over your latest commits (re boldness), they work great!

[hayd]

bump!

[ViralBShah]

Could you squash the commits?

[hayd]

Excellent! Thanks for merging @one-more-minute, squashed one but ran out of time this morning.

[MikeInnes]

No problem, thanks for the PR!