www/news/asciidoctor_to_rss.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4 <link rel="stylesheet" href="https://wpitchoune.net/style.css">
   5 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">
   6 <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script>
   7 <script src="https://wpitchoune.net/nav.js"></script>
   8 <title>Asciidoctor to RSS</title>
   9 </head>
  10 <body>
  11 <div id='header'>
  12 <h1>Asciidoctor to RSS</h1>
  13 </div><div id='content'>
  14 <div class='date'>2016-11-07</div><div id="preamble">
  15 <div class="sectionbody">
  16 <div class="paragraph">
  17 <p>In order to ease the edition of this website and
  18 the management of the server, I want it to be purely
  19 static and generated from <a href="http://asciidoctor.org">Asciidoctor</a> documents.</p>
  20 </div>
  21 <div class="paragraph">
  22 <p>The <em>news</em> part of the website is also written as Asciidoctor
  23 documents, <code>asciidoctor_to_rss</code> is converting them into static
  24 HTML pages and generates a RSS 2.0 file.</p>
  25 </div>
  26 </div>
  27 </div>
  28 <div class="sect1">
  29 <h2 id="_installation_of_asciidoctor_to_rss">Installation of asciidoctor_to_rss</h2>
  30 <div class="sectionbody">
  31 <div class="paragraph">
  32 <p>It is required to install:</p>
  33 </div>
  34 <div class="ulist">
  35 <ul>
  36 <li>
  37 <p><a href="http://maven.apache.org/download.cgi">Apache Maven</a> (3.3.9)</p>
  38 </li>
  39 <li>
  40 <p><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java</a> (Sun JDK &gt;=1.8)</p>
  41 </li>
  42 </ul>
  43 </div>
  44 <div class="paragraph">
  45 <p>The sources can be retrieved from GIT:</p>
  46 </div>
  47 <div class="listingblock">
  48 <div class="content">
  49 <pre>git clone git clone https://git.wpitchoune.net/asciidoctor_to_rss.git</pre>
  50 </div>
  51 </div>
  52 <div class="paragraph">
  53 <p>Compilation:</p>
  54 </div>
  55 <div class="listingblock">
  56 <div class="content">
  57 <pre>cd asciidoctor_to_rss
  58 mvn clean install</pre>
  59 </div>
  60 </div>
  61 </div>
  62 </div>
  63 <div class="sect1">
  64 <h2 id="_howto_write_news">Howto write news</h2>
  65 <div class="sectionbody">
  66 <div class="paragraph">
  67 <p>Each <em>news</em> must be written in an <a href="http://asciidoctor.org">Asciidoctor</a> document
  68 and all documents must be dropped into a directory.</p>
  69 </div>
  70 <div class="paragraph">
  71 <p>There is not any restriction concerning the syntax because
  72 the utility is based on the Java bridge of Asciidoctor.
  73 I have added an attribute <code>date</code> which allows the utility
  74 to know the publication date of the news.</p>
  75 </div>
  76 <div class="paragraph">
  77 <p>Here is an example of <em>news</em>:</p>
  78 </div>
  79 <div class="listingblock">
  80 <div class="content">
  81 <pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">= Asciidoctor to RSS
  82 Jean-Philippe Orsini &lt;jeanfi@gmail.com&gt;
  83 :date: 2016-11-07
  84 :icons: font
  85
  86 In order to ease the edition of this website and
  87 the management of the server, I want it to be purely
  88 static and generated from http://asciidoctor.org[Asciidoctor] documents.
  89
  90 The _news_ part of the website is also written as Asciidoctor
  91 documents, `asciidoctor_to_rss` is converting them into static
  92 HTML pages and generates a RSS 2.0 file.
  93
  94 == Installation of asciidoctor_to_rss
  95
  96 It is required to install:
  97
  98 * http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)
  99
 100 * http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK &gt;=1.8)</code></pre>
 101 </div>
 102 </div>
 103 <div class="paragraph">
 104 <p>You can see few examples at
 105 <a href="https://wpitchoune.net/gitweb/?p=www.git;a=tree;f=src/news;hb=HEAD" class="bare">https://wpitchoune.net/gitweb/?p=www.git;a=tree;f=src/news;hb=HEAD</a>.
 106 The source document of this <em>news</em> is at
 107 <a href="https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/news/asciidoctor_to_rss.adoc;hb=HEAD" class="bare">https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/news/asciidoctor_to_rss.adoc;hb=HEAD</a>.</p>
 108 </div>
 109 </div>
 110 </div>
 111 <div class="sect1">
 112 <h2 id="_configuration">Configuration</h2>
 113 <div class="sectionbody">
 114 <div class="paragraph">
 115 <p>The configuration file of <code>asciidoctor_to_rss</code> is text file containing key/value pairs.</p>
 116 </div>
 117 <div class="paragraph">
 118 <p>See an example at
 119 <a href="https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/asciidoctorrss.props;hb=HEAD" class="bare">https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/asciidoctorrss.props;hb=HEAD</a> .</p>
 120 </div>
 121 <div class="listingblock">
 122 <div class="content">
 123 <pre class="highlight"><code class="language-text" data-lang="text">feed.title=News
 124 feed.description=News of the wpitchoune.net website.
 125 feed.link=https://wpitchoune.net/news/feed.xml
 126 feed.baseurl=https://wpitchoune.net/news
 127
 128 html.header.file=src/header.html</code></pre>
 129 </div>
 130 </div>
 131 <div class="paragraph">
 132 <p><code>feed.title</code>: the title used for the feed, in the RSS 2.0 and <code>news.html</code> files.</p>
 133 </div>
 134 <div class="paragraph">
 135 <p><code>feed.description</code>: the description used in the RSS 2.0 file.</p>
 136 </div>
 137 <div class="paragraph">
 138 <p><code>feed.link</code>: URI of the RSS 2.0 file.</p>
 139 </div>
 140 <div class="paragraph">
 141 <p><code>feed.baseurl</code>: base URI where the HTML news files will be located.</p>
 142 </div>
 143 <div class="paragraph">
 144 <p><code>html.header.file</code>: the content of the denoted file will be added in the <code>head</code> block of
 145 the generated HTML documents.</p>
 146 </div>
 147 </div>
 148 </div>
 149 <div class="sect1">
 150 <h2 id="_run_the_utility">Run the utility</h2>
 151 <div class="sectionbody">
 152 <div class="paragraph">
 153 <p>The command line usage is:</p>
 154 </div>
 155 <div class="listingblock">
 156 <div class="content">
 157 <pre>asciidoctor_to_rss.sh &lt;IN_DIR&gt; &lt;OUT_DIR&gt; &lt;CFG_FILE&gt;</pre>
 158 </div>
 159 </div>
 160 <div class="paragraph">
 161 <p><code>IN_DIR</code>: the directory containing the news as Asciidoctor documents.</p>
 162 </div>
 163 <div class="paragraph">
 164 <p><code>OUT_DIR</code>: the output directory which contains all generated files.</p>
 165 </div>
 166 <div class="paragraph">
 167 <p><code>CFG_FILE</code>: the path to the configuration file.</p>
 168 </div>
 169 <div class="paragraph">
 170 <p>The <code>OUT_DIR</code> will contain:</p>
 171 </div>
 172 <div class="ulist">
 173 <ul>
 174 <li>
 175 <p>one HTML file for each Asciidoctor document,</p>
 176 </li>
 177 <li>
 178 <p>the <a href="https://wpitchoune.net/news/news.html"><code>news.html</code></a> file,</p>
 179 </li>
 180 <li>
 181 <p>and the <a href="https://wpitchoune.net/news/news.html"><code>feed.xml</code></a> file which is a feed
 182 compatible with RSS v2.0.</p>
 183 </li>
 184 </ul>
 185 </div>
 186 </div>
 187 </div></div></body>
 188 </html>