msuchane / presciidoc Goto Github PK

The current version of presciidoc currently interprets three forward slashes at a beginning of a line as a comment line and when ran with the -c option, removes such lines from the output:

$ cat test.adoc 
/// This is not a comment
$ presciidoc -c test.adoc 
$

AsciiDoctor however defines line comments as exactly two forward slashes at the beginning of the line followed either by the end of line or any character other than another forward slash. As a consequence, the asciidoctor utility interprets lines starting with three forward slashes as regular paragraphs:

$ asciidoctor -so - test.adoc 
<div class="paragraph">
<p>/// This is not a comment</p>
</div>

I believe presciidoc should match this behavior.

Version 0.4.1 of presciidoc fails to recognize // without a space or any other character following it as a comment. Consider the following file:

$ cat test.adoc 
// There are no other characters after the slashes on the following line:
//

This line should be displayed.

When processed with asciidoctor, both comment lines are correctly ignored:

$ asciidoctor -so - test.adoc 
<div class="paragraph">
<p>This line should be displayed.</p>
</div>

When processed with presciidoc, the second comment line is however left in:

$ presciidoc -c test.adoc 

//

This line should be displayed.

Version 0.4.1 of presciidoc successfully removes code blocks but leaves the attribute lists (such as [source,ruby] or [literal,subs="+quotes"]) in the output. Consider the following file:

$ cat test.adoc 
This line should be displayed as a paragraph.

[literal,subs="+quotes"]
....
This block should be removed.
....

This line should be displayed as a paragraph.

When run with the -b option to remove the code block, presciidoc produces the following output:

$ presciidoc -b test.adoc 
This line should be displayed as a paragraph.

[literal,subs="+quotes"]




This line should be displayed as a paragraph.

Because of the way AsciiDoctor ignores empty lines that follow attribute lists, if this output was converted to HTML, AsciiDoctor would treat any non-empty line that follows after the attribute list as a code block:

$ presciidoc -b test.adoc | asciidoctor -so - -
<div class="paragraph">
<p>This line should be displayed as a paragraph.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>This line should be displayed as a paragraph.</pre>
</div>
</div>

I believe presciidoc should delete the attribute lists along with their corresponding code blocks.

The current version of presciidoc artificially removes the newline character from the very last line. I realize some editors prefer to store files without this character on the last line, but as presciidoc is intended to be used on the front of the command line pipe, this can contribute to unexpected and incorrect output.

Consider the following file (notice that the command prompts start on a new line):

$ cat test.adoc 
First line.
Second line.
$ wc -l test.adoc
2 test.adoc

When processed by presciidoc, the last newline character disappears which confuses some standard utilities:

$ presciidoc test.adoc 
First line.
Second line.$ presciidoc test.adoc | wc -l
1

I know Bash has many known pitfalls, but the most unexpected one is that when the last line does not have a newline character, the while read loop completely ignores it:

$ presciidoc test.adoc | while read line; do echo "Line: '$line'"; done
Line: 'First line.'

There is a workaround for it but as presciidoc is intended to be used for these types of tasks, I would recommend that it does not artificially strip the last newline if it is present in the file, even maybe adds it when it is not so that it guarantees predictable output.

The current version of presciidoc only recognizes comment blocks that use exactly four forward slashes as their delimiter. Consider the following file:

$ cat test.adoc 
This line should be displayed.

/////
This line is a block comment. The following line does not terminate this block either:
////
This line is a continuation of the block comment.
/////

This line should also be displayed.

AsciiDoctor allows four or more forward slashes as comment block delimiters and requires the same amount of slashes to close the open comment block. Because of that, it only displays the first and the last line of the example above:

$ asciidoctor -so - test.adoc 
<div class="paragraph">
<p>This line should be displayed.</p>
</div>
<div class="paragraph">
<p>This line should also be displayed.</p>
</div>

Because of the current behavior, presciidoc fails to recognize the initial opening of the comment block and displays it as regular lines. It then mistreats the four slashes that are inside a comment block and should be ignored as an opening of a comment block that is then never closed:

$ presciidoc -c test.adoc 
This line should be displayed.


This line is a block comment. The following line does not terminate this block either:

I believe presciidoc should match the behavior of asciidoctor.