added tricks about the sound
[www.git] / src / news / asciidoctor_to_rss.adoc
1 = Asciidoctor to RSS
2 Jean-Philippe Orsini <jeanfi@gmail.com>
3 :date: 2016-11-07
4 :icons: font
5
6 In order to ease the edition of this website and
7 the management of the server, I want it to be purely
8 static and generated from http://asciidoctor.org[Asciidoctor] documents.
9
10 The _news_ part of the website is also written as Asciidoctor
11 documents, `asciidoctor_to_rss` is converting them into static
12 HTML pages and generates a RSS 2.0 file.
13
14 == Installation of asciidoctor_to_rss
15
16 It is required to install:
17
18 * http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)
19
20 * http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8)
21
22 The sources can be retrieved from GIT:
23
24 ----
25 git clone git clone https://git.wpitchoune.net/asciidoctor_to_rss.git
26 ----
27
28 Compilation:
29
30 ----
31 cd asciidoctor_to_rss
32 mvn clean install
33 ----
34
35 == Howto write news
36
37 Each _news_ must be written in an http://asciidoctor.org[Asciidoctor] document
38 and all documents must be dropped into a directory.
39
40 There is not any restriction concerning the syntax because
41 the utility is based on the Java bridge of Asciidoctor.
42 I have added an attribute `date` which allows the utility
43 to know the publication date of the news.
44
45 Here is an example of _news_:
46
47 [source, asciidoc]
48 ----
49 = Asciidoctor to RSS
50 Jean-Philippe Orsini <jeanfi@gmail.com>
51 :date: 2016-11-07
52 :icons: font
53
54 In order to ease the edition of this website and
55 the management of the server, I want it to be purely
56 static and generated from http://asciidoctor.org[Asciidoctor] documents.
57
58 The _news_ part of the website is also written as Asciidoctor
59 documents, `asciidoctor_to_rss` is converting them into static
60 HTML pages and generates a RSS 2.0 file.
61
62 == Installation of asciidoctor_to_rss
63
64 It is required to install:
65
66 * http://maven.apache.org/download.cgi[Apache Maven] (3.3.9)
67
68 * http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java] (Sun JDK >=1.8)
69 ----
70
71 You can see few examples at
72 https://wpitchoune.net/gitweb/?p=www.git;a=tree;f=src/news;hb=HEAD.
73 The source document of this _news_ is at
74 https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/news/asciidoctor_to_rss.adoc;hb=HEAD.
75
76 == Configuration
77
78 The configuration file of `asciidoctor_to_rss` is text file containing key/value pairs.
79
80 See an example at
81 https://wpitchoune.net/gitweb/?p=www.git;a=blob;f=src/asciidoctorrss.props;hb=HEAD .
82
83 [source, text]
84 ----
85 feed.title=News
86 feed.description=News of the wpitchoune.net website.
87 feed.link=https://wpitchoune.net/news/feed.xml
88 feed.baseurl=https://wpitchoune.net/news
89
90 html.header.file=src/header.html
91 ----
92
93 `feed.title`: the title used for the feed, in the RSS 2.0 and `news.html` files.
94
95 `feed.description`: the description used in the RSS 2.0 file.
96
97 `feed.link`: URI of the RSS 2.0 file.
98
99 `feed.baseurl`: base URI where the HTML news files will be located.
100
101 `html.header.file`: the content of the denoted file will be added in the `head` block of
102 the generated HTML documents.
103
104 == Run the utility
105
106 The command line usage is:
107
108 ----
109 asciidoctor_to_rss.sh <IN_DIR> <OUT_DIR> <CFG_FILE>
110 ----
111
112 `IN_DIR`: the directory containing the news as Asciidoctor documents.
113
114 `OUT_DIR`: the output directory which contains all generated files.
115
116 `CFG_FILE`: the path to the configuration file.
117
118 The `OUT_DIR` will contain:
119
120 * one HTML file for each Asciidoctor document,
121
122 * the https://wpitchoune.net/news/news.html[`news.html`] file,
123
124 * and the https://wpitchoune.net/news/news.html[`feed.xml`] file which is a feed
125   compatible with RSS v2.0.