prepare changelog for 1.1.0
[enigma2-curlytx.git] / README.rst
1 *******
2 CurlyTx
3 *******
4 Enigma2 (Dreambox) plugin that lets you view the contents of remote
5 *plain text* files, e.g. HTTP URLs.
6
7 Multiple URLs can be configured and navigated.
8
9 .. contents::
10    :depth: 2
11
12
13 ========
14 Features
15 ========
16 - Load any remote plain text files, e.g. via HTTP
17 - Unlimited number of remote URLs/pages
18 - Reload pages
19 - Non-blocking URL loading
20 - Show HTTP headers
21 - Configurable page titles
22 - Configurable text size
23 - Configurable default page
24 - Import complete page list from Atom feed
25 - Visible in the main menu or the extension menu (configurable)
26 - Configurable menu title
27 - Help screen for main window and settings window
28
29
30 =====
31 Usage
32 =====
33
34 First run
35 =========
36 After installing CurlyTx and restarting Enigma2, open the main menu.
37 The first entry will be "CurlyTx" - activate it.
38
39 You will see the main window with the message
40 "Go and add a page in the settings".
41 Do just that end press the red button to access the settings window.
42
43 Now we'll add the first URL:
44
45 - Press the yellow button ("New"); the "page edit" window will show up
46 - Enter the page URL, e.g. http://ip.cweiske.de
47 - If you wish, enter a page title, e.g. "My IP"
48 - Set the text size if you want. 20 is a good default value.
49 - Press the green button ("OK"), and you are back on the settings window.
50 - The page you have just created is in the configuration list now.
51
52
53 If you made a mistake and want to change it, select the page with the
54 up/down buttons and press "OK" - the page edit window will open.
55
56 Press the green button and the settings will be saved.
57 You're back on the main window now and the URL you just configured will be loaded.
58
59 Note that with version 1.1, CurlyTx supports opening local files.
60 Prepend them with ``file://``, e.g. ``file:///tmp/test.txt``.
61
62
63 Adding many pages
64 =================
65 You can use the settings window to add new pages, but this gets tedious if you
66 want to add many pages.
67
68 It's better to use the Atom feed import in this case.
69 All you need is a text editor and a web server you can serve the feed page with.
70
71 Here is an example feed::
72
73   <?xml version="1.0" encoding="utf-8"?>
74   <feed xmlns="http://www.w3.org/2005/Atom">
75    <title>URL list for CurlyTx</title>
76    <author>
77     <name>Christian Weiske</name>
78     <email>cweiske@cweiske.de</email>
79    </author>
80    <link rel="self" href="http://home.cweiske.de/pagefeed.atom"/>
81    <entry>
82     <id>ip</id>
83     <title>My IP</title>
84     <link rel="alternate" type="text/html" href="http://ip.cweiske.de/" />
85    </entry>
86    <entry>
87     <id>temp</id>
88     <title>House temperatures</title>
89     <link rel="alternate" type="text/html" href="http://home/temperatures.txt" />
90    </entry>
91   </feed>
92
93 Start CurlyTx, go to the settings and write the feed URL in the
94 "Page feed URL" field.
95 Then press "OK" and the feed's pages will be loaded into the settings window.
96
97
98 Local configuration file
99 ========================
100 CurlyTx looks for a local page feed file on the harddisk on every run,
101 at ``/etc/enigma2/curlytx-pagefeed.xml``.
102 If this file exists, it gets loaded unconditionally and overwrites
103 the current page configuration.
104
105
106 Disable settings
107 ================
108 The page feed file may contain a tag that disables the settings button.
109 By using it, you can prevent people from modifying the CurlyTx settings.
110
111 First, register the namespace::
112
113     <feed xmlns="http://www.w3.org/2005/Atom" xmlns:c="http://ns.cweiske.de/curlytx">
114
115 Then, add the setting after the author or self link::
116
117     <c:enableSettings>0</c:enableSettings>
118
119 Here is the example feed with disabled settings::
120
121   <?xml version="1.0" encoding="utf-8"?>
122   <feed xmlns="http://www.w3.org/2005/Atom" xmlns:c="http://ns.cweiske.de/curlytx">
123    <title>URL list for CurlyTx</title>
124    <author>
125     <name>Christian Weiske</name>
126     <email>cweiske@cweiske.de</email>
127    </author>
128    <link rel="self" href="http://home.cweiske.de/pagefeed.atom"/>
129    <c:enableSettings>0</c:enableSettings>
130    <entry>
131     <id>ip</id>
132     <title>My IP</title>
133     <link rel="alternate" type="text/html" href="http://ip.cweiske.de/" />
134    </entry>
135    <entry>
136     <id>temp</id>
137     <title>House temperatures</title>
138     <link rel="alternate" type="text/html" href="http://home/temperatures.txt" />
139    </entry>
140   </feed>
141
142
143 =================
144 Modifying CurlyTx
145 =================
146
147
148 Translation
149 ===========
150 Beginning a new translation
151 ---------------------------
152 Replace ``$lang_code`` with your two-letter language code::
153
154     $ cd po
155     $ cp messages.po $lang_code.po
156     ... edit $lang_code.po now
157     $ ./compile.sh
158
159
160 Editing an existing translation
161 -------------------------------
162 Simply run ::
163
164     $ cd po
165     $ ./update.sh
166
167 This will update the translation template ``messages.pot`` from the source code
168 and will merge the changes into the single translation files.
169
170
171 Testing a translation
172 ---------------------
173 Link your compiled translation file into ::
174
175     src/locale/$lang_code/LC_MESSAGES/CurlyTx.mo
176
177 Enigma2 will pick it up automatically.
178
179
180 Building
181 ========
182 First upgrade the version number in ``CONTROL/control``.
183
184 Then simply run ::
185
186     ./build.sh
187
188 Directory ``releases/`` will contain the freshly baked ``.ipk`` file that can
189 then be transferred to your dreambox, e.g. via ``scp``::
190
191     $ scp releases/enigma2-plugin-extensions-curlytx_2.3_mipsel.ipk dreambox:
192     $ ssh dreambox
193     $ ipkg install enigma2-plugin-extensions-curlytx_2.3_mipsel.ipk
194
195 You will need the ``ipkg-build`` script from
196  http://reichholf.net/files/dreambox/tools/ipkg-build
197
198 Also see http://dream.reichholf.net/wiki/Howto:IPK_Pakete_erstellen
199
200
201 Open issues / ideas
202 ===================
203 - move mode to re-order pages
204 - how to show clock in lcd?
205
206
207 =====
208 About
209 =====
210 Homepage
211 ========
212 https://open-dreambox.org/trac/dreambox/wiki/CurlyTx
213
214 Author
215 ======
216 Christian Weiske, `cweiske@cweiske.de`__
217
218 .. __: mailto:cweiske@cweiske.de
219
220 License
221 =======
222 The plugin is subject to the GPLv3_ or later.
223
224 Additional exception:
225   This plugin may be distributed and executed on hardware which is licensed by
226   Dream Multimedia GmbH.
227
228 .. _GPLv3: http://www.gnu.org/licenses/agpl.html