diff --git a/README.md b/README.md index e136eee..b46cbda 100644 --- a/README.md +++ b/README.md @@ -477,6 +477,93 @@ show-msg() { ## Advanced features +### Literal md source + +By default, `shdoc` performs whitespace trimming at the start of a comment line while it builds description blocks. +This behavior disables the possibility to use formatting options like code blocks by indentation (4 spaces), or use +pre-formatted (and indented) text within fenced code blocks (`~~~` or ` ``` `). + +It is possible to disable the trimming behavior by using `#|` as comment prefix, instead of just `# ` (as for annotations). +`shdoc` will only consume the beginning of the line matching the regex `[ ]*#|` and leave the rest untouched. +**Exception:** There is a simple detection if the line contains a table row definition (when it also ends with `|[ ]*`). +In that case, only `[ ]*#` at the beginning will be consumed and the pipe will be left untouched. + +**Examples** + +- Simple + + + + + + + + + +
InputResult
+ +```bash +# @description Simple +#| This is kept literally... +#| ... this too +# me too... not. +``` + + + +```md +Simple + This is kept literally... + ... this too +me too... not. +``` + +
+ +- Tables +**Note:** In MD itself, there is little reason to indenting a table. Instead, indenting it too far would convert the table into a code block instead, +where the table source code is not processed as MD. +The literal md marker does not perform any extra checks to find out wether the pipe contained in `#|` is part of the table or not. The pipe character +connected to the comment hash will be stripped. As a consequence, writing tables requires a space between `#` and the left beginning `|` for regular +tables. Alternatively, if the table code should really be indented, 2 pipes must be used, with spaces in between. + + + + + + + + + + +
InputResult
+ +```bash +# @description Table +#| co1 | co2 | +# | abc | def | +#| | 123 | 456 | +#| | 123 | 456 | +``` + + + +```md +Table + co1 | co2 | +| abc | def | + | 123 | 456 | + | 123 | 456 | +``` + +
+ + +Takeaway: +1. If (for optical reasons only) you want to indent a table, don't use `#|`. +2. For regular tables, keep at least one space between `#` and `|` at the beginning of the line +3. Indenting table source requires `#|`, followed by the desired amount of spaces, then `|` to start the table row. + ### Parameter support **fork-specific** diff --git a/shdoc b/shdoc index 3eb6d09..762e63d 100755 --- a/shdoc +++ b/shdoc @@ -730,12 +730,16 @@ in_description { in_description = 0 handle_description() + } else if (match($0, /^[[:space:]]*#\|/)) { + debug("→ → in_description: literal [" $0 "] (keep spaces)") + sub(/^[[:space:]]*#\|/, "") + description = concat(description, $0) + next } else { sub(/^[[:space:]]*# @description[[:space:]]*/, "") sub(/^[[:space:]]*#[[:space:]]*/, "") sub(/^[[:space:]]*#$/, "") debug("→ → in_description: concat [" $0 "]") - description = concat(description, $0) next } @@ -743,6 +747,7 @@ in_description { /^[[:space:]]*# @endsection/ { debug("→ @endsection") + process_section() section = "" section_description = "" section_active = 0 diff --git a/tests/testcases/md-literal-lines.test.sh b/tests/testcases/md-literal-lines.test.sh new file mode 100644 index 0000000..5bcf3b5 --- /dev/null +++ b/tests/testcases/md-literal-lines.test.sh @@ -0,0 +1,115 @@ +#!/bin/bash + +tests:put input <