tazpkg view README.devel @ rev 958

Add Italian; make pot; make msgmerge; make clean
author Aleksej Bobylev <al.bobylev@gmail.com>
date Tue Jan 30 11:49:21 2018 +0200 (2018-01-30)
parents bbc6b0a453a7
children
line source
1 README file for TazPkg developers
2 =================================
5 Desktop integration
6 -------------------
8 mimeapps.list: this file deprecated and not installed
9 https://wiki.archlinux.org/index.php/Default_applications
10 (Also, defaults.list deprecated.)
12 MIME-type "x-scheme-handler/tazpkg" already listed in the tazpkg-url.desktop
15 Categories for .desktop files are listed here:
16 http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html
18 tazpanel-pkgs.desktop: sub-category PackageManager -> category Settings
21 TazPkg modules
22 --------------
24 About 4,000 lines of code is too big to effectively maintain in a single file.
26 Linux way [https://en.wikibooks.org/wiki/Linux_Guide/How_Linux_Works]:
27 > The Linux Way can be summarized as:
28 > * Use programs that do only one task, but do it well.
29 > * To accomplish complex tasks, use several programs linked together.
30 > * Store information in human-readable plain text files whenever it is
31 > possible.
32 > * There is no "one true way" to do anything.
33 > * Prefer commandline tools over graphical tools.
35 It is decided to split single tazpkg code into a few independent modules.
37 Goals: not to scroll thousands of lines to move back and forth to the internal
38 tazpkg functions and to the main tazpkg code; knowledge that single code
39 changing in the one place will not have side effects in the other place; reduce
40 the barrier to entry for new developers.
43 Best place to fit tazpkg modules is /usr/libexec directory.
44 http://www.linuxbase.org/betaspecs/fhs/fhs/ch04s07.html
46 > /usr/libexec includes internal binaries that are not intended to be executed
47 > directly by users or shell scripts. Applications may use a single subdirectory
48 > under /usr/libexec.
50 > Applications which use /usr/libexec in this way must not also use /usr/lib to
51 > store internal binaries, though they may use /usr/lib for the other purposes
52 > documented here.
54 So, the directory for tazpkg modules is /usr/libexec/tazpkg/.
55 It is out of the PATH, so modules will not interfere with original Linux
56 commands and will not autocomplete in the terminal. Nothing changed with the
57 user experience: it is still single tazpkg.
60 To execute module we need to know full path to the module.
61 We can use simple names for modules such as "help", "convert", "list", etc.
64 Directory variables
65 -------------------
67 Many programs can be configured using variables such as prefix, docdir, etc.:
68 make prefix=/usr install
70 All variables are in lower case (only DESTDIR is in upper case). See more here:
71 https://www.gnu.org/prep/standards/html_node/Directory-Variables.html
73 Makefile contains variables support with default values.
74 Default prefix=/usr, all other variables are defaults to values described
75 at the given link.
78 Code commenting
79 ---------------
81 Developer comments are very important to understand how the program works.
82 But these comments are useless to the end user and they just increase the size
83 of the scripts without making any changes to the script business logic. It also
84 increases the size of the scripts that includes shared "libs" such as libtaz.sh.
86 We can strip all the comments from installed scripts, leaving those comments
87 for developers in the SliTaz Hg repositories.
89 We need only to leave "#!/bin/sh" line and one or two lines of comments describing
90 what it is and where you can find the original scripts if you want to develop
91 them.
94 Tests
95 -----
97 Tests are the important part of the development process. TazPkg development is
98 not easy. We have no automated tests at the moment. Only we can do manual tests,
99 but even we have no check-list.
101 To test tazpkg effectively we need two sorts of the tests. One set of the tests
102 we can reproduce in the local file system (inside special prepared chroot
103 environment). For other tests we need a special test-server that provides special
104 +test cases (emulate package database changes), this also provides both main and few
105 +undigest repositories. We can set up special scripts and test repositories on the
106 existing server (cook.slitaz.org).
109 HTML terminal converter
110 -----------------------
112 In the module "help" was an attempt to write code that could easily display the
113 HTML-help in a terminal. The idea is to re-use TazPkg help files, which are
114 intended for display in the browser.
116 I'll tell you about the most interesting and complex part of the script that
117 starts like this:
119 PRE=$(echo "$HLP" | sed ...
121 Here $HLP is a part of the HTML page that we are going to show. Next the chain
122 of sed commands are transformed in this HTML source in the next way.
124 * `/^$/d;` remove blank lines;
125 * `/<pre>/,/<\/pre\>/{s|.*|  &|; s| |·|g};` prepend lines within <pre>*</pre>
126 tags with two unbreakable spaces, temporarily change spaces to middle dot;
127 * `s|^  </*pre>$||; s|<pre>||; s|</pre>||;` remove "<pre>" tags;
128 * `s|  ·#|  #|;` remove specified extra-space (converted to middle dot);
129 * `tr '\n' ' '` convert all the newlines to spaces. Now we get one long line.
130 Note that we already marked beginning of the pre-lines with two unbreakable
131 spaces;
132 * `s|[ ][ ]*| |g;` combine all the successive spaces and/or tabs into
133 single space;
134 * `s|[ ]*<dl>|O\n|g;` change opening tag "<dl>" into "O<backspace>".
135 Note, here and below I use "<backspace>" character because later I'll break
136 long lines using function "longline()" from libtaz.sh, which in turn uses
137 Busybox function "fold". In the final step sequences like "O<backspace>"
138 will be changed to "invisible" color codes, and they should have "zero
139 width" when they are processed by `fold` to break long lines in the right
140 places. Fortunately, Busybox `fold` knows about "<backspace>" character and
141 processes it correctly, so sequence like "O<backspace>" have "zero width"
142 for `fold`;
143 * `s|[ ]*</dl>|L\n|g;` change closing tag "</dl>" into "L<backspace>";
144 * `s|[ ]*</*dt>||g;` remove opening and closing tags "<dt>";
145 * `s|[ ]*<dd>| |g; s|</dd>|\n|g;` now lines within tags "<dd>" are
146 prepended by tabulation;
147 * `s|<h4>|<b>|g; s|</h4>|</b>\n|g` change header "<h4>" into separate line
148 with code `<b>...</b>\n`;
149 * `s|[ ]*<p>[ ]*||g;` remove opening tag "<p>" both with extra-space;
150 * `s|[ ]*</p>|\n \n|g;` remove closing tag "</p>" and append it with
151 "<newline><single unbreakable space><newline>";
152 * `s|  |\n  |g` prepend each line of the <pre> block (marked before with the
153 double unbreakable spaces) with <newline>;
154 * Now we have: individual lines prepended by two unbreakable spaces for <pre>
155 block, individual lines for paragraphs, as well for content of "<dt>" tag,
156 individual lines prepended by tabulation for content of "<dd>" tag,
157 individual lines "O<backspace>" and "L<backspace>" for begin and end of the
158 "<dl>" block;
159 * `s|<a [^>]*>||g; s|</a>||g;` remove links, leaving only link text;
160 * `s|·| |g` change back middle dots into spaces;
161 * `s|</*nobr>||g; s|&shy;||g;` remove tags "<nobr>" and soft hyphens;
162 * `s|^[ ]*||` remove space in the beginning of each line;
163 * `/^$/d` remove empty lines. Note, we already have line with the single
164 unbreakable space as separator between paragraphs;
165 * `s|<tt>|A|g; s|<code>|A|g;` change open tags to "A<backspace>"; in the
166 final step it will be changed to the color code;
167 * `s|<em>|B|g; s|<strong>|B|g;` other color code;
168 * `s|</tt>|D|g; s|</code>|D|g; s|</em>|D|g;` here will be code that
169 cancel previous color code;
170 * `s|DD|D|g;` clean doubles.