-
-
Notifications
You must be signed in to change notification settings - Fork 5.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Rendering of documentation in terminal could perhaps be better #22870
Comments
Cool. We should try to adjust the docsystem API's so it's more extensible and Markdown doesn't have to live in Base for much longer, and other packages can do more interesting things. |
Maybe just print headers as |
Should be fairly broadly supported since it's a very low code point. |
I think just changing Examples to be standard bold is easier? |
Sure, but it seems like there should be a distinction between different levels of header, no? |
Where? There is a distinction between headers, they use different underline. As I said we could use |
That seems ugly. Am I missing something – why would we want to do that? |
Maybe I'm not being clear... Right now we use one |
Perhaps, but I like that we use the header semantics correctly. The hard part is that some documents use all six levels of header and really need the top one to be A HEADER, but other documents only use a single level of header and really would be better off with just a subtle indication of headerness. Perhaps when outputting a markdown document, we should take the overall depth of headers into account and start at the lowest level and work our way up to more and more intense header levels as they are needed. Would require pre-scanning the document, but perhaps this could be done when the document is constructed – i.e. each section would have a header depth field so you know how bold to make your headers. That dovetails nicely with an idea I had previously, which was that if you insert a chunk of markdown into a larger document, you really want the header levels in the chunk to be relative to the context into which its inserted. I.e. a level-one header in a chunk inserted into a book at a level-two section should become a level-three header under that section. |
I don't know what the header semantics are, why shouldn't the markdown here be generated with the "largest" header when a |
xref #19914 |
My point is that In this case, if there's only one level of header in some Markdown fragment, especially if we're showing it in the terminal, we typically want to output it only using the least prominent header style instead of the most prominent one. If the fragment actually had six levels of header, then we'd want to use all six styles. If it was being inserted into another document, on the other hand, we'd want to use the next level of prominence, respecting the structure of the document. So the rule should probably be something like this:
This idea requires distinguishing Markdown fragments from Markdown documents, which I'm not sure we do, but that could be a distinction made at render time instead of in the data structure itself. |
I would vote for the vertical bar, but either way it is a nice improvement! |
How about the same kind of left-side |
Not sure what you mean exactly, but maybe it would look good if the horizontal line was a few characters wide, on the line before the text starts? |
You mean adding a blank line on the top and bottom like:
? |
I mean that if you put the horizontal line on its own line you can make it wider, e.g.: ┌──
│ blabla
│ blabla |
That does give some more visual separation without being quite as heavy as the full hline. |
What about no horizontal line at the bottom so it's just the border on the top and left of each section? Example:
Not sure if the left border should extend below the text for its section or not. |
I was going to suggest (or at least demonstrate for comparison) a similar option to Stefan:
|
Hmm, to me, that would look like the second HEADER is a subheader to the first one. I think it is better to completely "reset" between methods. |
Think this is pretty ok now. |
Note that by using a header-1 for what is logically a subheading we also get odd rendering in IJulia, because the notebook uses Can't we at least use |
This was quite extensively discussed #22870 (comment) and following. I suggested just using bold to fix this straight away instead of a header at all, but, in my opinion, some overly complex solution was suggested instead and two years later we are still left with sucky example headers. |
I still like my "overly complex solution" fwiw 😝. When you splice a bit of markdown into another bit of markdown, it seems that the hierarchy of the text should be respected, i.e. an |
See you in two years ;) |
Okay, it took 3 years 😂 (#44866) |
For reference, below is a comparison between the documentation of a function as rendered in the terminal and in the documentation:
There are a few things I think are non ideal in the terminal output:
Example
header is too prominent. We use single#
for#Examples
which gives this massive header. Only bold should be enough (as the HTML shows it). Perhaps changing either to just using**Examples**
or###### Examples
to achieve this?Example
header is indented. I don't really see a reason for this, left alignment would look better to me.The text was updated successfully, but these errors were encountered: