search

adam-mcdaniel / oakc

A portable programming language with a compact intermediate representation
Apache License 2.0
725 stars 21 forks source link

doc subcommand markdown issues #66

Open kevinramharak opened 4 years ago

kevinramharak commented 4 years ago

So i noticed a few issues with the doc subcommand:

  1. the -o OUTPUT flag does not seem to work
  2. characters like * and _ have special meaning in markdown. These characters are currently unescapable when writing a #[doc("*")] directive
  3. a function without arguments is printed out like fn HWI::comport_console_clear). A function with arguments is printed out correctly like fn HWI::comport_self_out(source: &char) -> bool.
adam-mcdaniel commented 4 years ago

Ahh, the first problem came about when I fixed the -g flag not working, and is a simple fix. Additionally, the third problem is also a one or two line fix. The second, however, I'm not really sure is a problem. The user has the ability to make the markdown look terrible by leaving an unescaped *, and I'm fine with that being their fault.

kevinramharak commented 4 years ago

Except it is impossible to escape it. Unless im writing the wrong sequence but from what i have tested nothing of the following will generate a *: \*, \\* and \\\\*.

adam-mcdaniel commented 4 years ago

Ohhhh, I see what you mean. I thought you meant that the user could not un-make-the-rest-of-the-markdown-italic. That should be fixed.

adam-mcdaniel commented 4 years ago

After doing some digging, the root of this problem is not in this crate. The crate printing the markdown to the terminal is at fault. If you want to display a * character in your markdown, \* will work. You just can't print it to the terminal properly right now; the -o output file will be displayed properly by another markdown compiler or previewer.