TerosTechnology
Markdown multiline code block displayed as single line
Describe the bug In the documentation description, markdown multiline code blocks are displayed on a single line.
To Reproduce
//!
//! Vitis code snippet :
//! ``` C
//! int* versions = 0x0080000000 ;
//! xil_printf("FLAVOUR: %08x\n\r", versions[10]) ;
//! xil_printf("GLOBAL_DATE: %08x\n\r", versions[9]) ;
//! xil_printf("GLOBAL_TIME: %08x\n\r", versions[8]) ;
//! xil_printf("GLOBAL_VER: %08x\n\r", versions[7]) ;
//! xil_printf("GLOBAL_SHA: %08x\n\r", versions[6]) ;
//! xil_printf("TOP_VER: %08x\n\r", versions[5]) ;
//! xil_printf("TOP_SHA: %08x\n\r", versions[4]) ;
//! xil_printf("CON_VER: %08x\n\r", versions[3]) ;
//! xil_printf("CON_SHA: %08x\n\r", versions[2]) ;
//! xil_printf("HOG_VER: %08x\n\r", versions[1]) ;
//! xil_printf("HOG_SHA: %08x\n\r", versions[0]) ;
//! ```
//! Attempting to write to a register, or to read from a non-existant one crashes the software.
//! (and maybe even stalls the whole CPU, need to be tested)
//!
module axi_version_regs #()
endmodule
Please complete the following information:
- OS: Ubuntu 18.04.6 LTS
- VSCode version: 1.85.2
- TerosHDL version: 5.0.12
Screenshots
We get:
I expected (taken from https://markdownlivepreview.com/):
** Additional Context ** As far as I know, for Markdown one quote ' -> code displayed on a single line and 3 quotes ''' -> code should be displayed on multiple lines
Looks like this is a bug when converting markdown to html. Exported Markdown file works fine.
It's a pain but you need to insert empty lines:
//!
//! Vitis code snippet :
//!
//! ``` C
//! int* versions = 0x0080000000 ;
//!
//! xil_printf("FLAVOUR: %08x\n\r", versions[10]) ;
//!
//! xil_printf("GLOBAL_DATE: %08x\n\r", versions[9]) ;
//!
//! xil_printf("GLOBAL_TIME: %08x\n\r", versions[8]) ;
//! ```
//!
//! Attempting to write to a register, or to read from a non-existant one crashes the software.
//! (and maybe even stalls the whole CPU, need to be tested)
//!
I think that there is no way to do this. If we render the break line in the comments as a break line in the HTML this is really ugly, in this case it's not possible to split the big lines.
Other way it's only support break line in comments == break line in HTML for code snippets.
Look a good starting point, but I think that it doesn't work for all the cases. I see the problems:
- Depends of the language the comment symbol is
--(VHDL) or//(Verilog/SV). - It's possible to configure the symbol: https://terostechnology.github.io/terosHDLdoc/docs/documenter/getting_started#configuration
Myabe it's better to iterate all the descriptions after the parsing and to do, before to convert to MarkDown:
code_fix = code.replace(/```[^]*```/g, function(match){return match.replace(/\n/g, ' \n');});
What do you think?
Your are right, i totally forgot about the different comment symbol for verilog/sv. I will revisit this in a new PR.