Scribble markdown renderer: tables

[Dominik Pantůček]

Hello Racketeers,

back from my procrastination projects to work :)

In the biggest project our company is working on right now, we use
Racket HTTP/REST backend and React.js frontend. The whole backend is
fully contracted - even all the actual servlets that are exposed via
HTTP are contracted. And in addition to it, they are all fully
documented using scribble/srcdoc.

I am using some syntax trickery to generate a table of API calls, so
that the frontend developers can easily find the right documentation. It
is just a transformation of dispatch-case to scribble tabular procedure.

With PDF output, it works like a charm. With markdown, the tables get
rendered as fixed-width columns - but it is still a plain text. No
markers, nothing.

Just to complete the picture, we are using CI/CD to automatically update
project's Gitlab wiki.

Am I missing something, or the markdown renderer produces incorrect
output and I should fix it?

Any hints will be VERY appreciated as the frontend is developed mostly
by non-programmers, so it would really help to have everything they need
in one interface (CI pipeline results, issues tracking, backend
documentation).


Cheers,
Dominik

[Alex Harsanyi]

I am not entirely sure what it is that is not working, so I am just guessing here:

* If you are generating Markdown files that contain tables, you need to be aware that tables need to be in column 0 (i.e. NOT indented).  If they are indented, they will be rendered as pre-formatted text.

* If you are using the `markdown` package to parse Markdown file, it does not support tables.  You either need to merge  Add support for table by antoineB · Pull Request #56 · greghendershott/markdown (github.com) , or use the `markdown-ng` package.

Hope this helps,

Alex. 

[Dominik Pantůček]

My impression is that the table generated by markdown render mixin is
not a markdown table.

This is what I get:

ONE two 33333
TWO three111
THREEone 222

From:

(tabular
(list
(list "ONE" "two" "33333")
(list "TWO" "three" "111")
(list "THREE" "one" "222")))

Also if you look at the actual line strings:

"ONE two 33333"
"TWO three111 "
"THREEone 222 "

I know it might sound silly, but to me it looks like the table
delimiters are just omitted in the code[1] and judging from the file
commit history, it looks like the tables are rendered on purpose this
way - but they are supposed to be wrapped inside ```/```racket blocks.
Which they aren't in this case.

The problem might be, that the markdown specification for tables
requires them to have the separator row and assumes first line to be the
heading line. While scribble tables are more LaTeX-like and do not make
any assumptions.

I hacked together a VERY ugly awk post-processing pass to solve the one
(and only one) table that I need to render properly. However it seems to
me that having better markdown table support might be beneficial for
others as well.

My proposal is:

Add the tabular delimiters ("| ", " | ", and " |") to the output and
generate the separator row immediately after the first row of data.

Is it too radical or should I patch the markdown renderer and send a PR?



[1]
https://github.com/racket/scribble/blob/master/scribble-lib/scribble/markdown-render.rkt#L94

On 30. 12. 20 1:14, Alex Harsanyi wrote:
>
> I am not entirely sure what it is that is not working, so I am just
> guessing here:
>
> * If you are generating Markdown files that contain tables, you need to
> be aware that tables need to be in column 0 (i.e. NOT indented).  If
> they are indented, they will be rendered as pre-formatted text.
> * If you are using the `markdown` package to parse Markdown file, it
> does not support tables.  You either need to merge  Add support for
> table by antoineB · Pull Request #56 · greghendershott/markdown

> (github.com) <https://github.com/greghendershott/markdown/pull/56> , or

> --
> You received this message because you are subscribed to the Google
> Groups "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to racket-users...@googlegroups.com
> <mailto:racket-users...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/racket-users/7d0d585f-0191-47ea-8979-ccbf71cf7a18n%40googlegroups.com
> <https://groups.google.com/d/msgid/racket-users/7d0d585f-0191-47ea-8979-ccbf71cf7a18n%40googlegroups.com?utm_medium=email&utm_source=footer>.