markdown support all 6 headers (title/section/subsections) in terminal

[peter1000]

Suggestion to support all 6 headers (title/section/subsections) like most
others e.g. github supports all 6 headers

Fast Fourier Transform

Fast Fourier Transform

Fast Fourier Transform

Fast Fourier Transform

Fast Fourier Transform

Fast Fourier Transform

Example code:

using Base.Markdown

md"""
# Fast Fourier Transform
## Fast Fourier Transform
### Fast Fourier Transform
#### Fast Fourier Transform
##### Fast Fourier Transform
###### Fast Fourier Transform
"""


OUTPUT

     Fast Fourier Transform
    ########################

     Fast Fourier Transform
    ========================

     Fast Fourier Transform
    ––––––––––––––––––––––––

     Fast Fourier Transform
    ************************

     Fast Fourier Transform
    ~~~~~~~~~~~~~~~~~~~~~~~~

     Fast Fourier Transform
    ------------------------

[peter1000]

seems that at the moment all osx build fail: https://travis-ci.org/JuliaLang/julia/builds/53648563
So this should not be a direct problem with the pullrequest

Cheers
P

[hayd]

-1 to 6 different characters, IMO the/any ordering is not intuitive...

An example of a Markdown which doesn't "support" headera this high is Stack Overflow, where IIRC h3 bolds and h4+ is ignored, and tbh this seems reasonable to me in the terminal. I guess I'm unclear on the use case for h4+s being distinct in the terminal... ?

Saying that, I agree the current #### could be better (I remember that from when I did #9853 but I didn't address it - it's such an unusual use)... could bolding and newline be reasonable compromise?

I think part of the problem here is that it's unclear how documentation is going to be done in practice, at the moment there are at least the following conventions for sections in docstrings: #, ##, ###, section: and **section**. The documentation (intentionally) doesn't suggest any convention. :(

cc #9853 and @MichaelHatherly

[peter1000]

@hayd
I would give to consideration that Markdown.jl exports on purpose functions like:

• readme which reads a Pkg README.md which might be using more than the current 3 headers.
  https://github.com/JuliaLang/julia/blob/master/base/markdown/Markdown.jl#L27

[hayd]

Could you give a real-life example README.md where bolding and indenting h4/h5/h6 the same (e.g. bold with a new line underneath / _term_header(io, md, ' ', columns)) would be an issue?

IMO this is unusual use case, and don't want to lose the simple (IMO) ordering of only 3 underline styles.

---

Saying that, if we did want more underline styles, \equiv is pretty nice to show the order (i.e. more lines would mean bigger h)

julia> Base.Markdown._term_header(STDOUT, Base.Markdown.Header("h1"), '≡', 77)
 h1
≡≡≡≡

julia> Base.Markdown._term_header(STDOUT, Base.Markdown.Header("h2"), "=", 77)
 h2
====

julia> Base.Markdown._term_header(STDOUT, Base.Markdown.Header("h3"), '―', 77)
 h3
――――

julia> Base.Markdown._term_header(STDOUT, Base.Markdown.Header("h4"), '-', 77)
 h4
----

julia> Base.Markdown._term_header(STDOUT, Base.Markdown.Header("h5"), ' ', 77)  # h6 the same
 h5

But I'm not sure this is needed, for the usual case I think h4+ being the same is fine.

[StefanKarpinski]

The triple lines of equiv is nice, but I worry about using a character that's not going to be supported everywhere. This is likely to not render correctly on Windows, for example. Now, if we start shipping with a decent terminal emulator on Windows, that might change the balance.

[MichaelHatherly]

@hayd, I've got no particular attachment to using **...** myself. It's mostly just from headers not being quite as distinctive in the terminal output as I'd wanted. Those \equivs are rather nice I think, but as Stefan mentions could be a problem for Windows. (I don't have access at the moment to a Windows machine to actually try it out though.)

[peter1000]

hi @hayd,
If one doesn't want to lose the simple (IMO) ordering of only 3 underline styles: there is no need to make use of h4,h5,h6 - in my opinion it is as simple as that.

Personally I think it is a rather nice idea to access Pkg information (at the moment @doc, LICENSE, README.md) within the REPL.
I'm not saying that one will make use often of all 6 headers but one might choose to use
h4,h5,h6 for a README.md because it is also used in other places like github and one preferce such instead of h1/h2/h3

---

Fast Fourier Transform

whatever...

Fast Fourier Transform

whatever...

Fast Fourier Transform

whatever...

---

Currently it renders like this:

which is not very distinct as @MichaelHatherly said above. In fact with the leading ###### it looks pretty ugly to me.

[tkelman]

This is likely to not render correctly on Windows, for example. Now, if we start shipping with a decent terminal emulator on Windows, that might change the balance.

[hayd]

@peter1000 yep, definitely ugly, we should lose the #### for sure. I'm advocating bolding h4+.

[peter1000]

@hayd,

In my view, if a text author wants bold he would have used it and would not have made a consious decision to use h4/h5/h6 instead. If the author of the @doc, README ect.. thought it wise to display things more distinct - I thing it wise to do the same (if it is possible without too much hassle)

We just have different opinions which is fine.

Of course we agree on one thing: the current situation is ugly.
P

[hayd]

I had this half-composed message yesterday:

I've went a bit off-topic / my two issues are distinct:

1. using 6 non-ordered characters for h1-6 is confusing (I think h4,h5,h6 displaying the same in the terminal is fine, using _term_header(io, md, ' ', columns) - edit: that's not just bold)
2. there's no convention for sections within docstrings

These are kinda related, since it's not clear what will be the most important / oft-used headers. For example, we wouldn't want something elaborate for h1s within docstrings if you use h1 for every section (even though that may be nice in an h1 from a README):

%%%%
 h1
%%%%

Note: 2. is #8966 / #8966 (comment): IMO there should be some simple convention(s), which are unambiguously parsable into a meta object i.e. be able to extract the sections... even if we don't implement the actual parsing/meta object yet. Otherwise everyone does random things and which can't all be parsed in the future. Also, a convention is needed for docstrings in Base.

---

Also we could reduce some lines/code duplication here by doing:

function term{N}(io::IO, md::Header{N}, columns)
    # raise for h7+ ?
    underline = "=–-   "[N]
    _term_header(io, md, underline, columns)
 end

[hayd]

If we are allowed \equiv (and \cdot) I put together an alternative pr #10481.

[peter1000]

I think if possible an ordered underline character as you @hayd suggested in #10481 is surely a better choice than what I suggested.

The only 2 important thing I would really want to see are:

1. All 6 headings must be distinct
2. All 6 headings must be different than normal bold,italic ect..

[MikeInnes]

@peter1000 Thanks for having a go at this one, even if it didn't go through in the end.

[peter1000]

that's just fine with me - will check it out...