1License 2------- 3 4Rarian is distributed under the GPL v2.0 (or later) license. Please see the 5COPYING file for full details. 6 7In addition, this package contains source code from the tinyxml project 8(www.sourceforge.net/projects/tinyxml). These files can be found in 9the util directory and have names beginning with "tiny". For their license 10terms, please refer to the indivual files. 11 12About Rarian 13----------- 14 15Rarian is designed to be a replacement for scrollkeeper. It is 16currently undergoing heavy development. As of writing, rarian can be 17installed in place of scrollkeeper and everything will work okay (as 18far as my testing indicates) 19 20The package consists of several things: 21 22* The librarian library 23 - This builds a list of available meta data files and allows access to these. 24 25* The rarian-sk-update script 26 - This is compatible with the scrollkeeper-update script that's required to 27 be run when installing new omf files. It converts the omf files into new- 28 style scrolls 29 30* The rarian-sk-migrate program 31 - Takes in a directory full of omf's, reads and parses them and spews out 32 an equivalent scroll file. You probably don't want to use this directly. 33 Instead, copy the omf directory to you're standard omf dir and run the 34 update script. 35 36* The rarian-example program 37 - Shows off what librarian is capable of. Prints a nice list of all 38 available documents found by the library. 39 40* Misc. rarian-sk-* scripts 41 - These emulate various functions of scrollkeeper as needed to 42 maintain backwards-compatibility. 43 44This package (the library part, at least) is based on the proposed Freedesktop 45Help System spec. The latest version of this spec can be found in the "help" 46subdirectory of this package. 47 48For major changes in 0.5 and above, please see the NEWS file. 49 50Major Changes in 0.4 51-------------------- 52 53Lots of changes in this version. I'll try and list as many as I can: 54* Change most things to support the spec. 55 - Use $XDG_DATA_DIRS and $XDG_DATA_HOME to find scroll files 56 - Use $LANGUAGE to decide which language to use 57 - Scan recursively through subdirs to pick up scrolls 58 - Allow locale-specific files to reside in $DIR/LOCALE/LC. Prioritise them 59 - Handle document sections. Allow docs to have as many sections as they want 60 - Remove the rubbish config file stuff 61 - Rename lots of key types 62 - Add support for lots more key types 63 - Handle URI and file paths properly 64* Remove previous migration script 65* Replace with update script which tracks changes (in 66 $OUTPUT_DIR/.rarian-update-mtimes) 67* Remove limit of 1024 chars per line 68* make calls to init implicit in operations 69* Add example of a Mallard Meta Data file, defining several sections, which 70 are spread across 1 document file and 1 section file 71* Fix a boatload of memory leaks 72* Added TODO to see what needs done 73* Add copy of spec to compare against 74 75Major Changes in 0.3 76-------------------- 77 78Only 1 really: Rarian can now be installed. If the right configure 79options are used. By default, it doesn't use the installation code 80stuff, it still relies on the uninstalled version. Look in the 81"Running it" section for how to get it installed etc. A config file 82is also generated which tells Rarian where to look for scrolls. It 83has a magic variable, HOME, which makes rarian look in the current 84user's home directory. Each path takes precedence over the older 85ones. If a scroll file is found in two paths, the one later in the 86config will replace the version found previously. 87 88Or better explanation: 89Config file specifies: /usr/share/rarian HOME/share/rarian 90Both have copies of beanstalk manual scroll. The only version that'll be 91reported is the one in HOME/share/rarian 92 93 94Major Changes in 0.2 95-------------------- 96 97* Scrolls are now translated in-file 98* All scrolls in data/sk-import are handled in the library init (but not 99recursively) 100* Add support for series_id and type in the Scroll struct 101* New and improved migration script - faster, cope with translations. It works 102 on the assumption that all files of the form <entry>-<lang>.omf are 103 translations and any other <entry>s are from different docs. 104 105Running it 106---------- 107 108In uninstalled (safe) mode 109-------------------------- 110 111To try it out, run 112./configure && make 113from the command line, in the top-level directory. Then: 114chmod u+x utils/rarian-sk-update 115./util/rarian-sk-update -o /usr/share/omf -r ./data/sk-import 116 117will make a temporary migration of all scrollkeeper omf files in 118/usr/share/omf. The scrolls can be found in data/sk-import. If you're omf 119files are not stored in /usr/share/omf, you need to edit the -o option to the 120correct path. 121 122If this step fails for some reason, fix the problem (if possible), let me know 123what went wrong and re-run the script. 124 125Once that's done, you can run: 126./util/rarian-example 127to build the in-memory index and iterate through, printing out each manuals 128filename. 129 130You can change the language used by changing the LANGUAGE environment variable: 131LANGUAGE=es ./util/rarian-example 132will print out the Spanish manuals. If a document doesn't have a translation, 133the default is to fall back to the C locale and use that (the same as 134scrollkeeper works), hence you'll see a lot of English in that list. 135 136You can also specify multiple fallback languages by specifying them in $LANGUAGE 137using colon seperation: 138LANGUAGE=es:de:en_GB 139("C" locale will always be used as a final fallback). 140 141In installed (unsafe) mode 142-------------------------- 143 144To get Rarian in an installed mode, the configure flag '--enable-installed' must 145be used. On top of this, there are the usual options (prefix etc.) 146that can be used. By default, when installed, it'll try converting the 147<prefix>/share/omf directory to scrolls stored in <prefix>/share/rarian. This 148can be changed using 149--with-convert-dir=/path/to/current/omfs 150 151All the programs / scripts get installed (rarian-example, 152rarian-sk-migrate and rarian-sk-update). To test, run the rarian-example with 153(or without) the LANGUAGE environmental variable set. The update script can 154also be used at any point using: 155rarian-sk-update 156Without any options, this will convert the covnert-dir specified during 157configuration. To convert a different directory, use 158rarian-sk-update -o <path/to/omfs> 159You can also regenerate all scroll files using the 160--clean-index 161parameter for the update script. 162To put the resulting scroll files in a different location (i.e. not 163<prefix>/share/help), use the parameter: 164-r <path/to/resultant/dir> 165 166Timings 167------- 168 169The following times are from my test-runs. They are all run with warm cache. 170I've not run them with cold cache for various reasons. 171 172Running update script to create a new, clean index: 173real 0m9.302s 174real 0m6.003s 175real 0m6.076s 176 177Running update script when nothing has changed: 178real 0m3.757s 179real 0m3.688s 180 181Running rarian-example: 182(between 0 and 6 languages specified in LANGUAGES) 183real 0m0.040s 184real 0m0.039s 185real 0m0.035s 186 187What's next? 188----------- 189 190Please see the TODO file. 191