rbt 0.11.118

data/doc/deprecated/deprecated_rbt.cgi

@@ -0,0 +1,2409 @@
+# =========================================================================== #
+# === Tutorial
+#
+# This is the old and deprecated webpage for the RBT project. Any still
+# relevant content should be carried into the new format stored at
+# README.gen.
+#
+# It has a table of contents since at least Feb 2014.
+# =========================================================================== #
+    header_stylish_brown 'The RubyBuildTools Tutorial', 'gold'
+    header_stylish_brown 'Project :: Ruby Build Tools'
+
+Welcome to this Tutorial
+
+This tutorial has a fairly simple goal, which is to try to teach other human
+beings how to use the <b class="orange">RubyBuildTools (RBT)</b>.
+
+It also has a secondary goal, which is to provide some reasoning
+and motivation for having created this project.
+
+Reworded differently, this tutorial should provide you with 
+an understanding how the RBT project may be useful for you you.'
+
+This document here is essentially an introduction to the possibilities
+of what can be done with the <b>RBT-scripts</b>. It will also show a
+lot of specific examples, usually for use in the commandline. Ideally
+though, we can also make use of RBT through a GUI interface or the
+WWW.
+
+The above would, on the commandline, tell you which version of
+the RBT scripts you are currently using. At the time of writing this
+tutorial, the current version was <>+RBT.version?.to_s+'</b>.
+
+In the event that you do happen to find a bug, it would be 
+appreciated if said bug could be reported on the
+github-issue tracker at
+
+<a href="https://github.com/shevegen/rbt" class="slateblue marl2em">
+  https://github.com/shevegen/rbt/issues
+</a>
+
+or via email to me at 
+<b class="yel">+Roebe.email?+</b> directly.
+
+All bug reports will additionally be stored in a local file, a
+"todo" file if you so will. This makes it easier for me to work
+through different issues one at a time - and sometimes postpone
+if things may be too hard to solve or take too long to implement.
+
+One important aspect of this tutorial is, regardless over
+whether you are a "newbie" or a "knowbie", to understand how
+things work, the reasoning behind them, how they can be used
+and how they can be applied to help you in your endeavours.'
+
+The RBT Project appreciates having knowledgable users - there
+should not be any artificial separation between "developers" and
+"users", because in the end, knowledge should be made available
+for everyone, at their own discretion, how they wish to apply
+it.'
+
+In the event that you think that the tutorial is missing 
+out some important information, report this as well please,
+so that this part of the Tutorial can be improved.',
+'marl1em BLOCK'
+
+e "Now, without further ado, let's get started."
+
+header_stylish_brown sg(:gitarre,'marr5px')+
+'  Installing the RBT gem', '','margin-left:1em;margin-top:1px;'
+p {
+  You may have to first download and install one gem, the
+  configuration gem.'
+  
+wget http://shevegen.square7.ch/configuration-1.0.18.gem'
+gem install ./configuration-1.0.18.gem'
+  
+  Next, try to install the rbt gem:
+  
+gem install rbt'
+  
+}
+header_stylish_brown sg(:gitarre,'marr5px')+
+'  Introduction', '','margin-left:1em;margin-top:1px;'
+
+p {
+  One of the main design decisions behind the 
+  <span class="crimson">Ruby Build Tools (RBT)</span> 
+  Project is to remain <b>extremely flexible</b>.'
+  
+  That means that there will be no "one way to use them".'
+  
+  There will be multiple ways and you can pick whatever way
+  suits you the most. Different paradigms may coexist with
+  one another. For instance, there is a class that allows
+  one to compile from a single file, with just the remote
+  URLs listed in that file.
+  
+  The RBT scripts will strive to remain logical, and
+  consistent.
+  
+  Complexity is ideally kept to a minimum, giving explanations
+  whenever possible, so that the user is in full control over
+  every decision in the end.
+  
+  One example for this can be noticed for commandline
+  options:
+  
+  If a long option is called 
+  <b class="green">"--skip-extracting"</b> or
+  <b class="green">"skip_extracting"</b>, then a shortcut like 
+  <b class="green">"se"</b> will - and should - work exactly 
+  as the longer version. This is valid for every commandline 
+  option - there are many aliases to them. So, if you see
+  a long commandline option, you can also try a shorter
+  variant of that - and it should work. You can also omit
+  all "_" - they are just used to make it easier to read
+  the specific command at hand.'
+  <b class="FI">skipextracting</b> would work just the same.'
+} 
+p {
+  The whole RBT project consists of various scripts, scripts 
+  which are the culmination of a very interesting endeavour 
+  into the '+ string_link('http://www.gobolinux.org/', 
+  sg(:external,'marr4px')+'Gobolinux world',0,
+  'marr0px slateblue BO')+'.'
+  
+  This endeavour is explained in the following box 
+  <i>"History of the RBT Tools"</i>, which you can skip
+  if you are not interested in it.'
+}
+# ===================================================================== #
+# The History of the RBT Project.
+# ===================================================================== #
+div(id: 'history_of_the_rbt_project
+  e sg(:dokument,'marr8px')+'The History of the Ruby Build 
+  Tools [RBT] Project', 'header marl4em'
+  p('ind1em pad1em marl2em','',STANDARD_BORDER) {
+    le 'Back then - and I still am of this opinion even today
+    - I thought that shell scripts ultimately tend to grow in
+    complexity way faster and steeper than other programming
+    languages would do. They also lean towards becoming really
+    ugly to further extend with more code, at which point sooner
+    or later maintaining them is no more real fun anymore. And
+    when it is no fun to maintain something, you start to lose
+    interest and eventually cease maintaining it or adding
+    anything new to it.'
+    
+    le 'In Ruby the situation is a <b>lot</b> better, as you 
+    can (re)arrange functionality freely into classes and modules, 
+    extend these lateron easily, and use one of the various GUI 
+    bindings to present the user with an easy-to-use graphical 
+    solution.'
+    
+    le 'In my opinion, Ruby is a much better language than shell 
+    scripts and the logic found in such scripts. The GNU Sourcemage 
+    project is trying to use only bash scripts, and they dont really 
+    evolve quite much from my point of view. Users prefer
+    distributions like Archlinux for a reason.'
+    le 'Big software projects will hardly ever be restricted to 
+    shell scripts - it is only the Linux world which still embraces 
+    this archaic concept of using ugly shell scripts.'
+    
+    le 'Also, well written Ruby code tends to be much nicer to read 
+    than the equivalent code in a shell script. Python code may be 
+    just as useful when compared to Shell Syntax, but since Ruby is
+    my main language, I chose to use Ruby rather than Python.'
+  }
+}
+p {
+  Let us reflect an important difference between a 
+  "traditional", and a "Gobolinux-like OS", because it is important 
+  to know about this difference with regards to using the 
+  <span class="crimson">RBT scripts</span>.'
+}
+p {
+  e sg(:dot7)+' A traditional system conforms (more or 
+  less) <b>completely</b> to the FHS standard, and thus uses 
+  /usr, /usr/lib and all the directories the FHS mandates one
+  to have.'
+  
+  This also means that the files of any given program will be 
+  spread around multiple locations and directories (/usr/bin, 
+  /usr/lib, /etc and so on). Most distributions conform to this 
+  setup, although sometimes they break the FHS standard (as did 
+  Sabayon on May 2009 when their LiveCD used /usr/qt/3)',
+  'marl2em'
+  
+  In my opinion this approach is slightly problematic and
+  not very elegant.'
+  
+  le 'You can not easily uninstall programs again unless you
+  use a package manager to help you (or somehow hope that
+  you can do "make uninstall").'
+  
+  e sg(:dot7)+' A GoboLinux like system uses a 
+  slightly different approach - the AppDir approach.
+  Every program is (or should be) self-contained in a single
+  directory and will then get symlinked into other locations,
+  into directories like /System, /Programs and so on. 
+  In a way this is similar to AppDirs, but it is also rare to
+  see in the UNIX world in general; I think only PC-BSD follows
+  a similar scheme, Whitix also follows a somewhat related model, 
+  and Mac OS-X also has a very similar scheme but focuses on 
+  a graphical approach with their AppDirs.','marl2em'
+}
+p {    
+  The <b class="ud">biggest advantage</b> is that this scheme 
+  is <span class="underline">a LOT</span> simpler to use, while 
+  remaining easy, pure and very clean.'
+  
+  If you want to remove a program, you just remove the 
+  <b>AppDir</b> directory.'
+  e "That's it basically."
+   
+  No need for a package manager to "sanitize" your system 
+  again. (Additionally, GoboLinux uses "legacy" symlinks to stay 
+  completely compatible with the FHS. These symlinks are by 
+  default hidden from the user and can be unhidden using 
+  "gobohide --unhide target".'
+  
+  It is often amusing to read posts of people claiming that
+  GoboLinux is not following the FHS - but every FHS-mapped
+  dir will in fact work just as well on GoboLinux, 
+  "cd /usr/bin", "cd /opt" and so forth - so in fact the 
+  statement that GoboLinux is fully FHS compliant is 100% true.'
+  The FHS does not forbid the use of symlinks, it merely
+  mandates that these directories need to be available at that
+  position, which they are.)','marl2em'
+  
+  More explanations will follow in detail lateron, 
+  but for now, just remember the <b class="yel ud">basic distinction</b> 
+  between a traditional, and a Gobolinux-like System (Gobolinux was
+  a pioneer in this area) lies in the <b>Filesystem layout</b>.'
+}
+header_stylish_brown 'Scope of the RubyBuildTools and Platforms'
+p {
+  Ultimately, the <span class="crimson">RBT tools</span> will not
+  be restricted to only run on Linux, they will work on different
+  platforms. However, the first concern will be to have them work
+  under Linux. Wherever Ruby works, the RBT scripts should work on
+  that platform as well.'
+  
+  For now please, use a terminal/shell and lets start.'
+  
+  Type or copy/paste the following (do not forget to
+  press the <b>enter key</b>):
+  
+rbt htop'
+   
+  If everything works, then you should be able to see some
+  information printed on to the screen. The RBT scripts are
+  compiling the application <b>htop</b> right now!'
+  
+  Once the scripts have finished compilation, you will be
+  notified as to where you can find the compiled files.'
+  
+  Note that since as of November 2013, you can also pass in
+  a full URL as argument.'
+  
+  That way, you can download from a remote site and immediately
+  continue from there.'
+  
+  Examples for the latter way:
+  
+rbt http://ftp.gnome.org/pub/GNOME/sources/jhbuild/3.10/jhbuild-3.10.0.tar.xz'
+rbt https://downloads.sourceforge.net/project/open-cobol/open-cobol/1.1/open-cobol-1.1.tar.gz'
+  
+  This will generate the necessary .yml files, download and 
+  repackage (repackaging is optional). Then you can decide whether
+  you wish to continue or not.'
+}
+
+On a default, out-of-the-box system, htop can now be found 
+under <b>/Programs/Htop/Current</b>, or rather $PROGRAMS
+variable rather than hardcoded /Programs. Note that you can
+change this in the configuration settings too.'
+
+Lets go there to have a look:
+command '  cd $PROGRAMS/Htop/Current; ll'
+You may notice the directory structure. It is how Gobolinux 
+has layout their directory structure of directories within /Program 
+as well, but there are some differences, which we will cover
+later.'
+
+Typically, you will find a 
+<span class="directories">bin/</span> directory and a
+<span class="directories">share/</span> directory
+there. Inside bin/ lies the single binay called "htop".'
+
+You may also see a file called <b>CompileTimeInformation</b>
+which contains information about the compilation process.'
+
+Anyway, the most important point to note here is this:
+
+e sg(:pfeil_rechts,'marr4px')+'All of htop is self-contained 
+in this directory.','marl3em yel FI'
+
+This in fact is the biggest difference to FHS-based 
+systems. Others call this approach (more or less) 
+AppDirs or similar.'
+
+Personally I prefer the word "self-contained" since it is 
+more direct to the point that everything that belongs to the 
+package directly, is aggregated inside one directory, and we 
+wont confuse it with Mac OS X Appdirs for example.'
+
+    p('ind0px
+If you want to, for instance, uninstalle htop again,
+simply remove the directory:
+
+    rm -rf /Programs/Htop/'
+
+or just the specific version:
+
+    rm -rf /Programs/Htop/0.8.1'
+
+e sg(:ausrufungszeichen,'marr4px')+'Note that 
+I recommend to set the variable $PROGRAMS so instead of 
+hardcoding the above, rewrite it like this:
+    rm $PROGRAMS/Htop/7.0'
+To get the value of $PROGRAMS, simply do:
+    echo $PROGRAMS'
+The removing of a dir should trigger an event, 
+called <b class="EVENT">on_remove_directory</b>, and 
+this will automatically invoke a few cleanup
+scripts.'
+
+This however, only works on Distributions specifically set up
+to deal with the RBT Scripts or if you use something like the
+Diamond Shell.'
+
+
+On most Linux Distributions you would find these things 
+under <b class="palevioletred">/usr/local</b> normally (if 
+you compiled on your own <b>without</b> a --prefix option).'
+
+Other people like to compile it into their home directory,
+like 
+<b class="palevioletred">$HOME/directory_name/program_version</b>.'
+
+
+Now, the problem with <b class="palevioletred">/usr/local</b> 
+is that it is an additional layer of complexity, with all 
+the disadvantages the FHS already has. Additionally,
+<b class="palevioletred">/usr/local</b> is typically exempt
+from the package manager of the Distribution in question -
+which means you are, once again, on your own.'
+
+The /usr hierarchy *must* be managed with a 
+package manager/system manager, because the files
+were already spread around.'
+
+The FHS is a rather messy solution which causes more problems
+than it solves.'
+
+Only with the help of package and system manager can users
+manage their FHS-based systems - without that, it would quickly
+become an unmaintainable chaos.'
+
+Personally, I do not encourage you to do use the FHS,
+but there is one clear advantage:
+
+marl2em '- If you use the FHS approach, you will have less 
+problems this way because it is the "standard" way to do
+things on Linux systems. The Gobolinux approach is a lot
+cleaner though.'
+
+    p('smaller marl2em'){
+e sg(:angry_smiley,'marr6px')+'It is rather tedious to persuade 
+other people in the Linux world that they should not rely on 
+inflexible hardcoded paths. Most individuals with an opinion are
+so <b>very</b> stubborn, dead-set on the "established" way to
+do something, unable to get their brains to think differently
+and consider other options as well.'
+
+It is especially annoying when you are confronted "upstream".
+A waste of time to argue.'
+
+    p('smaller marl5em'){
+e sg(:explanation)+'Some people are so infected by this FHS
+doctrine that they hate other ideas, such as self-contained
+application directories.'
+In doing so they fail to see that this solution 
+is <span class="underline">a LOT</span> better and more 
+elegant in the long run than the ugliness of the FHS-imposed, 
+arbitrary rule-set.'
+
+marl2em '(What is even worse, the LSB builds and <b>extends</b> 
+upon the FHS.)'
+
+    p('ind0px mart2em'){
+Back on track though - lets say you like the FHS approach 
+(after all, Linux is or should be all about choice) and want 
+to compile htop into a directory like /usr.'
+No problem!'; br
+There are several ways to do this - one that I 
+like is to modify the specific .yaml file in question.'; br
+Simply open up your local <yel>cookbook.yml</> version -
+or the individual .yml file in question, in case you
+follow the "one program per file" approach - like so:
+
+    bluefish /System/Settings/cookbook.yml &'
+    $EDITOR $COOKBOOK_DIRECTORY/ALL_COOKBOOKS/cookbook.yml &'
+
+(Of course, use another editor like nano or vim 
+if you like. For simplicty, the rest of the instruction set 
+will refer to bluefish as the main graphical editor, just use
+the editor you prefer.)'
+ 
+This file, <span class="yel">cookbook.yml</span>, is 
+quite large. In November 2011 I had about 2600 registered 
+programs there in all my cookbook files. Dont worry about 
+reading everything in those files though ;-) just jump straight 
+to the entry called "htop:" (by pressing CTRL+F then typing 
+htop:) and press enter.'
+
+You should now be at the entry for htop. Have a 
+ief glance to see what is there.'
+(At the time of writing this tutorial, htop could be 
+found in the file <yel>cookbook.yml</>.)','marl3em'
+ 
+Look at the important option " prefix:"'
+marl1em 'You will see a f next to it, which simply means "false".'
+As you may have guessed, a "t" would indicate a value of 
+"true". RBT always tries to allow shortcuts when it is possible,
+but you can be explicited as well if you wouldd like to.'
+
+For now dont think too much about the meaning of 
+traditional itself, just change the "f" letter to a "t".'
+This has changed the "traditional" option to be true, 
+and true in this context roughly means "yes, we want to compile 
+in a FSH way", thus the prefix target would become /usr.'
+
+If this convention confuses you, you could use an explicit
+setting such as this too:
+
+cmd ' prefix: /usr'
+
+Though it is a bit longer to type.'
+
+Please note that you can overrule this option on
+the commandline, via --prefix=, like so:
+
+    rbt htop --prefix=$J'
+    rbt htop --prefix=/usr/local'
+    rbt htop --prefix=$HOME'
+
+Note that the last option there, the --prefix=$HOME,
+also is available via a short-cut flag:
+
+    rbt htop --into-home-dir'
+    rbt htop --home-dir'
+
+And you can also compile into your home dir, in
+an AppDir variant, by using this:
+
+    rbt htop --appdir-into-home-dir'
+
+The above is equivalent to:
+
+    --prefix=$HOME/Programs/Htop/1.0.1'
+    --prefix=/root/Programs/Htop/1.0.1'
+
+You can also omit the <b>prefix:</b> option entirely, it will 
+<b>default</b> to prefix=/usr/ in that case. But you could also 
+put in /opt here or even /opt/PROGRAM_NAME - the last bit is 
+a "macro" which will simply be expanded to the real program
+name.'
+
+I myself tend to use this here a lot in the yaml files:
+
+cmd ' prefix: f'
+
+Which translates to "compile in a Gobolinux like fashion".
+In other words, a <b>standalone AppDir structure</b>.'
+
+Once you have done this change, save the file, and go to 
+your shell again.'
+
+Then type this in your shell (and press the enter key):
+
+    rbt htop'
+
+You will see that htop will be compiled, but this 
+time it will use that other prefix - the /usr prefix.'
+
+Which means, after (a successful) compilation, you will 
+find the htop binary at <b>/usr/bin/htop</b>.'
+
+(Htop was created by Hisham who also started Gobolinux 
+together with André, by the way. Htop is a really cute small 
+program.)','marl3em smaller FI'
+By changing a single letter in the <yel>cookbook.yml</> 
+we have instructed our compile tools to build to another 
+prefix. You can set other prefixes to this "traditional: value"
+setting, for example /pkg if you want to compile into the 
+directory /pkg and so on.'
+
+You can also pass arbitrary -- configure options.'
+
+For instance, you can do this:
+
+    rbt utillinux ntrad --without-ncurses'
+
+This would attempt to compile the program called
+utillinux, use an AppDir prefix, and also pass
+in --without-ncurses as commandline option.'
+
+
+e "Let's review the concepts learned so far, in a nutshell:"
+
+lem sg(:red_square,'marr5px')+"Basically, all you had to do was
+to change one letter in the 'recipes collection', in order
+to compile it to another prefix."
+
+This is one of the <b class="ud orange">principles of the 
+RubyBuild Tools</b>. Things should be simple, clean and 
+as logical as possible - for the <b>end user</b>.'
+
+IF we need complexity for some reason, then we need to be able
+to manage it with ease and explain why we have done so. It would
+be not much fun to be buried under a load of complexity.'
+
+If you have a proposal for a simplification, voice it.'
+
+Make sure you thought about it for a bit before issuing 
+though, it makes our life easier if you are completely convinced 
+that this can be useful to have.'; br
+
+One final word about this "traditional:" setting for now:
+
+l2em 'You can of course overrule this setting on commandline 
+just as well.'
+
+So ultimately, you do not have to edit any of the various
+<yel>cookbook.yml</> files. The commandline must allow
+the user to overrule any setting, at runtime.'
+
+Or even try to ignore it completely and just provide a URL 
+to a tarball of some sorts, to download and compile something.'
+
+To show you how to overrule the setting in the cookbook files, 
+look at the following examples:
+    rbt htop traditional'
+    rbt htop non_traditional'; br
+Of course, "compile htop ntrad" works too as does 
+"compile htop t".'
+
+If you try to pass both options (<i>non_traditional</i>
+and <i>traditional</i>) then we will display a warning, and
+favour only one of those options given, which right now is
+the last option given. In general, <ud>options that come last
+are allowed to overrule earlier options given</ud>. We
+however display a warning in this case because it does
+not seem to make a lot of sense.'
+
+Please note - if you do not have a cookbook.yml file yet or 
+if you want to generate a new one, you can do so by issuing:
+
+    rbt generate_new'
+
+This will try to generate a new cookbookfile into
+/Depot/Temp and if this does not work, it defaults to the
+current working directory.'
+
+
+Lets look back at <yel>cookbook.yml</> now and contemplate 
+on the size of it. It is indeed quite large... '
+There may be some people who will say that having 
+<b>one big file</b> like <yel>cookbook.yml</> is a bad thing. '
+
+I agree partially, and this is the reason why you can use 
+as many .yml files as you want.'
+
+The RBT Scripts should allow you to freely build and install
+applications, and thus they should not restrict you.'
+
+You can use multiplie .yaml files or you could create and
+use standalone recipes: Enter The Recipes World!'
+
+More on Recipes later - stay tuned.'
+
+# ========================================================================= #
+# === Batch-update all registered gems
+# ========================================================================= #
+    header_stylish_brown 'Batch-update all registered gems'
+
+You can batch-update all registered gems via:
+
+    rbt --update-all-gems'
+
+Note that this will only work if you use the Cookbooks project.'
+
+# ========================================================================= #
+# === Disabling the use of cookbook aliases
+# ========================================================================= #
+    header_stylish_brown 'Disabling the use of cookbook aliases'
+
+The cookbooks submodule, part of RBT, makes use of several aliases
+to program names. This is mostly a convenience feature.'
+
+Sometimes this may lead to unexpected or unwanted results,
+such as when you want to compile program **a**, but the
+cookbooks project renames the program to **b** instead.'
+
+In order to avoid this, a commandline-option exists for
+the RBT project.'
+
+Invoke it like so:
+
+    rbt sdlttf --do-not-use-cookbook-aliases'
+    rbt sdlttf --do-not-use-cookbook-alias'  
+
+This will specifically disable making use of cookbook
+aliases.'
+
+
+# ========================================================================= #
+# === Program Versions
+    #
+# Program Version tag, versions tag. rf rbtcgi program_versions
+# Here we can set specific versions.
+# ========================================================================= #
+    header_stylish_brown 'Program Versions'
+
+You can overrule the version specified in the cookbook yaml 
+file from the commandline. To do this, look at the following two 
+examples:
+
+    rbt nano --version=2.1.9
+    rbt nano --version=2.2.2
+    rbt nano --version=2.4.3
+    rbt gtk+ --version=2.24.29
+
+Note though that this has a chance to fail right now,
+i.e. if the remote mirror does not have this specific version,
+or if you do not have it available locally.'
+
+You can also use a slight shortcut:
+
+    rbt nano --v=2.4.3
+
+And an even shorter variant is to just give the leading
+name, and have the RBT script just pick one that fits:
+
+    rbt python --2'
+
+You can also use a more complete copy-paste version
+setting (like you copy, then paste the full name), 
+like this:
+
+    rbt nano --version=pango-1.24.2.tar.bz2'
+
+The .tar.bz2 part, and the part before that, will 
+simply be ignored.'; br
+Also note that you can retrieve a listing of all locally
+available versions.'
+
+Use the following to get at this information:
+
+    rbt gcc available_versions?'
+    rbt gcc ?'
+
+The result would be something like:
+
+result '================================================================================'
+result ' - (1) gcc-3.4.6'
+result ' - (2) gcc-4.0.4'
+result ' - (3) gcc-4.1.2'
+result ' - (4) gcc-4.2.4'
+result ' - (5) gcc-4.3.3'
+result ' - (6) gcc-4.4.2'
+result ' - (7) gcc-4.4.3'
+result ' - (8) gcc-4.5.0'
+result '================================================================================'
+
+You can then compile one of these version, by doing i.e. this here:
+
+    compile gcc v4'
+    compile gcc 4'
+You can omit the v too. The v is just a mnemonic shortcut for 
+"version", but the position number alone suffices anyway:
+
+    rbt gcc 3'
+
+This also works with negative numbers, like:
+
+    rbt perl -3'
+    rbt perl v-3'
+
+The above would compile the Perl version that is the -3 most
+recent. In other words, we start to count from the current version,
+and step back 3 times from that. (This will only work if you
+have the perl versions available locally).'
+
+If you give a bogus entry like v-66126363 and that version
+could not be found, we will instead treat it as input that you
+meant to refer to the very last version anyway.'
+
+A positional index with a word works for the first and last 
+entry too. The convenient keywords for this are called "first" 
+and "last". So rather than type 1 or 8, you can do this:
+
+    rbt v first'
+    rbt v last'
+
+The last version can be useful.'
+
+Aliases to these do exist:
+
+    rbt pcre vlatest'
+    rbt pcre vnewest'
+    rbt pcre latest'
+    rbt pcre newest'
+
+You can also query for the current RBT Versions.'
+
+To do this, do either of the following:
+
+    rbt htop --version'
+    rbt VERSION?'
+    rbt --version?'
+
+Since as of December 2015, you can also compile a random
+version.'
+
+This requires of you to have the other versions available
+locally though.'
+
+Usage example:
+
+    rbt gcc --use-random-version'
+
+    p(id: 'to_bash'){
+The scripts are written in ruby, but for several reasons 
+one might want to prefer using shell scripts instead.'
+
+You can generate the small shell scripts by issuing 
+something like:
+
+    rbt --to_bash'
+
+Or shorter:
+
+cmd ' ry --tobash'
+cmd ' ry tobash'
+
+A single file will be created as a result, it can normally
+be found under' 
+
+    /System/Settings/Scripts/bash_programs_rc','yel marl1em'
+
+
+Now, this is pretty handy, but what if you do <b>NOT</b> 
+want to compile at all?'
+
+No problem. Use a package.'
+
+Example:
+
+    rbt python install_package'
+    rbt fox package'
+
+This will install python from a binary package (and 
+download it from a remote site if needed, i.e. if it can 
+not be found locally.)'
+
+
+There are many more options available to the scripts that handle 
+these things but for a starter, this should be it.'
+
+But what if you <b>dont</b> have this package on your computer?'; br
+By default the RBT Scripts will assume that you 
+already downloaded this package and put it in some location, 
+like <b>/Depot/Packages</b>.'; br
+But you can download '+sg(:pfeil9,'marr4px')+' 
+a package with the scripts too:
+    rbt python download'
+This would (try to) fetch the latest (source package) of python 
+and download it to your machine.'
+Note that this command may fail due to several 
+reason, such as that the remote server is not available or 
+that the location has moved to another website and so on.','marl2em'
+
+As of September 2014 we also added a configuration option to
+yaml files called:
+
+    do_not_download
+
+
+# ======================================================================= #
+# === Porg tag
+# ======================================================================= #
+
+Porg'
+
+You can use porg to install a program.'
+
+To query whether porg is in use, you can issue this command:
+
+    rbt --use_porg?'
+
+Porg will keep track of program files that are installed.'
+
+You can also disable porg on the commandline via:
+
+    rbt --disable-porg'
+    rbt --disable_porg'
+    rbt --disableporg'
+
+Or just directly edit the respective .yml file.'
+
+# ======================================================================= #
+# === Installed files
+# ======================================================================= #
+header Installed files'
+
+You can ask RBT which files belong to a specific program.'
+
+Do this like so:
+
+    rbt htop --installed-files?'
+    rbt htop --installed-files'
+
+# ======================================================================= #
+# === meson
+# ======================================================================= #
+header meson'
+
+You can specifically enable the meson-build by issuing this:
+
+    rbt glib --use-meson'
+
+# ======================================================================= #
+# === M4 Macros
+# ======================================================================= #
+header M4 Macros'
+
+We can symlink .m4 Macros into the directory
+<b>/usr/share/aclocal</b>. This obviously only makes sense if the
+program at hand was installed into an AppDir-like prefix, rather
+than straight into the /usr prefix hierarchy.'
+
+
+# ======================================================================= #
+# === Binary and Library Checking.
+# ======================================================================= #
+
+You can specify another source directory (base_dir) by doing
+something like this:
+
+    rbt mantis --source_dir=/Depot/j'
+
+# ======================================================================= #
+# === GoboLinux SymlinkProgram
+# ======================================================================= #
+
+On GoboLinux, you can use SymlinkProgram. On non-GoboLinux systems,
+SymlinkProgram is not available by default; the RBT suite contains 
+class RBT::SymlinkProgram, which behaves somewhat similar, but not
+quite.'
+
+It may be better to use SymlinkProgram on GoboLinux, and the
+following entry point allows you to use the GoboLinux SymlinkProgram
+variant rather than class RBT::SymlinkProgram:
+
+    rbt htop --use-gobolinux-symlinkprogram
+
+# ======================================================================= #
+# === Symlink all upcased programs to downcased variants
+# ======================================================================= #
+
+If you ever have to, or want to, symlink all upcased program
+entries to downcased program variants (excluding the first character),
+then you can use this invocation line:
+
+    rbt --symlink-all-upcased-programs-to-downcased-variants'
+
+This will create a symlink, for example, at
+/Programs/Zlib for /Programs/ZLib.'
+
+The reason it was added was because GoboLinux uses semi-upcased
+directory names; and this makes things a bit more complicated 
+sometimes.
+
+# ======================================================================= #
+# === UpdateEntry
+# ======================================================================= #
+header UpdateEntry'
+
+You can use class RBT::UpdateEntry to update an entry in one of
+the available <b>cookbooks</b>.'
+
+This class accepts, as <b>parameter</b>, a remote URL - the URL to
+the program in question.'
+
+So for example, if you wish to change to another glib version,
+you could issue this command:
+
+    update_entry http://ftp.gnome.org/pub/gnome/sources/glib/2.53/glib-2.53.4.tar.xz'
+    ue http://ftp.gnome.org/pub/gnome/sources/glib/2.53/glib-2.53.4.tar.xz'
+    rbt --update-entry http://ftp.gnome.org/pub/gnome/sources/glib/2.53/glib-2.53.4.tar.xz'
+
+UpdateEntry will store the last downloaded program in a specific
+file. You can then make use of this from RBT, by doing something
+like this here:
+
+    rbt lastdownload
+
+# ======================================================================= #
+# === Libtool tag.
+# ======================================================================= #
+header Libtool'
+
+Libtool is a shell script. It makes use of .la files.'
+
+Since most programs come via .pc (pkgconfig) files these
+days, .la files are rarely needed.'
+
+If you wish to automatically get rid of .la files after
+compilation, then you can use this switch:
+
+    --remove-la-files'
+
+# ======================================================================= #
+# === ldconfig tag.
+# ======================================================================= #
+header ldconfig'
+
+Note that the current behaviour is to (silently) run ldconfig 
+after compilation has finished. This can be modified in the
+config file, see the option there called `run_ldconfig`.'
+
+You can also disable the running of ldconfig from the commandline
+for the program you wish to install.'
+
+In order to do this, do:
+
+    rbt htop no_ldconfig # Main command'
+    rbt htop noldconfig # Alias to the above ^^^'
+    rbt htop nold'
+
+# ======================================================================= #
+# === Convert to FHS tag
+# ======================================================================= #
+header Convert to FHS'
+
+If you ever want to convert a given package to FHS style, use this:
+
+    rbt php5 convert'
+    rbt php5 cpackage'
+    rbt php5 convert_package'
+    rbt nimrod cpa'
+
+This is, right now, using the files under /Programs - or more 
+accurately, it uses the setting specified in your configuration yaml
+file, the value of "programs_dir" - , and
+will then copy these into the /usr prefix.'
+
+To get a listing of available programs, you can do:
+
+    rbt --available_programs?'
+    rbt available_programs?'
+    rbt available_cookbooks?'
+
+This will iterate over all programs specified at programs_dir.'
+
+# ======================================================================= # 
+# === Installing older versions. rf rbt Installing_older_versions
+    #
+# Version tag. rf rbtcgi installing_older_versions
+# ======================================================================= #
+header Installing older versions'    
+
+What if you want to install an older version of python?'
+
+We briefly addressed this elsewhere on this page already, but we
+will now go into more detail.'
+
+lem sg(:info,'marr4px','drag_INFO_IMAGE','','INFO')+'
+The <b class="yel">cookbook.yml</b> normally 
+"supports" only the version you specified in 
+<b>"<lightblue>archive_name:</>"</b>'
+
+For example, if you jump to the "python:" entry in the cookbook.yml 
+file, you will see that its version is 2.5.1.'
+
+e sg(:anmerkung)+'In later revisions python apps are gathered
+inside python_cookbook.yml instead of the general cookbook.yml 
+file.'; br
+You can change this permanently by writing another name/version 
+there.'; br
+Because editing of various cookbook.yml files can be a little annoying, 
+and because flexibility is a good thing, there exists another way to 
+specify a different version manually on the commandline:
+
+    compile python --version=2.4.1'
+
+This works with every version, even "newer" ones.'; br
+The name of the version should however be part of the filename.'
+
+For more information about this, and an even <b>easier way</b>, 
+jump <a href="#program_versions" class="slateblue">here</a> to.'
+
+    
+# ======================================================================= # 
+# === Dump all .rb files.
+# ======================================================================= #
+header Dump all Recipe files'
+
+To dump all recipe files (Gobolinux files, ebuild files, 
+.rb recipe files) do this:
+
+    rbt x dumpall'
+
+# ======================================================================= # 
+# === Suppress Commandline
+# ======================================================================= #
+header Suppress Commandline Output'
+
+To suppress configure spamming useless information to you, and to
+also suppress other things, do this:
+
+    rbt htop v2 suppress-output'
+    rbt htop v2 soutput'
+    rbt htop v2 sout'
+    rbt htop sout'
+
+You can also make all output completely disappear:
+
+    rbt htop --be-completely-quiet'
+
+This will suppress all output.'
+
+# ======================================================================= # 
+# === Generate completion (completion tag).
+# ======================================================================= #
+header Generate and use shell completion'
+
+You can generate a bash shell completion file from within 
+RBT.'
+
+In order to do so, try this:
+
+    rbt x generate_shell_completion'
+
+This will write a simple shell script which you can source if
+you want to use ry <TAB> to compile programs.'
+This also works for Zsh by the way.'
+
+The file in question is called <b>generate_shell_completion.rb</b>.'
+
+If called standalone from the commandline directly, it will 
+generate .sh shell files for both Bash and Zsh.'
+
+# ======================================================================= # 
+# === Find out local location of tarballs
+# ======================================================================= #
+header Find out local location of tarballs'
+
+To find out the local location of a tarball use this:
+
+    rbt gcc local_url'
+    rbt gcc lurl'
+
+The result will be something like this:
+
+    => The local file for gcc can be found at:
+    /Users/x/SRC/GCC/gcc-4.6.1.tar.bz2'
+
+# ======================================================================= # 
+# === Build inside a subdirectory (build directory).
+# ======================================================================= #
+header Build inside a subdir'
+
+Sometimes you dont want to build in the current directory, but
+may want to use a subdirectory instead. (For example, glibc requires
+you to build inside a subdirectory).'
+
+To do this from the commandline, simply do one of the following
+commands:
+
+    rbt php --subdir=PHP_BUILD_DIRECTORY'
+
+The above would build in the directory called "PHP_BUILD_DIRECTORY".
+If this directory does not exist (which is the case usually), then 
+the RBT scripts will create that directory.'
+
+The default name for the subdirectory is called
+<b class="red">BUILD/</b> and you can do default to
+this directory:
+
+    rbt pango -b'
+
+This will create a <b class="red">BUILD/</b> directory and change 
+the working directory into it, while compiling.'
+
+In practise, defaulting to the BUILD/ directory is the easiest
+solution if you want to compile in your own directory.'
+
+Please also note that you can specify build directories
+in the respective cookbook file as well - look at the description
+of the variables called `<span class="yel">use_build_directory</span>`, 
+and `<span class="yel">use_this_build_directory</span>`.'
+
+Alternative syntax exists as well,of course. If you want to
+use the default build directory for a project you compile, you
+can pass the option <b>usebuilddir</b> like so.'
+
+    rbt automake --use-build-dir'
+    rbt automake usebuilddir'
+    rbt htop usebuilddir'
+    rbt php use_build_dir'
+
+You can also specify a specific build directory to use.'
+
+One way that this works is via this:
+
+    rbt htop --use-this-build-dir=/Depot/j'
+
+The RBT scripts will append a trailing / if it is a
+directory and if it does not yet have a trailing / character
+presently, so the above command is the very same as passing
+in <b>/Depot/j/</b>.'
+
+If you want to use a build directory, but do not care
+about the name, you can also use a random name, like 
+so:
+
+    rbt php --use-random-build-directory'
+
+# ======================================================================= #
+# === Register all programs. Register tag.
+# ======================================================================= #
+header Register all programs'
+
+It may be that you want to register all programs in the yaml
+Database. To do this, run this command:
+
+    rbt --register_all_programs'
+    rbt --rap'
+
+
+    
+# ======================================================================= #
+# === Extract Archives
+# ======================================================================= #
+header Extracting Archives'
+
+You can extract a tarball and finish the program. In order to 
+do this, try:
+
+    rbt php eonly'
+
+This would extract the latest PHP tarball and then exit the program.'
+
+Also note something else, related to <b>Extracting</b>. You can use
+the argument --extract_to (or its alias --homedir or --temp_dir) to
+specify another <b>extract target</b> to use. You can even use
+shell environment variables here.'
+
+Usage Examples:
+
+    rbt htop --extract_to=pwd'
+    rbt htop --extract-to=$J # This makes use of the shell
+environment $J'
+    rbt htop --temp_dir=/tmp'
+    rbt htop --homedir=pwd'
+
+# ======================================================================= #
+# === Removing all directories in the temp directory
+# ======================================================================= #
+header Removing all directories in the temp directory'
+
+If you ever need to or want to remove all directories in the
+temporary directory (by default: /Depot/Temp/), then the following
+option may be useful:
+
+    rbt --remove-all-temp-directories'
+
+    
+# ======================================================================= #
+# Use first URL
+# ======================================================================= #
+header Use the first URL instead of program name:
+
+You can overrule the program name and specifically force 
+the usage of the first URL entry.'
+
+You do this like so:
+
+    rbt ffmpeg use_url'
+    rbt libgtkhtml use_url'
+
+Do note though that for this to work, it requires a proper 
+url1 entry in the cookbook file.'
+
+# ======================================================================= #
+# === Output all URLs.
+# ======================================================================= #
+header Use the first URL instead of program name:
+
+You can output all URLs like so:
+
+    rbt --output_all_urls'
+    rbt all_urls?'
+
+Note that this will also save this result in a file.'
+
+# ======================================================================= #
+# === Use a specific compile version
+# ======================================================================= #
+header Use a specific compile version'
+
+You can overrule the program_version? that will be used for
+app-dir like compilation like this:
+
+    rbt glib --compile-version=2.16.33_ROEBE'
+
+The above command will try to compile glib, but will use a
+specific version that you defined here. Typically it should
+be only numbers, but you can also use non-numbers.'
+
+The above would translate into this prefix:
+
+/Programs/Glib/2.16.33_ROEBE'
+
+# ======================================================================= #
+# === md5sum tag
+# ======================================================================= #
+header md5sum'
+
+Verify the md5sum:
+    rbt gcc4 md5'
+    rbt libogg md5'
+
+Note that you can disable the md5sum calculation, by
+using the switch --no-md5sum:
+
+    rbt htop --no-md5sum'
+
+# ======================================================================= #
+# === check locally tag
+# ======================================================================= #
+header Check locally'
+
+You can check for the latest packages locally via'
+
+    rbt htop latest'
+
+# ======================================================================= #
+# === Feedback tag
+# ======================================================================= #
+header Feedback about a program'
+
+To get feedback about i.e. php, do:
+
+    rbt php feedback_all'
+    rbt ruby fall'
+
+You can also make use of SanitizeCookbookDataset.
+
+    rbt php --scookie
+    
+# ======================================================================= #
+# Using multiple yaml files
+# ======================================================================= #
+header Use multiple yaml files','multiple_yaml_files'
+
+You can use more than one cookbook yaml file. Just specify this in
+the config file, at the entry <b>"cookbook_directory"</b>.'
+
+The first entry should always point to your most important
+cookbook file though, the one you use most of the time, or is 
+the largest cookbook file.'
+You can of course just use one big cookbook file.'
+
+Additionally, you can use a "one-file-per-program" approach.'
+
+I myself transitioned into this approach several years ago. It
+simply was easier to update information stored in individual 
+directories.'
+
+You can use a special "macro", which will load all files of a
+given directory.'
+
+Example:
+
+cmd ' - /some/directory/YAML/'
+
+The above would load all files inside that directory.'
+
+Yes, this was changed some time ago, I think in 2009. RBT will
+automatically try to load all .yml files from that directory.'
+
+# ======================================================================= #
+# === Query whether we have a binary file.
+# ======================================================================= #
+header Querying whether we have a binary file','query_binary_file'
+
+If you want to find out if we have a registered program,
+whose binary name is "file", do this:
+
+    rbt file binary?'
+
+In other words, you can find out if we have such a binary name.'
+
+Different programs will have different binary names, and sometimes
+it is important to find out which binary belongs to what package.'
+
+# ======================================================================= #
+# === Query Inclusions
+# ======================================================================= #
+header Query Inclusions','inclusions'
+
+To find out whether all your files are included in the cookbook
+file, do this:
+
+    rbt htop inclusions?'
+
+It will report which files were not included.'
+
+This is mostly helpful when you want to cleanup unneeded 
+packages.'
+
+# ======================================================================= #
+# === Static Compilation.
+# ======================================================================= #
+header Static Compilation'
+
+You can compile an application statically by passing <b>static</b>
+to <b>compile.rb</b>.'
+
+Example:
+
+    rbt make static'
+
+Note that this will not work for every program.'
+
+In the event that you, on the commandline, try to enable static
+compilation, and the yaml file specifies otherwise, such as via a
+configure switch like --disable-static, we will ignore the latter
+option and allow the user to specifically overrule this setting.
+RBT always assumes that the user knows what he is doing.'
+
+Note that you can also zero these flags via a commandlie
+option:
+
+    rbt strace --no-compile-time-flags'
+    rbt strace --plain'
+
+This option means that all CFLAGS etc... will be ignored
+altogether; that is, they will set to an empty again.'
+
+# ======================================================================= #
+# === Searching for something
+# ======================================================================= #
+header Searching for something','searching'
+
+To search for something, do this:
+
+    rbt ruby search'
+
+To find a specific list of packages, do this:
+
+    rbt pyt*'
+
+The * will tell us that we intend to find all packages
+starting with "pyt".'
+
+This can work with single letters too, that is - if you wish
+to discover all programs that are registered in the Cookbooks
+project starting with a, you can do:
+
+    rbt e*'
+
+The "*" is the important token here that will trigger this
+functionality.'
+
+Be careful though if you use a shell like Bash or 
+Zsh - the * can be expanded by the shell.'
+
+# ======================================================================= #
+# === Prefix Tag
+# ======================================================================= #
+header Using another prefix','prefix'
+
+You can specify a different prefix to use when compiling a 
+program.
+
+To do this, do:
+
+    rbt gimp --prefix=$J
+    rbt gimp --prefix=/opt
+
+Some nifty shortcuts exist. For example, to compile gimp
+into a standalone directory, into /Programs/Gimp/LatestVersion,
+you can do:
+
+    rbt gimp ntrad'
+    rbt gimp non_traditional'
+
+Please also note that you can use the Option <b>noprefix</b> to
+avoid using <b>any</b> specific prefix. (This is the same as passing
+--prefix=/usr/local though on GNU systems.)'
+
+If you have the need to find out the prefix that will be used,
+do this:
+
+    rbt htop prefix?'
+
+Do note that you can also use "compound-prefixes". These are
+prefixes such as /Programs/Xfce/4.12, where you may want to put
+all xfce-related programs into.'
+
+Syntax is like this:
+
+    rbt xfce4panel --prefix=:xfce'
+
+In order for this to work, an environment variable called
+XFCE_PREFIX may have to exist. If such an environment variable
+does not exist, then the program_version is guessed. I recommned
+to set such a prefix variant.'
+
+The leading : is important here - do not forget it.'
+
+# ======================================================================= #
+# === Specify another program to compile.
+# ======================================================================= #
+header Specify another program to compile','another_program_to_compile'
+
+You can specify another program to compile.'
+
+For this there are currently two ways possible:
+
+cmd 'ry x --this_file=/path/to/mousetweaks-3.1.1.tar.bz2'
+cmd '$RBT/Compile.rb /path/to/mousetweaks-3.1.1.tar.bz2'
+
+# ======================================================================= #
+# === Merging Cookbook Files.
+# ======================================================================= #
+header Merge Cookbook Files'
+
+If you do have multiple cookbookfiles (or if you want to merge
+your existing cookbooks into one new file),
+you can do this:
+
+    rbt php merge'
+
+By default this command will merge into the 
+file DEPOT_DIR+merged.yml'
+
+# ======================================================================= #
+# === Debug tag
+# ======================================================================= #
+header Debug'
+
+If you want to debug the RBT Scripts, you can set the 
+<b class="orange">@debug</b> value on the fly via:
+    rbt x debug'
+This will toggle the debug value simply. Set this to true 
+if you want to debug. If set to true then we will feedback extra
+information.'
+You can also query the debug value by doing this:
+    rbt x debug?'
+
+# ======================================================================= #
+# === Common operations
+# ======================================================================= #
+header Applying a common operation'
+
+You can apply a common operation to multiple programs at the same 
+time. First, let us assume that you want to compile all versions of GTK:
+    rbt gtk all_versions'
+This would compile all the versions of GTK you have downloaded.'
+
+# ======================================================================= #
+# === Using Stow
+# ======================================================================= #
+header Stow'
+
+If you want to use stow, simply set the configuration option
+for Stow to true (in the <b>configuration file</b>)'
+
+You can query whether you have stow enabled, by doing:
+
+    rbt --use-stow?'
+
+# ======================================================================= #
+# === Included program
+# ======================================================================= #
+header Included program'
+
+You can find out whether a specific program is included or not
+by doing this:
+    rbt htop include?'
+
+# ======================================================================= #
+# === whereis program
+# ======================================================================= #
+header Whereis'
+
+If you forgot where you defined your program entry, you can
+use <b>SourceDefinition.rb</b> to locate it. This is aliased to 
+the action where_is.'
+
+So, try this:
+
+    wis gcrypt'
+
+This will tell you where gcrypt is installed.'
+
+# ======================================================================= #
+# === Symlink headers
+# ======================================================================= #
+header Symlink headers'
+
+If a cookbook file has this entry:
+lem '  symlink_headers: t'
+Then this means that the RBT scripts will attempt to symlink
+all entries under the respective include/ directory into the
+FHS /usr/include/ hierarchy.'
+
+Why is this useful? Sometimes you may wish to have a hybrid
+system, that is, with some AppDirs under /Programs, and some
+non-AppDirs installed at /usr.'
+
+You can also invoke this on the commandline by issuing 
+--symlink-headers, like this:
+
+    rbt htop ntrad --symlink-headers'
+
+# ======================================================================= #
+# === Symlinking all programs
+# ======================================================================= #
+header Symlinking all programs'
+
+If you want to (re)symlink all programs in the main directory
+called <b>/Programs/</b>, just do this  any of these:
+
+    rbt x symlinkall'
+    rbt x traverse'
+    rbt --resymlink'
+    rbt --symlink_every_program'
+
+The last option may quite possibly be the easiest one to remember.'
+
+A note about <b>symlinks</b>. The GoboLinux way is to keep the Version
+as a Symlink, under <b>/Programs/Name/Version</b>. RBT also uses this
+scheme when compiling in a gobolinux-like (== App)way.'
+
+Say that you have successfully compiled htop version 2.0.2. Then,
+a symlink will also be set, called <b>Current</b>. This one could
+then be found at:
+
+lem '/Programs/Htop/Current'
+
+Which would point at:
+
+lem '/Programs/Htop/2.0.2'
+
+
+# ======================================================================= #
+# === Sleeping.
+# ======================================================================= #
+header Sleep before continuing'
+
+You can use a <b>delay</b> before compiling (or doing another
+action).'
+
+This works like so:
+
+    rbt htop sleep5'
+    rbt htop sleep55'
+
+That is technically the same as doing'
+
+cmd 'sleep 5; ry foo'
+or'
+cmd 'sleep 55; ry foo'
+
+This would mean that you would want to wait for 5 or 55 seconds
+before starting your action.'
+
+
+# ======================================================================= #
+# === Do not show program names.
+# ======================================================================= #
+header Do not show programs names'
+    div {
+By default, the RBT Scripts will show the name of the Ruby 
+script that is running an execution.'
+You can disable this by doing:
+    rbt htop dont_show_names'
+    rbt htop dontshownames'
+
+# ======================================================================= #
+# === SCRIPTS AND THE STRUCTURE
+# ======================================================================= #
+header The Scripts and their (Infra)Structure'
+    div {
+The scripts are written in '+string_link(:remote_ruby,
+sg(:ruby))+'<b class="red">ruby</b>, and although I 
+have tried to keep them rather simple, at times they can be a 
+bit complex (and some code parts are quite dated, and thus 
+may not be easy to understand - not even for myself.)'
+I do however often reconsider design decisions, and start 
+rewrites every now and then to clean up the existing 
+infrastructure.'; br
+If you want to explore these scripts, you should first look at '
+  Query.rb','marl2em grey'
+This file consists of one class, which has 
+only one basic job:
+
+marl2em '  Load the data from the cookbook.yml file by using
+DatabaseLoader.rb and answer queries the user gives us.'
+
+<b>DatabaseLoader.rb</b> will load the yaml dataset, 
+and then you can actually use Query.rb to query whether 
+a package is included or not.'; br
+That is basically all these two files do.'
+
+DatabaseLoader.rb is much larger because it ensures that 
+the dataset is also correct.'
+
+Now, with this information we come to the most important
+script of the Ruby Build Tools - the <b>Installer.rb</b>'
+This is a bit complex. What you must keep in 
+mind is that this file tries to fullfil many different 
+user wishes at once:
+A user may want to install, uninstall, compile, copy, 
+get the URL of a program, create .deb packages, create 
+dependency graphs, create shell scripts, ebuilds, 
+Gobolinux recipes, md5chksum it and and and.'
+Now add all these tasks together in one program, and 
+the result will be quite large (though the code should 
+be rather straight-forward). Maybe I will split it up
+in several new files, but for now this approach must 
+suffice.'; br
+There are helper files available too.'; br
+The main purpose of Installer.rb is to be the 
+<b>general wrapper</b> around these various tasks.'
+Basically, whatever you want to do, you should be 
+able to do so via Installer.rb.'
+It is a basic duty of this script to invoke other 
+scripts as needed as well, acting as THE general 
+wrapper script'; br
+We now move to a more detailed section of how 
+Installer.rb actually works.'
+# ===================================================== #
+# compile.rb
+# ===================================================== #
+h4 'compile.rb'
+If you pass arguments to class Compile, then all "-" will be removed.'
+It makes it easier to label packages this way.'
+Installer.rb provides some logging capabilities:; br
+The <b>general log file</b> will usually be 
+stored here:
+
+/InstalledSourceFiles.html',
+    content: '/InstalledSourceFiles.html',
+    css_class: 'marl1em slateblue'
+Additionally, a file called '
+
+/System/Information/LastCompiledProgram.html',
+    content: '/System/Information/LastCompiledProgram.html',
+    css_class: 'marl1em slateblue'
+
+will be created.'
+
+Installer.rb accepts the program name as command:
+
+Typical Invocation examples are like so:
+
+    rbt ebml'
+    rbt libxml'
+    rbt libogg'
+
+If you omit the name of a program, the scripts
+will try to automatically guess a proper name using 
+the script <b>GuessName</b>. It is however recommended 
+to set the name manually, rather than guessing.'
+Also note, since December 2009 <b>GuessName</b> has been mildly
+deprecated. In Jul 2011 GuessName has been removed. The macro 
+USE_URL (or shorter, URL) will be auto-used in case you forgot 
+to set the program name.'
+
+To install in Gobolinux style (via the commandline, which will 
+overrule any settings in the respective cookbook at hand), you
+can do something like this:
+
+    rbt python gobo'
+    rbt gcc gobostyle'
+    rbt sed gstyle'
+    rbt gcc nt'
+
+I recommend you to try out gobo, it opens eyes. ;-)'
+
+In the above first example, Python would be compiled 
+into this directory by default:
+    /Programs/Python/VersionNummer'
+In effect, this will overrule any setting defined 
+in the YAML file. The reason for this behaviour is that the 
+user specifically wanted this behaviour.'
+
+Whatever the user wants to use, is the way-to-go for 
+us.','ud marl2em yel bigger'
+
+If you want to skip extracting (i.e. because you 
+already have it extracted) then do this:
+
+    rbt php skip_extracting'
+
+or more formally:
+
+    rbt gimp --skipextract'
+or for the lazy guys (includes me)'
+
+    rbt php se'
+
+You can also skip running any configure scripts, by doing this:
+
+    rbt php skip_configure'
+    rbt php sc'
+
+And you can combine this too, like:
+
+    rbt php skip_configure skip_extract'
+
+If you want to extract the package, and also run the configure
+script, but do not want to start compiling via make and make install
+yet, do this:
+
+    rbt binutils dc'
+
+dc means "dont compile", and this works too:
+
+    rbt binutils dont_compile'
+
+Please note that the last compiled programm will be stored
+in a yaml file. This will then allow you to easier acces the
+last compiled program and a pointer to it will be available
+if you use :last or @last as commandline argument.'
+
+For example, you can do this:
+
+    rbt :last url'
+    rbt @last url'
+
+This allows you to recompile the program quickly.'
+
+    rbt @l'
+
+Yes, @l is an alias to @last.'
+
+Also note that we will store the configure options that are 
+used to compile a program in a yaml file. Typically this is 
+<b>last_compiled_configure_options.yml</b>.'
+
+# ======================================================================= #
+# === Querying configure options
+# ======================================================================= #
+You can also query configure options for a given program.'
+To do this, try this:
+
+    rbt gcc3 configure?
+    rbt htop configure_option?
+
+Note that the script <b>ExclusiveLogic.rb</b> will check if a configure
+script makes sense. If you pass both --enable-fading and --disable-fading
+to the Installer.rb script, for instance, then ExclusiveLogic.rb will warn
+you of this mistake. This will allow you to fix the problem before you
+continue.'
+
+If you do not want to symlink after compilation has finished, add the
+option <b>dont_symlink</b> (or shorter, ds):
+
+    rbt gcc4 dont_symlink'
+    rbt gcc4 ds'
+
+Of course you can freely combine those instructions together:
+
+    rbt gcc4 dont_symlink skip_extracting'
+
+To create a new '+sg(:present, 'marr4px')+'package, you 
+use this command:
+
+    rbt fox cpackage'
+    rbt htop cpackage'
+    rbt fox cpackage archlinux'
+
+Default for this (if you omit i.e. archlinux) to create a
+.deb packages.'
+
+If you pass i.e. archlinux to it, we will create a package
+for Archlinux.'
+
+You can explicitely create a .deb Package as well by using
+something like:
+
+    rbt gcc3 cdeb'
+
+If you want to create a slackware package for the editor
+"tea" instead, do this:
+
+    rbt tea slackware'
+
+If you want to create a gentoo ebuild, you can do this:
+
+    rbt gcc3 ebuild'
+
+A word about conventions ...'
+
+After the ./configure string, we will normally use --prefix first.'
+After --prefix come the other options.'
+You can also create dependency graphs, although this 
+right now is not top notch state of the art ... ;-P'
+See Query for more information about this.'
+
+To search/search for certain packages or entries, 
+do something such as:
+
+    rbt ruby search'
+    rbt gcc s'
+
+If you instead have several chained programs such as e17, then
+you can do something like this:
+
+    rbt e17 wrap url'
+    chained e17 url'
+
+For the crazy guys, you can do this:
+
+    rbt foo all'
+
+This basically will compile EVERYTHING!'
+It is probably not a good idea to do this, 
+but then again, whoever *wants* to do it can do so. 
+Perhaps for test purposes... go on.'
+
+(This is no different than running each program entry 
+in the cookbook.yml manually anyway, no magic at all.)'
+
+If you however want to compile a defined set of programs, 
+there exists another way - chained programs in cookbook.yml'
+
+Via chained programs you simply specify a certain
+chain of compilation. I use this to compile xfce for 
+example, or kde.'
+
+Via <b class="yel">generate_custom_yaml</b> you can 
+dump specific programs into a new yaml file.'
+
+Usage example:
+
+    rbt gcc dump_yaml'
+    rbt gcc dyaml'
+    rbt x generate_custom_yaml'
+
+Installer.rb has different install procedures like "python
+setup.py install", which are stored in a macro such as PINSTALL1'
+You can use this macro in <b>cookbook.yml</b>
+
+# Supported Build Types in the RBT Scripts.
+Currently these Types are supported in the Ruby Build Tools 
+scripts:
+p('ind0px
+  - .rb Files (ruby)','marl3em yel'
+  - .py Files (python)','marl3em yel'
+  - Cmake Files','marl3em yel'
+  - GNU Autoconfigure Files','marl3em yel'
+}
+# ======================================================================= #
+# === Copy the whole yaml database.
+# ======================================================================= #
+You can copy the whole yaml database by doing this:
+
+    rbt x copy_yaml'
+
+# ======================================================================= #
+# === Copy the whole yaml database.
+# ======================================================================= #
+You can copy the whole yaml database by doing this:
+
+    rbt x copy_yaml'
+
+# ======================================================================= #
+# === KDE Konsole tab title
+# ======================================================================= #
+You can disable the renaming of the KDE Konsole tab, even if the
+configuration setting specifies otherwise, on the commandline, by
+issuing something like the following:
+
+    rbt pango dontrenametab'
+    rbt pango dont-rename-tab'
+    rbt pango --dont-rename-tab'
+
+
+# ======================================================================= #
+# === Do not use any configure option
+# ======================================================================= #
+pad1_5em s2em marl3em mart1em','','border:1px dotted darkorchid
+h3' Do not use any configure option'
+If you do not want to use any configure option, use the following
+command:
+
+    rbt htop --dont-use-configure-options'
+
+# ======================================================================= #
+# === Last configure option
+# ======================================================================= #
+pad1_5em s2em marl3em mart1em','','border:1px dotted darkorchid
+You can show the last configure option used by issuing:
+
+    rbt last_options?'
+
+Note that this requires you to have at least compiled one
+program, as otherwise we have not yet stored a configure option.'
+
+# ======================================================================= #
+# === Last compiled options
+# ======================================================================= #
+pad1_5em s2em marl3em mart1em','','border:1px dotted darkorchid
+You can display the last n compiled programs.'
+
+This is done like so:
+
+    rbt --last-compiled?=6'
+    rbt --last-4-compiled?'
+
+
+
+# ======================================================================= #
+# === Program Settings
+# ======================================================================= #
+header Programs Settings'
+
+On traditional Linux structures, system-wide settings will
+be stored under the directory <b>/etc</b>.'
+
+The RBT project will offer the same behaviour - or it will
+default to make use of its own Settings directory, as is
+done on GoboLinux as wel).'
+
+If you want to backup all these stuff, you can use '
+
+l2em '  ProgramsBackup.rb','yel'
+
+# ======================================================================= #
+# === Install only the bin/ subdirectory
+# ======================================================================= #
+header Install only the bin/ subdirectory'
+
+You can also install only the bin/ subdirectory. Every other directory
+that belongs to this program will not be installed.'
+
+Example:
+
+    rbt htop --only-binaries'
+
+# ======================================================================= #
+# === Compile and upload the binaries
+# ======================================================================= #
+header Compile and upload the binaries'
+
+You can compile and then upload all binaries. This currently
+only works for my own FTP host.'
+
+Usage Example:
+
+    rbt make ntrad upload-binaries'
+
+This would upload all binaries of make, from
+<b>/Programs/Current/Make/bin</b>.'
+
+Do also note, for my own system (or if you enable this
+by setting an environment variable called IS_ROEBE to 1),
+we can upload the current ruby to a remote website via
+ftp. The following example shows how to invoke this:
+
+    rbt --upload-ruby-binary
+
+# ======================================================================= #
+# === Environment Variables
+# ======================================================================= #
+header Environment Variables'
+
+You can set certain environment variables, such as LDFLAG and
+similar.'
+
+If you need a generic way to do so, you can do so in the
+yaml file directly, via:
+
+    set_env_variables:
+    GLL_DRV: i915,r600,nouveau,radeonsi,svga,swrast'
+
+This would be equivalent to setting this in a shell, such as
+bash.' 
+
+Note that you can also disable the use of ANY environment
+variable, including CLFAGS, by issuing the following command:
+
+    --do-not-use-special-flags
+
+This will NOT remove the PATH variable though, as otherwise
+we may be unable to compile anything.'
+
+Sometimes you may not want to use ANY environment variable
+and clear ENV. This can be done by issuing the following
+command:
+
+    rbt gtk --clear-env
+
+Note the $PATH setting will be kept though, as otherwise
+we could not compile anything if the compiler is not found
+to be within the $PATH variable.'
+
+# ======================================================================= #
+# === Convert Program
+# ======================================================================= #
+header Convert Program'
+
+You can convert a program too.'
+
+To convert a program such as htop to non-traditional, do this:
+
+     rbt htop to_programs'
+
+# ======================================================================= #
+# === Gobolinux Recipes
+# ======================================================================= #
+header Gobolinux Recipes'
+
+In order to create Gobolinux Recipes for i.e. python, do this:
+
+    rbt python goborecipe'
+
+Note that this will create the recipe in the current working
+directory.'
+
+
+# ======================================================================= #
+# === Create a slackware slack-desc file
+# ======================================================================= #
+header Slackware slack-desc files'
+
+You can create a slackware slack-desc file.'
+
+Do this:
+
+    rbt ruby --generate-slack-desc-file'
+    rbt ruby --slack-desc'
+
+# ======================================================================= #
+# === Standalone Yaml Files
+# ======================================================================= #
+header Standalone Yaml Files'
+
+To create standalone Yaml files, do this:
+
+    rbt ruby create_standalone_yml'
+
+# ======================================================================= #
+# === Tags     (Tags tag)
+    #
+# This documents the /System/Tags hierarchy.
+    #
+# /System/Tags
+# ======================================================================= #
+header /System/Tags' # rf rbt tags
+    p(id: 'tags
+The /System/Tags directory is a special directory. If you set the
+configuration option called <b>use_tags</b> in the file
+<b>configuration.yml</b> to <b>true</b>, then we will honour
+the <b>tags: variable</b> in the individual cookbook yaml file.'
+
+e "What does this actually mean? Let's look at a specific example."
+
+Say you have an <b>editor</b> like vim, defined in a yaml file.'
+
+The yaml file option for vim includes a line such as:
+marl3em 'tags: editor','yel'
+
+Now we have tagged the program vim to be an editor. When vim
+is then compiled, we also symlink the vim binaries into:
+
+    /System/Tags/Editors/vim'
+
+This is somewhat useful in that you can group different
+programs according to what feature they give you.'
+You can also search for tags, via the class
+SearchForTags, or invoke it from the commandline:
+    stag mate # Search for all tags with mate'
+    stag mate WITH_URL # ^^^ same as above but also
+output the URL.'
+
+If at any moment you wish to setup the tags again, do
+this:
+
+    rbt --setup-tags'
+
+Note that you can also combine searching via tags.'
+
+For instance, consider:
+
+    stag gnome python
+
+This would yield all entries that combine both
+of these tags.
+
+Let us look at another example.'
+
+    tags kde ftp'
+
+This will yield the following results:
+
+    1) kasablanca'
+    2) kftpgrabber'
+
+As of February 2017, we will exit when an invalid
+tag is in use. The <b>idea</b> behind this is to clean
+up all the various cookbook files properly, and specify
+the tags that are allowed.'
+
+Note that you can also display all valid tags, that
+is, the ones in /System/Tag, by issuing the following
+command:
+
+    rbt --valid-sys-tags?'
+
+
+ 
+# ======================================================================= #
+# === View Available Licenses
+# ======================================================================= #
+header View Available Licenses'
+
+To view available licenses, do this:
+
+    rbt --view-available-licenses'
+    rbt --licenses?'
+
+You can filter for specific licenses on a given program, such as
+by issuing this command:
+
+    rbt gcc license lgpl'
+
+This would filter for all <b>LGPL license</b> (case-sensitiveness
+is ignored for finding results).'
+
+# ======================================================================= #
+# === Global flags
+# ======================================================================= #
+header Global flags'
+
+Global flags are compile-time flags that you can use, which
+will be appended to GNU configure runs.'
+
+These flags are stored in the file global_flags.yml'
+
+You can either manually modify this file, or use commandline
+instructions to modify this file.'
+
+For example, if you wish to append <b>--disable-static</b>
+to all configure invocations via RBT, then you can issue
+the following command:
+
+    rbt --add-global-flag=--disable-static'
+    rbt --add-global-flag --disable-static'
+
+Likewise, to remove a global flag, you can do:
+
+    rbt --remove-global-flag=--disable-static'
+    rbt --remove-global-flag --disable-static'
+
+You can reset all global flags again, by issuing:
+
+    rbt --clear-global-flags'
+
+
+# ======================================================================= #
+# View Available Programs
+# ======================================================================= #
+header View Available Programs'
+
+To view which programs are available, do this:
+
+    rbt x all_programs?'
+
+As of JUL 2011, the above no longer works. compile is a direct
+alias to Compile.rb now. Try the following instead:
+
+    rbt x all_programs?'
+
+# ======================================================================= #
+# === View Configure Options
+# ======================================================================= #
+header View Configure Options'
+
+You can view the configure options that will be used for a
+program by doing this here:
+
+    config? glibc'
+    rbt glibc qco'
+    rbt glibc query_configure_options'
+
+# ======================================================================= #
+# === Changing Versions
+# ======================================================================= #
+header Changing Versions'
+
+You can always edit the .yml files in question using a simple
+text editor. But sometimes you may only want to update a specific
+entry without opening an editor, and you can do this by issuing
+the following command:
+
+cmd 'newversion ruby-1.9.2'
+
+This would find the entry (i.e. at ruby_cookbook.yml), and change
+the version of ruby to be 1.9.2'
+
+The advantage is that you dont have to open an editor to change it.'
+
+# ======================================================================= #
+# === Edit tag, editor tag
+# ======================================================================= #
+header Editing the cookbooks yaml files'
+
+You can edit individual cookbook entries from the commandline.'
+
+For example, to edit nano, do:
+
+    rbt --edit-file=nano'
+    rbt --edit=nano'
+
+
+
+
+# ======================================================================= #
+# === Configuration Settings. Config tag.
+# ======================================================================= #
+header Configuration Settings'
+
+You can quickly overrule a specific configuration setting by 
+doing something like this:
+
+    rbt rbt.use_ccache'
+
+The above will try to use ccache. If ccache was not found,
+the scripts will not try to make use of it.'
+
+Also note that the configuration will be optional - if 
+you do not have a configuration file, we will assume some 
+default values.'
+
+If you need to find out the configuration directory
+of your running DiamondShell, do this:
+
+    config_dir?
+
+This will give you the main directory for all the
+yaml configuration files.
+
+If you wish to view the whole RBT Configuration, consider
+issuing the following command:
+
+    rbt config?
+
+
+# ======================================================================= #
+# === CMAKE Tag.
+# ======================================================================= #
+header CMake'
+
+RBT supports cmake files.'
+
+Here come some conventions.'
+
+Right now, if a CMake*.txt file was not found, then we will
+not run cmake. Instead, we will try to run GNU configure instead.'
+
+Note that you can force the use of cmake from the commandline
+by passing <b>--cmake</b>, </b>-cmake</b> or <b>cmake</b> to
+<b>bin/rbt</b>. Using <b>--cmake</b> is the preferred variant; I
+recommend to default to this option if you are using it.'
+
+As of Oct 2017, some KDE-related programs insist on /usr/lib/cmake/
+so if the "is on roebe" setting is set, and we use an app-dir prefix,
+then the cmake/ subdirectory will be symlinked into /usr/lib/cmake/,
+but only directories, not files.' 
+
+# ======================================================================= #
+# === LEGALESE TAG
+# ======================================================================= #
+header Legalese / Disclaimer
+
+
+- Once you DOWNLOAD these scripts, they in fact help YOU 
+to automate tasks which YOU could do from a shell _alone_.'
+It is NOT that WE do it for YOU, you are doing so. '
+You are in the whole process (and control), it is thus 
+your own risk to use them. This is also the reason 
+why there are so many settings - we want people to change 
+the scripts to their likings as much as possible and 
+as much as it makes sense.'
+
+It is entirely in your responsibility to ensure that 
+your police state does allow what you do - we have no 
+control over your actions and we do not encourage you to 
+fight against your police state or do any other 
+activities that should not be done ... remember, 
+obedience to the law means freedom, cuz otherwise the 
+armed and armoured guys come in - and get you to jail. ;-)'
+
+e "However we try to ensure our best that these scripts do 
+not teleport your cats to Texas, nor make polar bears appear 
+at your local friseur in Goteborg or bring Ninjas to your 
+aunt's place... Still, use at your own risk."; br
+This section is more or less needed so noone goes and 
+claims that what these scripts are doing is harmful, or 
+is making any <b>derivative work</b> upon others, or that 
+they <b>endorse illegal activity</b>.'
+We dont even care about this crap. Lawyers that 
+fight for their money purse are annoying.'
+Once you use these scripts THEY ARE YOURS.'
+ <b>THEY ARE NOT A DERIVATIVE WORK</b>.' 
+They are scripts which _YOU_ control and in essence _YOU_ 
+use. We only have in common that we helped write these scripts.'
+They are _NOT_ under GPL. They are not even under a BSD 
+licence. If, you need a license, you may license them under 
+the freest possible ruby license.'; br
+Once you have these scripts and use them, they BECOME YOUR 
+PROPERTY and you are FREE TO DO WHAT YOU WANT WITH THEM with 
+<b>one</b> exception - you MUST clearly and openly state that 
+you wrote these scripts IF you publish them.' 
+This means you may not claim that we are the author of 
+your scripts if you decide to relicense them to the public 
+in any way. (If you dont release them to others, it doesnt 
+matter anyway. You can do whatever the hell you want to do 
+with them anyway.)'
+This is the only conditional clause.'; br
+The reason is simple. We dont care if you make money 
+with it, we dont actually care WHAT you do with them but 
+if you use them, <b>leave us totally alone</b>.'
+It must be clear to you that the scripts are 
+YOUR scripts at the moment you download them. We do not own
+the datastream.'
+In a way you immediately become a full sublicensee.'
+If the laws of your state do not allow this, 
+then YOU MAY NOT DOWNLOAD/USE THESE SCRIPTS!'
+
+If you dont want to do this, or are in doubt of your 
+state law, then do <b>NOT</b> download these scripts.'
+
+# ======================================================================= #
+# === Conventions tag. rfrbt Conventions
+# ======================================================================= #
+header Conventions'
+    p('FW4
+This is the reference for important conventions used as
+part of the ruby build tools project.'; br
+- Conventions about naming entries (how to properly name them):
+
+/Users/x/SRC/PHP/phpwiki-1.3.12.tar.bz2','BO yel'
+marl5em '  <span class="green">@program_path</span> = <span class="lightblue">/Users/x/SRC/PHP/phpwiki-1.3.12.tar.bz2</span>'
+marl5em '  <span class="green">@archive_type</span> = <span class="lightblue">.tar.bz2</span>'
+marl5em '  <span class="green">@program_full_name</span> = <span class="lightblue">phpwiki-1.3.12.tar.bz2</span>'
+marl5em '  <span class="green">@base_dir</span> = <span class="lightblue">/Users/x/SRC/</span>+<span class="green">@base_dir</span> # specify the base directory of the program in question'
+marl5em '  <span class="green">@short_name</span> = <span class="lightblue">phpwiki</span>'
+marl5em '  <span class="green">@program_name</span> = <b class="green">@short_name</b>+<b class="green">@program_version</b> 
+Example: <span class="lightblue">phpwiki-1.3.12</span>'
+marl5em '  <span class="green">@program_version</span> = <span class="lightblue">1.3.12</span>'
+
+Since Feb 2012 we follow a new convention when it comes to options
+like --no-harm. All options that include -- will become an integrated
+part of the main case/menu data structure.
+
+# ======================================================================= #
+# cookbook.yml tag
+# ======================================================================= #
+    h4 'Cookbook.yml'
+    e 'You can apply patches, like a linux kernel patch, by adding 
+    an <b>apply_patch:</b> entry in the cookbook.yml file.'
+    e 'Also note that you can use this entry in a conditinal. For
+    instance:
+    br
+    cmd '  apply_patch: http://connie.slackware.com/~alien/slackbuilds/id3lib/build/id3lib-3.8.3_gcc4.diff if PROGRAM_VERSION == 5.14.1'
+    br
+    e 'The above line would only be applied if the program version would
+    match. This allows us to apply patches in a conditional way.'
+    br
+    e 'Since 13.09.2007 you can also manipulate the cookbook.yaml
+    file via a .cgi Page.'
+    br
+    e 'You are currently viewing this page :)'
+    br
+    e 'Just look at the following formular.'
+# ======================================================================= #
+# === Remove Program
+# ======================================================================= #
+pad1_5em s2em marl3em mart1em','RemoveProgram','border:1px dotted darkorchid
+field_with_legend 'Remove Program','yel'
+p('white mar2px pad1px
+  Use this formular if you want to remove a program 
+  from your system.'
+  table 'marl1em'
+    make_row 'Name of program which should be removed:,
+    'remove_this_program','BG_Black lightblue'
+  ctable