Skip to content

Commit

Permalink
Remove code comments from HTML output.
Browse files Browse the repository at this point in the history 
The literate program already explains everything
necessary, so the code comments are not useful.

The code comments however are kept in the generated
source, since that can be useful when reading the
generated source directly.

Fixes #38
  • Loading branch information
@jesterKing
jesterKing committed Dec 27, 2023
1 parent f4df474 commit 147728a
Show file tree
Hide file tree
Showing 3 changed files with 74 additions and 6 deletions.
38 changes: 35 additions & 3 deletions literate/literate.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1561,7 +1561,10 @@ <h2>Gathering all fragments</h2>
<code>HTML</code> as generated by the default rule. Before we can actually wrap that in our
<code>div</code> tags with the necessary tags we ajust the rendered <code>HTML</code> code to protect
fragment tags. Otherwise these will also be syntax colored, and that we don't
want.</p>
want. The fragment tag protection is explained in <code>&lt;&lt;fragment tag protector&gt;&gt;</code>.</p>
<p>For further cleanup of the rendered result any spans with comments in are
removed. These code comments are useful for the generated source code, but a
<strong>literate</strong> program otherwise already documents code thoroughly. Comment removal from the <code>HTML</code> rendition is done with <code>&lt;&lt;remove comments from HTML&gt;&gt;</code></p>
<p>The fence is skipped if its info contains the string <code>SETTINGS</code>, since that
denotes a configuration block as can be specified in <code>index.literate</code>. And the
configuration block is not intended to be visible in either resulting code nor
Expand All @@ -1575,6 +1578,7 @@ <h2>Gathering all fragments</h2>
<div class="code">
<pre><code>
<span class="literate-tag-name">&lt;&lt;fragment tag protector&gt;&gt;</span>
<span class="literate-tag-name">&lt;&lt;remove comments from HTML&gt;&gt;</span>

<span class="hljs-keyword">function</span> <span class="hljs-title function_">renderCodeFence</span>(<span class="hljs-params">tokens : Token[],
idx : <span class="hljs-built_in">number</span>,
Expand All @@ -1600,6 +1604,7 @@ <h2>Gathering all fragments</h2>
fileName = fileName || <span class="hljs-string">&#x27;&#x27;</span>;
fileName = fileName.<span class="hljs-title function_">trim</span>();
rendered = <span class="hljs-title function_">protectFragmentTags</span>(rendered);
rendered = <span class="hljs-title function_">removeCodeComments</span>(rendered);
rendered =
<span class="hljs-string">`&lt;div class=&quot;codefragment&quot;&gt;
&lt;div class=&quot;fragmentname&quot;&gt;&amp;lt;&amp;lt;<span class="hljs-subst">${name}</span>&amp;gt;&amp;gt;<span class="hljs-subst">${root}</span><span class="hljs-subst">${add}</span> <span class="hljs-subst">${fileName}</span>&lt;/div&gt;
Expand Down Expand Up @@ -1651,7 +1656,7 @@ <h2>Gathering all fragments</h2>
<div class="codefragment">
<div class="fragmentname">&lt;&lt;fragment tag protector&gt;&gt;= </div>
<div class="code">
<pre><code><span class="hljs-keyword">function</span> <span class="hljs-title function_">protectFragmentTags</span>(<span class="hljs-params">rendered : <span class="hljs-built_in">string</span></span>) {
<pre><code><span class="hljs-keyword">function</span> <span class="hljs-title function_">protectFragmentTags</span>(<span class="hljs-params">rendered : <span class="hljs-built_in">string</span></span>) : <span class="hljs-built_in">string</span> {
<span class="hljs-keyword">function</span> <span class="hljs-title function_">cleanHighlights</span>(<span class="hljs-params">match : <span class="hljs-built_in">string</span>, _: <span class="hljs-built_in">number</span>, __: <span class="hljs-built_in">string</span></span>)
{
<span class="hljs-keyword">let</span> internal = match.<span class="hljs-title function_">replaceAll</span>(<span class="hljs-variable constant_">FRAGMENT_HTML_CLEANUP_RE</span>, <span class="hljs-string">&quot;$2&quot;</span>);
Expand All @@ -1668,7 +1673,34 @@ <h2>Gathering all fragments</h2>
</div>
</div><p>In our CSS file we can now specify <code>.literate-tag-name</code> to say an italic font to
stand out in the code fences.</p>
<h2>Register the literate.process command</h2>
<h3>Remove code comments</h3>
<p>In rendered <code>HTML</code> code comments are wrapped in <code>span</code> tags with the class
<code>hljs-comment</code>. These can be on one line, or for comment blocks on multiple
lines. Since the goal is to remove these completely from rendered <code>HTML</code> the
regular expression for the match will be just to do that: match the span with
the <code>hljs-comment</code> even if it is over several lines. To do that we use also the
<code>s</code> modifier to the expression.</p>
<div class="codefragment">
<div class="fragmentname">&lt;&lt;fragment regular expressions&gt;&gt;=+ </div>
<div class="code">
<pre><code><span class="hljs-keyword">const</span> <span class="hljs-variable constant_">CODECOMMENT_HTML_RE</span>= <span class="hljs-regexp">/&lt;span class=&quot;hljs-comment&quot;&gt;.*?&lt;\/span&gt;/g</span>s;
</code></pre>

</div>
</div><p>The remove action becomes now a simple <code>replaceAll</code> on the rendered <code>HTML</code> using
the regular expression <code>CODECOMMENT_HTML_RE</code> with the empty string as
replacement.</p>
<div class="codefragment">
<div class="fragmentname">&lt;&lt;remove comments from HTML&gt;&gt;= </div>
<div class="code">
<pre><code><span class="hljs-keyword">function</span> <span class="hljs-title function_">removeCodeComments</span>(<span class="hljs-params">rendered : <span class="hljs-built_in">string</span></span>) : <span class="hljs-built_in">string</span> {
rendered = rendered.<span class="hljs-title function_">replaceAll</span>(<span class="hljs-variable constant_">CODECOMMENT_HTML_RE</span>, <span class="hljs-string">&quot;&quot;</span>);
<span class="hljs-keyword">return</span> rendered;
}
</code></pre>

</div>
</div><h2>Register the literate.process command</h2>
<p>The command <code>literate.process</code> is registered with Visual Studio Code. The
disposable that gets returned by <code>registerCommand</code> is held in
<code>literateProcessDisposable</code> so that we can push it into <code>context.subscriptions</code>.</p>
Expand Down
34 changes: 32 additions & 2 deletions literate/literate.literate
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1506,7 +1506,11 @@ If we have a match we prepare the `HTML` code to essentially wrap around the
`HTML` as generated by the default rule. Before we can actually wrap that in our
`div` tags with the necessary tags we ajust the rendered `HTML` code to protect
fragment tags. Otherwise these will also be syntax colored, and that we don't
want.
want. The fragment tag protection is explained in `<<fragment tag protector>>`.

For further cleanup of the rendered result any spans with comments in are
removed. These code comments are useful for the generated source code, but a
**literate** program otherwise already documents code thoroughly. Comment removal from the `HTML` rendition is done with `<<remove comments from HTML>>`

The fence is skipped if its info contains the string `SETTINGS`, since that
denotes a configuration block as can be specified in `index.literate`. And the
Expand All @@ -1521,6 +1525,7 @@ module import of `mermaid.js` to render diagrams expressed in these tags.
```ts : <<renderCodeFence rule>>=

<<fragment tag protector>>
<<remove comments from HTML>>

function renderCodeFence(tokens : Token[],
idx : number,
Expand All @@ -1546,6 +1551,7 @@ function renderCodeFence(tokens : Token[],
fileName = fileName || '';
fileName = fileName.trim();
rendered = protectFragmentTags(rendered);
rendered = removeCodeComments(rendered);
rendered =
`<div class="codefragment">
<div class="fragmentname">&lt;&lt;${name}&gt;&gt;${root}${add} ${fileName}</div>
Expand Down Expand Up @@ -1597,7 +1603,7 @@ on the match passed on to `cleanHighlights`. The result is used to wrap inside
the `span` with the `literate-name-tag` class.

```ts : <<fragment tag protector>>=
function protectFragmentTags(rendered : string) {
function protectFragmentTags(rendered : string) : string {
function cleanHighlights(match : string, _: number, __: string)
{
let internal = match.replaceAll(FRAGMENT_HTML_CLEANUP_RE, "$2");
Expand All @@ -1614,6 +1620,30 @@ function protectFragmentTags(rendered : string) {
In our CSS file we can now specify `.literate-tag-name` to say an italic font to
stand out in the code fences.

### Remove code comments

In rendered `HTML` code comments are wrapped in `span` tags with the class
`hljs-comment`. These can be on one line, or for comment blocks on multiple
lines. Since the goal is to remove these completely from rendered `HTML` the
regular expression for the match will be just to do that: match the span with
the `hljs-comment` even if it is over several lines. To do that we use also the
`s` modifier to the expression.

``` ts : <<fragment regular expressions>>=+
const CODECOMMENT_HTML_RE= /<span class="hljs-comment">.*?<\/span>/gs;
```

The remove action becomes now a simple `replaceAll` on the rendered `HTML` using
the regular expression `CODECOMMENT_HTML_RE` with the empty string as
replacement.

```ts : <<remove comments from HTML>>=
function removeCodeComments(rendered : string) : string {
rendered = rendered.replaceAll(CODECOMMENT_HTML_RE, "");
return rendered;
}
```

## Register the literate.process command

The command `literate.process` is registered with Visual Studio Code. The
Expand Down
8 changes: 7 additions & 1 deletion src/extension.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ const FRAGMENT_RE =
/(?<lang>[^:]*)(?<colon>:)?.*<<(?<tagName>.+)>>(?<root>=)?(?<add>\+)?\s*(?<fileName>.*\s+\$)?(?<extraSettings>\s+.*)?/;
const FRAGMENT_HTML_CLEANUP_RE= /(<span.class="hljs-.+?">)(.*?)(<\/span>)/g;
const FRAGMENT_HTML_RE= /(&lt;&lt;.+?&gt;&gt;)/g;
const CODECOMMENT_HTML_RE= /<span class="hljs-comment">.*?<\/span>/gs;

class FragmentNode extends vscode.TreeItem
{
Expand Down Expand Up @@ -333,7 +334,7 @@ export class FragmentHoverProvider implements vscode.HoverProvider {
}
}

function protectFragmentTags(rendered : string) {
function protectFragmentTags(rendered : string) : string {
function cleanHighlights(match : string, _: number, __: string)
{
let internal = match.replaceAll(FRAGMENT_HTML_CLEANUP_RE, "$2");
Expand All @@ -345,6 +346,10 @@ function protectFragmentTags(rendered : string) {
cleanHighlights
);
}
function removeCodeComments(rendered : string) : string {
rendered = rendered.replaceAll(CODECOMMENT_HTML_RE, "");
return rendered;
}

function renderCodeFence(tokens : Token[],
idx : number,
Expand All @@ -370,6 +375,7 @@ function renderCodeFence(tokens : Token[],
fileName = fileName || '';
fileName = fileName.trim();
rendered = protectFragmentTags(rendered);
rendered = removeCodeComments(rendered);
rendered =
`<div class="codefragment">
<div class="fragmentname">&lt;&lt;${name}&gt;&gt;${root}${add} ${fileName}</div>
Expand Down

0 comments on commit 147728a

Please sign in to comment.