new post: rewrite-this-blog-generator

3 files changed, 264 insertions, 0 deletions

diff --git a/content/posts/2023-03-10/rewrite-this-blog-generator.xml b/content/posts/2023-03-10/rewrite-this-blog-generator.xml
new file mode 100644
index 0000000..1ed5328
--- /dev/null
+++ b/content/posts/2023-03-10/rewrite-this-blog-generator.xml
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<article xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0">
+  <info>
+    <title>このブログのジェネレータを書き直した</title>
+    <abstract>
+      このブログのジェネレータを書き直したので、やったことを書き記しておく。
+    </abstract>
+    <revhistory>
+      <revision>
+        <date>2023-03-10</date>
+        <revremark>公開</revremark>
+      </revision>
+    </revhistory>
+  </info>
+  <section xml:id="intro">
+    <title>はじめに</title>
+    <simpara>
+      このブログを構築するシステムを書き直したのは 2度目である。
+      元々立ち上げた当初は、静的サイトジェネレータである <link xl:href="https://gohugo.io/">Hugo</link> を使っていた。
+      それを <link xl:href="https://asciidoctor.org/">Asciidoctor</link> にいくつかのカスタムを加えた自前のジェネレータに移行したのが 2022年の11月ごろだ。
+      そして今回、スクラッチから書いた <link xl:href="https://deno.land/">Deno</link> 製のジェネレータに移行した。
+    </simpara>
+    <simpara>
+      この記事では、移行の理由などを (主に将来の私へ向けて) 書き記しておく。
+    </simpara>
+  </section>
+  <section xml:id="from-hugo-to-asciidoctor">
+    <title>Hugo から Asciidoctor へ</title>
+    <simpara>
+      最初に断っておくと、Hugo は大変に優れた静的サイトジェネレータである。移行の理由の大半は、自分でジェネレータを書きたかったからに他ならない。
+      実のところ、この記事を執筆している現在、自作ジェネレータは Hugo よりも機能が劣っている。
+      例えば、Hugo を使っていたころはサポートしていた RSS フィードの生成は、まだ実装できていない。
+    </simpara>
+    <simpara>
+      移行先のフォーマットとして AsciiDoc を選んだのは、Markdown よりも表現力に優れるからである。Markdown は広く使われている軽量マークアップ言語だが、以下のような欠点を持つ。
+    </simpara>
+    <simpara>
+      <itemizedlist>
+        <listitem>CommonMark では機能が貧弱である (例: 脚注、<code>id</code> 属性の付与)</listitem>
+        <listitem>拡張記法に実装間で互換性がない</listitem>
+        <listitem>メタデータ (公開日など) を埋め込む統一された方法がない</listitem>
+      </itemizedlist>
+    </simpara>
+    <simpara>
+      AsciiDoc は Markdown に比べると普及していないが、上記の欠点は克服している。
+    </simpara>
+    <simpara>
+      <itemizedlist>
+        <listitem>ブログを書くのに十分な表現力がある</listitem>
+        <listitem>フォーマットを拡張するときの記法があらかじめ定められている</listitem>
+        <listitem>メタデータを埋め込む統一された方法がある</listitem>
+      </itemizedlist>
+    </simpara>
+    <simpara>
+      なお、Hugo は AsciiDoc もサポートしているのだが、AsciiDoc を使う場合 Asciidoctor を別途インストールする必要があり、それならば最初から Asciidoctor でよかろうと移行を決めた。
+    </simpara>
+  </section>
+  <section xml:id="from-asciidoctor-to-my-own-generator">
+    <title>Asciidoctor から自前のジェネレータへ</title>
+    <simpara>
+      AsciiDoc は良いフォーマットだが、私には 1点不満があった。それは、高い表現力を担保するために記号が使い倒されており、エスケープが難しいという点だ (具体例を挙げたいのだが、何だったか覚えていない)。これは、多種多様な記号類を入力する必要のある技術ブログにとっては辛い問題である。この問題を解決するため、
+      <itemizedlist>
+        <listitem>表現力が高く、</listitem>
+        <listitem>文法が厳密であり、</listitem>
+        <listitem>簡単に実装できる</listitem>
+      </itemizedlist>
+      フォーマットが求められた。これに合致したのが、XML をベースとする <link xl:href="https://docbook.org/">DocBook</link> (今回使っているのは、そのサブセットである <link xl:href="https://tdg.docbook.org/tdg/sdocbook/5.1/">Simplified DocBook</link>) である。
+    </simpara>
+    <simpara>
+      実は、AsciiDoc と DocBook はおおよそ互換性がある。AsciiDoc で書かれた文書は (ほぼ) 情報ロスなしに DocBook へ変換でき、逆もまたしかりである。
+      よって、DocBook には、AsciiDoc と同等の表現力がある。
+    </simpara>
+    <simpara>
+      XML の文法の厳密さについては、説明するまでもないだろう。また、単純な文法であることから実装が容易であり、事実上 Asciidoctor へロックインされる AsciiDoc とは異なり、さまざまな言語で多くのライブラリが存在する。
+    </simpara>
+    <simpara>
+      今回は、XML のパース自体も自分で書いている (これは何となく書きたかったからであり、合理的な理由があるわけではない。実装はサボりまくっているので XML のコメントが使えないといった制限がある)。
+    </simpara>
+    <simpara>
+      XML という機械処理しやすいフォーマットを選ぶことには、機械的な変換や検査といった処理がおこないやすくなるといった利点もある。
+      欠点は軽量マークアップ言語と比べて冗長であることだが、書く際は補完などを用いるのでそれほど気にならない。
+      結局のところ、技術ブログの執筆を律速するのは調査と文章の記述であり、マークアップの手段は執筆時間に大した影響を与えない。
+    </simpara>
+  </section>
+  <section xml:id="outro">
+    <title>おわりに</title>
+    <simpara>
+      2度のリライトを経て、記事のフォーマットとサイトジェネレータを上から下まで掌握した。
+      今後も改善のアイデアは多数あるので、じわじわと進めていきたいところだ。
+    </simpara>
+    <simpara>
+      最後にもう一度書くのだが、Hugo は大変に優れた静的サイトジェネレータである。
+      無駄な拘りがなければこれを使うとよい。
+      私は無駄に拘ったので、ブログの記事を書く時間を潰してブログシステムを作ってしまった。
+    </simpara>
+  </section>
+</article>
diff --git a/public/posts/2023-03-10/rewrite-this-blog-generator/index.html b/public/posts/2023-03-10/rewrite-this-blog-generator/index.html
new file mode 100644
index 0000000..ba5deb9
--- /dev/null
+++ b/public/posts/2023-03-10/rewrite-this-blog-generator/index.html
@@ -0,0 +1,153 @@
+<!DOCTYPE html>
+<html lang="ja-JP">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="author" content="nsfisis">
+    <meta name="copyright" content="&copy; 2023 nsfisis">
+    <meta name="description" content="このブログのジェネレータを書き直したので、やったことを書き記しておく。">
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg">
+    <title>このブログのジェネレータを書き直した | REPL: Rest-Eat-Program Loop</title>
+    <link rel="stylesheet" href="/hl.css?h=208c52e3b7c9db1cad782c5d30b4698f">
+    <link rel="stylesheet" href="/style.css?h=779b1a3debcaeba619f6fe500e93d525">
+    <link rel="stylesheet" href="/custom.css?h=38829d5e1dc8776c51bbc34984de8807">
+  </head>
+  <body class="single">
+    <header class="header">
+      <nav class="nav">
+        <p class="logo">
+          <a href="/">REPL: Rest-Eat-Program Loop</a>
+        </p>
+      </nav>
+    </header>
+    <main class="main">
+      <article class="post-single">
+        <header class="post-header">
+          <h1 class="post-title">このブログのジェネレータを書き直した</h1>
+        </header>
+        <div class="post-content">
+          <section>
+            <h2 id="changelog">更新履歴</h2>
+            <ol>
+              <li class="revision">
+                <time datetime="2023-03-10">2023-03-10</time>: 公開
+              </li>
+            </ol>
+          </section>
+          <section id="section--intro">
+            <h2><a href="#section--intro">はじめに</a></h2>
+            <p>
+              このブログを構築するシステムを書き直したのは 2度目である。 元々立ち上げた当初は、静的サイトジェネレータである<a xl:href="https://gohugo.io/">Hugo</a>を使っていた。 それを<a xl:href="https://asciidoctor.org/">Asciidoctor</a>にいくつかのカスタムを加えた自前のジェネレータに移行したのが 2022年の11月ごろだ。 そして今回、スクラッチから書いた<a xl:href="https://deno.land/">Deno</a>製のジェネレータに移行した。
+            </p>
+            
+            <p>
+              この記事では、移行の理由などを (主に将来の私へ向けて) 書き記しておく。
+            </p>
+          </section>
+          
+          <section id="section--from-hugo-to-asciidoctor">
+            <h2><a href="#section--from-hugo-to-asciidoctor">Hugo から Asciidoctor へ</a></h2>
+            <p>
+              最初に断っておくと、Hugo は大変に優れた静的サイトジェネレータである。移行の理由の大半は、自分でジェネレータを書きたかったからに他ならない。 実のところ、この記事を執筆している現在、自作ジェネレータは Hugo よりも機能が劣っている。 例えば、Hugo を使っていたころはサポートしていた RSS フィードの生成は、まだ実装できていない。
+            </p>
+            
+            <p>
+              移行先のフォーマットとして AsciiDoc を選んだのは、Markdown よりも表現力に優れるからである。Markdown は広く使われている軽量マークアップ言語だが、以下のような欠点を持つ。
+            </p>
+            
+            <p>
+              <ul>
+                <li>
+                  CommonMark では機能が貧弱である (例: 脚注、<code>id</code>属性の付与)
+                </li>
+                
+                <li>
+                  拡張記法に実装間で互換性がない
+                </li>
+                
+                <li>
+                  メタデータ (公開日など) を埋め込む統一された方法がない
+                </li>
+              </ul>
+            </p>
+            
+            <p>
+              AsciiDoc は Markdown に比べると普及していないが、上記の欠点は克服している。
+            </p>
+            
+            <p>
+              <ul>
+                <li>
+                  ブログを書くのに十分な表現力がある
+                </li>
+                
+                <li>
+                  フォーマットを拡張するときの記法があらかじめ定められている
+                </li>
+                
+                <li>
+                  メタデータを埋め込む統一された方法がある
+                </li>
+              </ul>
+            </p>
+            
+            <p>
+              なお、Hugo は AsciiDoc もサポートしているのだが、AsciiDoc を使う場合 Asciidoctor を別途インストールする必要があり、それならば最初から Asciidoctor でよかろうと移行を決めた。
+            </p>
+          </section>
+          
+          <section id="section--from-asciidoctor-to-my-own-generator">
+            <h2><a href="#section--from-asciidoctor-to-my-own-generator">Asciidoctor から自前のジェネレータへ</a></h2>
+            <p>
+              AsciiDoc は良いフォーマットだが、私には 1点不満があった。それは、高い表現力を担保するために記号が使い倒されており、エスケープが難しいという点だ (具体例を挙げたいのだが、何だったか覚えていない)。これは、多種多様な記号類を入力する必要のある技術ブログにとっては辛い問題である。この問題を解決するため、
+              <ul>
+                <li>
+                  表現力が高く、
+                </li>
+                
+                <li>
+                  文法が厳密であり、
+                </li>
+                
+                <li>
+                  簡単に実装できる
+                </li>
+              </ul>
+              フォーマットが求められた。これに合致したのが、XML をベースとする<a xl:href="https://docbook.org/">DocBook</a>(今回使っているのは、そのサブセットである<a xl:href="https://tdg.docbook.org/tdg/sdocbook/5.1/">Simplified DocBook</a>) である。
+            </p>
+            
+            <p>
+              実は、AsciiDoc と DocBook はおおよそ互換性がある。AsciiDoc で書かれた文書は (ほぼ) 情報ロスなしに DocBook へ変換でき、逆もまたしかりである。 よって、DocBook には、AsciiDoc と同等の表現力がある。
+            </p>
+            
+            <p>
+              XML の文法の厳密さについては、説明するまでもないだろう。また、単純な文法であることから実装が容易であり、事実上 Asciidoctor へロックインされる AsciiDoc とは異なり、さまざまな言語で多くのライブラリが存在する。
+            </p>
+            
+            <p>
+              今回は、XML のパース自体も自分で書いている (これは何となく書きたかったからであり、合理的な理由があるわけではない。実装はサボりまくっているので XML のコメントが使えないといった制限がある)。
+            </p>
+            
+            <p>
+              XML という機械処理しやすいフォーマットを選ぶことには、機械的な変換や検査といった処理がおこないやすくなるといった利点もある。 欠点は軽量マークアップ言語と比べて冗長であることだが、書く際は補完などを用いるのでそれほど気にならない。 結局のところ、技術ブログの執筆を律速するのは調査と文章の記述であり、マークアップの手段は執筆時間に大した影響を与えない。
+            </p>
+          </section>
+          
+          <section id="section--outro">
+            <h2><a href="#section--outro">おわりに</a></h2>
+            <p>
+              2度のリライトを経て、記事のフォーマットとサイトジェネレータを上から下まで掌握した。 今後も改善のアイデアは多数あるので、じわじわと進めていきたいところだ。
+            </p>
+            
+            <p>
+              最後にもう一度書くのだが、Hugo は大変に優れた静的サイトジェネレータである。 無駄な拘りがなければこれを使うとよい。 私は無駄に拘ったので、ブログの記事を書く時間を潰してブログシステムを作ってしまった。
+            </p>
+          </section>
+        </div>
+      </article>
+    </main>
+    <footer class="footer">
+      &copy; 2021 nsfisis
+    </footer>
+  </body>
+</html>
diff --git a/public/posts/index.html b/public/posts/index.html
index d04ded2..bfaf834 100644
--- a/public/posts/index.html
+++ b/public/posts/index.html
@@ -25,6 +25,20 @@
         <h1>投稿一覧</h1>
       </header>
       <article class="post-entry">
+        <a href="/posts/2023-03-10/rewrite-this-blog-generator/">          <header class="entry-header">
+            <h2>このブログのジェネレータを書き直した</h2>
+          </header>
+          <section class="entry-content">
+            <p>
+              このブログのジェネレータを書き直したので、やったことを書き記しておく。
+            </p>
+          </section>
+          <footer class="entry-footer">
+            Posted on<time datetime="2023-03-10">2023-03-10</time>
+          </footer>
+</a>
+      </article>
+      <article class="post-entry">
         <a href="/posts/2023-01-10/phperkaigi-2023-unused-token-quiz-3/">          <header class="entry-header">
             <h2>PHPerKaigi 2023: ボツになったトークン問題 その 3</h2>
           </header>