msuchane / presciidoc Goto Github PK
View Code? Open in Web Editor NEWPreprocessing AsciiDoc for other tools (WIP)
License: Apache License 2.0
Preprocessing AsciiDoc for other tools (WIP)
License: Apache License 2.0
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
.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.