roebe 0.5.109

data/doc/diamond_shell_tutorial.cgi

@@ -0,0 +1,2984 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# http://localhost/DATA/PROGRAMMING_LANGUAGES/RUBY/src/roebe/doc/diamond_shell_tutorial.cgi
+# =========================================================================== #
+# Das Tutorial hier muss in Englisch gehalten sein.
+#   http://localhost/PROGRAMMING_LANGUAGES/RUBY/SRC/diamond_shell/lib/diamond_shell/documentation/DIAMOND_SHELL_TUTORIAL.cgi
+# =========================================================================== #
+require 'cyberweb/autoinclude' # rf diatut
+
+english {
+t 'Diamond Shell Tutorial'
+css_style '
+pre {font-size:1.25em}
+p  { margin-left:1em;}
+h2 { color: yellow; margin-top:0.2em; margin-bottom:0px; }
+body { width:98%;}
+div {
+  padding:5px;
+  margin-bottom:10px;
+}
+span.directory {
+  color: orange;
+}
+span.file, b.file {
+  color: lightgreen;
+}
+b.cmd,b.variables {
+  color: orange;
+}
+
+.thin_orange_border {
+  border:     1px solid orange;
+  box-shadow: 0 1px 1px red;
+}
+'
+fav 'RPG/RPG_FAVICON.png'
+body_css_class 'pad1em BG_Black White'
+font_size '1.15em'
+
+GREEN_SQUARE = sg(:green_square, 'marr8px')
+CMD_COLOUR = 'lightblue'
+CMD  = 'marl2em BO '+CMD_COLOUR
+CMD2 = 'marl4em BO '+CMD_COLOUR
+Cyberweb.cmd2 = CMD2
+
+# =========================================================================== #
+# === in_file
+# =========================================================================== #
+def in_file(this_file)
+  e dot(102, 'marr6px')+this_file,'orange BO'
+end
+
+# =========================================================================== #
+# === sin_file
+# =========================================================================== #
+def sin_file(i)
+  return string_s2(i,'orange BO')
+end
+
+ARRAY_HEADER_IDS = []
+
+# =========================================================================== #
+# === command
+# =========================================================================== #
+def command(this_command, optional_id = '')
+  e this_command, CMD, optional_id
+end; alias cmd command # === cmd
+
+# =========================================================================== #
+# === header
+# =========================================================================== #
+def header(content)
+  spacer :center
+  id = content.downcase
+  if id.include? '<' # split at first <
+    index = id.index '<'
+    id = id[0,index]
+  end
+  id = id.gsub(/ /,'_').sub(/^the_/,'')  
+  ARRAY_HEADER_IDS << id
+  # ========================================================================= #
+  # Add a HTML comment to the subsection. This may allow us to
+  # identify the section in a simple way.
+  # ========================================================================= #
+  ee Cyberweb.html_comment('Header for: '+id.to_s, :newline)
+  h2 GREEN_SQUARE+'<a class="marl5px yel" href="#'+id+'">'+content+'</a>','marb8px',id
+end; alias personal_header header # For now, we keep this as alias, but in the future we may use an own header.
+
+doc('wid78') {
+  div {
+    img 'PC/DIAMOND_SHELL/DIAMOND_SHELL_LOGO.png','marl3em', :drag # The logo.
+  }
+  h3 'This document was last updated in <b>March 2017</b>.'
+  br
+  anm 'This is a tutorial for the Diamond Shell (also called DiaShell), 
+  which is a shell written in the programming language Ruby.', margin_left: '2em'
+  br
+  anm 'Please note that this tutorial assumes that you have a Diamond Shell
+  instance running.', margin_left: '3em'
+  br
+  e 'That is, after you have started it, for instance by typing <b>dia</b>
+  in a terminal, you can type in the following commands.'
+  # ========================================================================= #
+  # === Diamond Shell Features tag.
+  # ========================================================================= #
+  header 'Features'
+  p {
+    e 'Listing the most important <b>features</b> of the <b>Diamond Shell</b>:'; br 
+    le3 '# - backup audio, or data, to usb or hdd.'
+    le3 '# - Compiles apps and chain_compiles even more apps.'
+    le3 '# - Type news to open some webpages for news stuff.'
+    le3 '# - Vim "support", which means you use vim to edit stuff.'
+    le3 '# - Trigger certain events. '
+    le3 '# - On startup of this shell, you can define some actions which'
+    le3 '#   need to be done, i.e "rdia rsong" to play random songs. More'
+    le3 '#   about this, please see the section here called "startup".'
+    le3 '# - ISO Creation, CD and DVD burning.'
+    le3 '# - ri-like browsing behaviour.'
+    le3 '# - Open your favourite files by specifing something like "blxorg"'
+    le3 '# - Open a local page in your editor by issuing "rf keyword"'
+    le3 '# - InBuilt help file.'
+    le3 '# use "songs" to view your local songs and songs 44-48
+    to play song 44 up to including song 48'
+    br
+    e 'It really has a lot more features, it is best to look at 
+    the page here - have a look around.'
+    br
+    e 'It should include all what is necessary - and if not, then 
+    I will add this information here.'  
+  }
+  # ========================================================================= #
+  # === Design tag
+  # ========================================================================= #
+  header 'Design Statements and Philosophy'
+  p {
+    e '<b class="orange">@aliases</b> should contain ALL aliases.'
+    br
+    e 'Every string data that the shell gathers - before it is sent
+    to the user - will be stored in a variable. This way you can tap
+    into this variable and make further use of it, for whatever 
+    purpose.'
+    br
+    e '<b class="orange">@this_file</b> points to the last
+    assigned or otherwise used file. Only this, and only
+    one variable may refer to the last used file.'
+  }
+  # ========================================================================= #
+  # === History tag
+  #   rf diacgi history
+  # ========================================================================= #
+  header 'History Support'
+  p('','history') {
+    e 'The Diamond Shell will, by default, log all commands that you
+    did enter via a keyboard interface.'
+    br
+    e 'This behaviour can be <b>turned off</b> by setting <b>enable_history_logging</b>
+    to false in the config file; you can also do this at <b>runtime</b> if
+    you do input <b class="cmd">disable logging</b> or <b>no logging</b>).'
+    br
+    e 'To access this information of your history, you can issue either of
+    these synonymous commands:'
+    br
+    cmd '  h'
+    cmd '  history?'
+    br
+    e 'This will then display the input-history.'
+    br
+    e 'You can also use a position of the history at, i.e. place 5,
+    like this:'
+    br
+    cmd '  history 5'
+    br
+    e 'This will '+sg(:dice,'marr6px')+'<b>substitute</b> the history
+    command of position 5. In other words, this allows you to use history
+    you already did input at an earlier time.'
+    br
+    e 'You can also use the bash equivalent here:'
+    br
+    cmd '  !-2'
+    br
+    e 'Personally I find this less readable, but if you are coming
+    from bash and like this functionality, you can use this in
+    the Diamond Shell as well.'
+    br
+    anm 'Please note - we wont append to the history log if the last
+    command entered is the same as the last entry in the history log
+    (keeping duplicates is not so useful).'
+    br
+    e 'You can empty/clear the history any given time by doing:'
+    br
+    cmd '  empty history'
+    br
+    e 'You can also disable logging of the history by doing:'
+    br
+    cmd '  disable history'
+    br
+    e 'And of course you can disable history support on startup
+    of the Diamond Shell as well:'
+    br
+    cmd '  rda --nohistory # or one of the aliases towards --nohistory'
+    br
+    anm 'We log all commands into the file <b>last_commands.yml</b>.'
+  }
+  # ========================================================================= #
+  # === Gzip Tag
+  # ========================================================================= #
+  header 'Gzip'
+  p {
+    e 'You can compress a string using gzip/zlib:'
+    br
+    cmd 'gzip bla'
+    br
+    e 'However right now I can not think for a good usage scenario 
+    for this ...'
+  }
+  # ========================================================================= #
+  # === Generate Tag
+  # ========================================================================= #
+  header 'Generate Part'
+  p {
+    e 'To generate a new page, issue:'
+    br
+    cmd '  generate BIOS.cgi'
+    br
+    e 'This will simply generate a new .cgi file.'
+  }
+  # ========================================================================= #
+  # === Feedback Tag, Documentation tag
+  # ========================================================================= #
+  header 'Feedback Part'
+  p {
+    e 'To get feedback about every Xorg component, do this:'
+    br
+    cmd 'gfeedback all_of_xorg'
+    br
+    anm 'Note that this will also generate a .html page.'
+    e 'As usual, using "<i>gfeedback help</i>" or "<i>gfeedback ?</i>"
+    will give you some help about this method.'
+    br
+    e 'To feedback the version of a program, do this:'
+    br
+    cmd '  programversion cups'
+    br
+    e 'To feedback the available programs, do:'
+    br
+    cmd 'aprograms'
+    br
+    e 'You can also get feedback about the documentation of Ruby.'
+    br
+    cmd '  docu? Array#sort'
+    br
+    anm 'You can also omit the leading docu? identifier and just
+    use this instead:'
+    br
+    cmd '  Array#sort'
+    br
+    e 'The above would use Ri to feedback information about Ruby.'
+    br
+    e 'This syntax here also works:'
+    br
+    cmd '  docu? Array.sort'
+    cmd '  showdoc Dir.chdir'
+    br
+    e 'And you can also <b>grab</b> the documentation for .rb files:'
+    br
+    cmd '  docu? foobar.rb'
+    br
+  }
+  # ========================================================================= #
+  # === Startup Tag
+  # ========================================================================= #
+  header 'Startup' # rf diatut startup
+  p {
+    e 'The Diamond Shell will allow some things to be done at startup
+    time.'
+    br
+    e 'Please keep in mind that there are aliases possible for your
+    convenience. For instance, the option nocolours and nocolors are
+    synonymous. Also, you can use either - or --, for instance
+    --nocolours will be the same as -nocolours.'
+    br
+    e 'You can decide what you prefer on your own.'
+    br
+    # ======================================================================= #
+    # Commandline options. rf diacgi commandline_options
+    # ======================================================================= #
+    e 'Following comes a table with the currently supported Commandline-Options:'
+    table2 'mart1em pad4px','commandline_options',
+           'margin-left: 6.5em; border-spacing: 12pt',
+      '<i>--version</i>','<b class="lightred">Display the version 
+       number of this shell.</b>',
+      '<i>--time</i>','<b class="lightred">show the current time, in
+       HH:MM:SS notation</b>', 
+      '<i>--nocolours</i>','<b class="lightred">disable colours.</b>',
+      '<i>--run_method</i>','<b class="lightred">run a specific
+       method, then exit.</b>',
+      '<i>--norc</i>','<b class="lightred">do not load the
+       configuration file(s) on startup. This also will ignore
+       the file diamondrc, should it exist.</b>',
+      '<i>--extract</i>','<b class="lightred">simply extract 
+       something, with the aid of the DiamondShell, such
+       as: rda extract all.</b>',
+      '<i>--help</i>','<b class="lightred">show the various help
+       options, then exit</b>',
+      '<i>--debug</i>','<b class="lightred">enable debugging
+       for this Diamond Shell instance</b>',
+      '<i>--silent-startup</i>','<b class="lightred">we will be rather
+       silent on startup</b>'
+    br
+    anm 'If you use a -- option that does not exist, the Diamond Shell
+    will notify you that it does not exist.'
+    br
+    e 'You can also invoke a specific method from the Diamond Shell from
+    the commandline.'
+    br
+    e 'Examples:'
+    br
+    cmd '  rdia --runmethod run_pkg_config'
+    cmd '  rdia --norc'
+    br
+    e 'You can also get tab completion on the commandline.'
+    br
+    e 'For instance, type this:'
+    br
+    cmd Cyberweb.escape_html('  rda --<TAB>')
+    br
+    e 'This will complete to --help'
+    br
+    e 'This will also work if you wish to tab-complete on the 
+    current files in the working directory of your shell.'
+    br
+    e 'So if you have a file called foo.txt, this will work:'
+    br
+    cmd '  rda fo<TAB>'
+    br
+    e 'The startup-related code will also attempt to
+    generated a hash that can be used for swift
+    filesystem-navigation.'
+  }
+  # ========================================================================= #
+  # Method name Format. Methods tag.
+  # ========================================================================= #
+  header 'Call any method'
+  p {
+    e 'You can call any method by its name from within the Diamond Shell.'
+    br
+    e 'The <b>general syntax</b> for this procedure is:'
+    br
+    cmd '  cmethod <span class="yel">name</span>'
+    br
+    e 'Examples:'
+    br
+    cmd '  cmethod foobar # would call the method foobar, if it exists.'
+    cmd '  cmethod clear_history'
+    cmd '  cmethod preformed_action?'
+    cmd '  cmethod history?'
+    cmd '  cmethod upload_screenshots?'
+    br
+    anm 'method and cmethod works the same, method is just an alias
+    to cmethod.'
+    br
+    e 'To list all available methods (which you could then call
+    with <b>cmethod</b>), do this:'
+    cmd '  all_methods'
+    br
+    e 'Also note that you can get feedback about a method since August
+    2015 if you pass the name:'
+    br
+    cmd '  method? yel'
+    cmd '  method? clear_history'
+  }
+  # ========================================================================= #
+  # === Compile Format                                          (compile tag)
+  # ========================================================================= #
+  header 'Compile'
+  p {
+    img 'PC/OS/LINUX/COMPILE.png', '', :drag_and_highlight; br
+    br
+    e 'If you want to get a list of all programs which can be 
+    compiled, do this:'
+    br
+    cmd '  compile help'
+    br
+    e 'You can compile i.e. nano by doing:'
+    br
+    cmd '  compile nano'
+    br
+    e 'In general the syntax is:'
+    br
+    cmd Cyberweb.escape_html('   compile <name>')
+  }
+  # ========================================================================= #
+  # Weekday tag
+  # ========================================================================= #
+  header 'Weekday'
+  p {
+    e 'You can find out the weekday of any date like so:'
+    br
+    cmd  '  wday 13.11.2011'
+    cmd2 '  This day is a Sunday.'
+    br
+    cmd  '  wday today'
+    cmd2 '  This day is a Sunday.'
+    br
+    cmd  '  wday today?'
+    cmd2 '  This day is a Saturday.'
+  }
+  # ========================================================================= #
+  # Prompt tag
+  # ========================================================================= #
+  header 'Prompt'
+  p {
+    e 'You can modify the prompt by doing something like this here:'
+    br
+    cmd '  prompt foo'
+    br
+    e 'Some options exist in regards to the prompt. For a listing of these,
+    query via help, such as this:'
+    cmd '  prompt help'
+    br
+    anm 'The Disco Prompt may be fun to try out.'
+    br
+    e 'You can set a mixed prompt, meaning that directories
+    will be colourized as default, but the / between them
+    will have another colour.'
+    br
+    e "Let's look at a screenshot for this:"
+    img 'PC/DIAMOND_SHELL/DIAMOND_SHELL_MIXED_PROMPT.png',
+        'mar0_5em marl3em'; br
+    e 'And now the code for this:'
+    cmd 'setprompt mixed'
+    br
+    e 'If you wish to clear the prompt again, do this:'
+    cmd '  prompt nil'
+  }
+  # ========================================================================= #
+  # Triggering Events
+  # ========================================================================= #
+  header 'Triggering Events'
+  p {
+    e 'You can trigger (and register) certain events. For instance.'
+    cmd 'in 5 sekunden trigger wecker'
+    e 'Would register this action to be run in 5 seconds from the time 
+    of entering the input..'
+    br
+    e 'A german variant of this works as well:'
+    cmd '  in 3 sekunden starte wecker'
+    br
+    e 'Aside from triggering events, we also have some event-like options
+    that can be used to configure the DiamondShell.'
+    br
+    e 'These can be stored in the configuration file <b>events.yml</b>'
+    e 'For instance, the event :on_remove_directory
+    will invoke a cleanup script, whenever a directory is removed
+    under the /Programs hierarchy (or more accurately, whatever
+    value was set to PROGRAMS_DIR)'
+  }
+  # ========================================================================= #
+  # Information about programs
+  # ========================================================================= #
+  header 'Information about Programs'
+  p {
+    e 'You can get information about programs like this:'
+    br
+    cmd '  pinfo libassuan'
+    br
+    e 'You can also use purl, which gives you the url of a program:'
+    br
+    cmd 'purl wine'
+    br
+    e 'And to also open this URL, do this:'
+    br
+    cmd '  purl wine open'
+    br
+    anm 'This will also set the variable <b class="variables">@last_url</b>.'
+    br
+    e 'In fact, anything that stores a URL should also keep this
+    information in @last_url. At any time you can retrieve this URL
+    by issuing something like:'
+    br
+    cmd '  open_url'
+    cmd '  openurl'
+    br
+    e 'Note that certain other commands also set this url. A rule of 
+    thumb is, that whenever you notice an URL output, then this variable
+    will also be set, and you can then simply use openurl on it easily.'
+    e 'Also note that two commands exist here "url" and "purl". The
+    current way is that if you use "url", and we do not find an URL for 
+    it, we will automatically invoke "purl". I added it because gaining 
+    information was more convenient to me if I only have to type once.'
+  }
+  # ========================================================================= #
+  # === Wecker Tag. Time tag.
+  # ========================================================================= #
+  header 'Wecker and Time'
+  p(id:'wecker'){
+    e 'You can set a Wecker, like when you want to wake up at a 
+    specific time.'
+    br
+    e 'This wecker formula is quite flexible right now:'
+    cmd '  wecker 6 std 8 minuten'
+    cmd '  wecker 855 minuten'
+    cmd '  wecker 2 tage 8 stunden'
+    br
+    e 'Time-related queries also work nicely.'
+    br
+    e 'For instance, if you wish to find out when the next Weekday is, try:'
+    br
+    cmd '  next sonntag'
+    cmd '  next sunday'
+  }
+  # ========================================================================= #
+  # Serve local pages Tag
+  # ========================================================================= #
+  header 'Serve local pages'
+  p(id: 'serve') {
+    e 'You can serve local .cgi pages, just do this:'
+    br
+    cmd '  serve foobar.cgi'
+    cmd '  serve PC.cgi'
+    cmd '  serve /Users/x/DATA/SCIENCE/THINKING_METHODS.cgi'
+    cmd '  serve http://localhost/GAMES/DSA/DSA_COMPUTERSPIELE.cgi'
+    br
+    e 'By default this will output the html code onto your
+    console. Additionally, it will save the result into a
+    .html page, within the directory of the DiamondShell log
+    directory.'
+  }
+  # ========================================================================= #
+  # Notification Format
+  # ========================================================================= #
+  header 'Notification Format and Notifications'
+  p {
+    in_file 'notify.rb'
+    br
+    e 'Right now the format is rather primitive.'
+    br
+    e 'One can use this:'
+    marl1em 'At 06.07.2008 15:00:34 send "hey your kitchen burns"'
+    marl1em 'In 20 seconds send "hey your kitchen is really burning!"'
+    br
+    anm 'If you omit the time, we will assume <b class="lightgreen">
+    12:00:00</b> as the default.','marl2em'
+    anm 'If you use "in 1000 seconds" then we will calculate 
+    the proper time automatically.','marl2em'
+  }
+  # ========================================================================= #
+  # === Open tag.
+  # ========================================================================= #
+  header 'Open'
+  p {
+    e 'The command <b>open</b> allows you to open files.'
+    br
+    e 'Some keywords are used for it, for example:'
+    br
+    cmd 'open last'
+    br
+    e 'Would open the last file. This may be useful when you have
+    opened a local page via some shortcut and want to refer to it.
+    In this case, "last" refers to that file.'
+    br
+    e 'This works also for programs and their project URL, for example
+    try this:'
+    br
+    cmd 'pinfo php open'
+    br
+    e 'This would give you some information about php, and open the webpage
+    in a browser.'
+    br
+    e 'Popular open-related actions include the following:'
+    br
+    cmd 'open wikipedia'
+    cmd 'open pdf'
+    cmd 'open html'
+    br
+    anm 'Note that you can also open URLs - in this case, we will fire
+    up the browser to load it.'
+    br
+    e 'You can open the last assigned file by doing either of the following:'
+    br
+    cmd '  open LAST_FILE'
+    cmd '  open ?'
+    br
+    e 'Note that we will try to glob towards an existing file
+    if we did not find a valid file to open otherwise.'
+  }
+  # ========================================================================= #
+  # === Create tag. create file tag.
+  # ========================================================================= #
+  header 'Create something with the Diamond Shell'
+  p {
+    e 'To <b>create a webpage</b>:'
+    br
+    cmd '  createw location'
+    cmd '  createw $IMG/FUN/ANIMALS'
+    cmd '  createw $IMG/NJOY/'
+    br
+    e 'You can also give a file and split it up. Example:'
+    br
+    cmd '  createw TANRIEL 3'
+    br
+    e 'Would split this file into 3 .html pages.'
+    br
+    e 'You can also create simple files. In UNIX Environments, 
+    you commonly use "touch file_name" to create a file.'
+    br
+    e 'This works when you use quotes too, for instance:'
+    cmd 'touch "foo bar"'
+    e 'Will create a file called "foo bar", including the space.'
+    br
+    e 'You can also create multiple files like so:'
+    br
+    cmd '  touch {temp1,temp2,temp3,temp4}'
+    br
+    e 'The Diamond Shell also tries to be "smart" when it notices you want 
+    to create a file. For instance, when you try to create a .rb file, 
+    we automatically insert a program skeleton into that .rb file.'
+    br
+    e 'This behaviour can be adapted and changed by you.'
+  }
+  # ========================================================================= #
+  # Disable tag
+  # ========================================================================= #
+  header 'Disable'
+  p {
+    e 'Currently if you want to generate certain files, such as 
+    <b>foo.rb</b>, we create a default layout for that.'
+    br
+    e 'This is done by the <b class="file">class CreateFileSkeleton</b>.'
+    br
+    e 'This is usually useful, but can sometimes be annoying. In
+    that case, you can simply disable the autogeneration via:'
+    br
+    cmd '  disable autogeneration'
+    br
+    e 'To find out whether we will autogenerate files/content for
+    files, do this:'
+    br
+    cmd '  autogeneration?'
+    br
+    anm 'To show all available actions for disable, do:'
+    br
+    cmd '  disable HELP'
+  }
+  # ========================================================================= #
+  # Burning tag
+  # ========================================================================= #
+  header 'Burning'
+  p {
+    e 'The Diamond Shell currently relies on i.e. libburn or cdrskin
+    and growisofs to burn CD and DVD iso files.'
+    br
+    e 'You can simulate a "test" run issuing:'
+    br
+    cmd '  burn test'
+    br
+    e 'The program to burn CDs and DVDs can be set in the configuration
+    file.'
+    br
+    e 'You can get its current value by doing:'
+    br
+    cmd '  dvd_burn?'
+    br
+    e 'Alternatively, you can set the run_simulation variable
+    to true like so:'
+    br
+    cmd '  run_simulation = true'
+  }
+  # ========================================================================= #
+  # === Iso tag
+  # ========================================================================= #
+  header 'Creating ISO files'
+  p {
+    e 'You can create .iso files with the Diamond Shell easily.'
+    br
+    e 'One way is to call the following method:'
+    br
+    cmd '  create_interactive_iso'
+    br
+    e 'You can also directly create an iso by doing this:'
+    br
+    cmd '  make_iso /path/to/directory/here'
+    cmd '  make_iso /tmp'
+    cmd '  make_iso /Depot/Games'
+    cmd '  make_iso /Users/x/DATA'
+  }
+  # ========================================================================= #
+  # System tag
+  # ========================================================================= #
+  header 'System Information'
+  p {
+    e 'To get System Information do this:'
+    cmd '  system?'
+    br
+    e 'This will use the following class:'
+    cmd '  SystemChecker.new'
+  }
+  # ========================================================================= #
+  # Input tag, User input tag. Multiline input.
+  # rf dia input
+  # ========================================================================= #
+  header 'Input'
+  p {
+    e 'A few words should be given about user input to the Diamond Shell.'
+    e 'These may be useful to understand certain design decisions.'
+    br
+    e '- Everything that comes after the first encountered <b>#</b> 
+    character will be regarded as a comment.'
+    e 'For instance:'
+    cmd '  exit # we will exit here. What comes after the # is ignored.'
+    br
+    e 'The above command would assume that the user wanted to exit
+    the shell, and the dia-shell will ignore everything that comes
+    after the # (and the # character will also be ignored)'
+    br
+    e 'This is basically the same behaviour you can find in other
+    shells as well.'
+    br
+    e 'The character <b class="yel">;</b> is treated as an 
+    <b>instruction_separator</b>, unless it is found as part of
+    an URL. For example:'
+    cmd 'cd $J; ll'
+    e 'Is assumed to be two different commands: first a change_directory
+    instruction, then a listing_content of a directory instruction.
+    This is consistent with how other shells act.'
+  } 
+  # ========================================================================= #
+  # === Recipe Creation tag
+  # ========================================================================= #
+  header 'Recipe Creation'
+  p {
+    e 'To create a recipe interactively (i.e. write up information about
+    it in a step-by-step fashion), run this command:'
+    br
+    cmd '  interactive_recipe'
+    cmd '  irecipe'
+    br
+    anm 'This is part of the Cookbooks project. We can use this to create
+    a new recipe for installing/compiling a program.'
+  }
+  # ========================================================================= #
+  # Superuser tag. Users tag.
+  # ========================================================================= #
+  header 'Superuser'
+  p {
+    e 'To change the superusername (on UNIX like systems), do this:'
+    br
+    cmd 'become new_name'
+    cmd 'become god # now the superusername would be called "god"'
+    br
+    e 'You can also show which users are available on a given system.'
+    br
+    e 'To do this, issue the following command:'
+    br
+    cmd '  users?'
+    br
+    e 'And you can find a specific User ID, such as User ID 11:'
+    cmd '  user 11'
+    cmd '  user_id 11'
+  }
+  # ========================================================================= #
+  # All tag
+  # ========================================================================= #
+  header 'All'
+  p {
+    e 'You can use a special keyword "all" as alias towards *.'
+    br
+    e 'That way you can apply a common operation on several file 
+    objects, for instance:'
+    cmd '  tovilla; bl 4/all*'
+    br
+    e 'This would open all files within the directory at position 
+    4 in the bluefish editor (or whatever else is your defined
+    editor under @config.editor).'
+    br
+    anmerkung_box('In general, "all" is considered a shortcut for "*",
+      unless a file exists with that name in question.','mart1px','',
+      'width:45%') { :enable_drag_and_drop }
+  }
+  # ========================================================================= #
+  # === Subdirectory tag
+  # ========================================================================= #
+  header 'Showing the size of a subdirectory'
+  p {
+    e 'You can show the file size of a subdirectory.'
+    br
+    cmd '  subdir_size?'
+    cmd '  ssize'
+    br
+    e 'I found this useful because sometimes I need to know how many
+    files are in a subdirectory.'
+  }
+  # ========================================================================= #
+  # === URL tag
+  # ========================================================================= #
+  header 'Program URLs'
+  p {
+    e 'To get the URL of a program, do this:'
+    br
+    cmd '  programurl wine'
+    cmd '  programurl ruby'
+    cmd '  programurl php'
+  }
+  # ========================================================================= #
+  # === Colours
+  #
+  # All about colours in the DiamondShell project.
+  # Colours tag Colors tag. rf diatut colours
+  # ========================================================================= #
+  header 'Colours'
+  p {
+    e 'The Diamond Shell will use colours if you specified that you want
+    to use colours.'
+    br
+    e 'This can set inside of the Diamond Shell, and it can be queried through
+    the method called <b>use_colours?</b>.'
+    br
+    e 'This option can be customized within the config file and it can
+    also be changed at run-time (see the coming section how to do that).'
+    br
+    anm 'If you do not want to use colours, set the variable
+    <b>use_colours</b> to false. This can also be done by 
+    issuing'
+    br
+    e '<b class="marl4em">disable colours</b>','FI'
+    br
+    e 'in your <b class="slateblue">running shell</b>.'
+    br
+    e 'To enable the colours, logically, you can do
+    <b>enable colours</b> again.'
+    br
+    e 'Currently, directories and files will have different colours,
+    as defined in the config file:'
+    br
+    cmd '  colours.yml'
+    cmd '  cat $DIA/YAML/colours.yml # Lets display the content.'
+    br
+    e 'To get a listing of which colours are used in the shell, do:'
+    br
+    cmd '  colours?'
+    br
+    e 'This will display the colours in use too, for instance:'
+    img 'PC/DIAMOND_SHELL/DIASHELL_COLOURS.png','marl2em',
+        'drag_diashell_colours'; br
+    br
+    e 'You can then set a new colour live, by doing something like:'
+    cmd '  colour_for_directories = red'
+    br
+    e 'From this point on, all directories will be displayed in red.'
+    br
+    e 'For fun and giggles, you can also randomly switch the colours,
+    just to try out how things will look.'
+    br
+    e 'For this, do:'
+    br
+    cmd '  switch colours'
+    cmd '  rotate colours'
+    cmd '  switch'
+    cmd '  rotate'
+    cmd '  scolours'
+  }
+  # ========================================================================= #
+  # Ascii tag
+  # ========================================================================= #
+  header 'ASCII'
+  p {
+    e 'You can use ascii art too:'
+    cmd '  to_ascii some_image.jpg'
+    cmd '  to_ascii 1'
+    cmd '  to_ascii 2'
+    cmd '  to_ascii all'
+    e 'Just try these.'
+    br
+    e 'In case we do not find any match, we will try to use a glob(),
+    before we fail finally.'
+  }
+  # ========================================================================= #
+  # IRC TAG.
+  # ========================================================================= #
+  header 'IRC'
+  p {
+    e 'You can use IRC from the Diamond Shell.'
+    br
+    e 'To do this, do:'
+    cmd 'irc channel_name_here'
+    cmd 'irc ruby-lang'
+    cmd 'irc ruby'
+  }
+  # ========================================================================= #
+  # Exiting the shell
+  # ========================================================================= #
+  header 'Exiting the shell'
+  p {
+    e 'To exit the shell do one of these:'
+    cmd 'q'
+    cmd 'exit'
+  }
+  # ========================================================================= #
+  # Password tag, Passwords tag.
+  # ========================================================================= #
+  header 'Passwords'
+  p {
+    e 'To clear the password of your user account, do:'
+    cmd 'nopasswd'
+    anm 'This will simply delete the password.'
+    br
+    e 'To show all available passwords, you may also
+    do:'
+    cmd 'passwords?'
+  }
+  # ========================================================================= #
+  # Fetching all .ogg/mp3 files in a given dir
+  # ========================================================================= #
+  header 'Fetching all .ogg/mp3 files in a given dir'
+  p {
+    cmd 'all ogg'
+    cmd 'all mp3'
+    anmerkung 'Of course you can apply other 
+    criterias as well, such as "all php" or something.'
+    br
+    e 'The result will be stored in <b class="variables">@file_listing</b> 
+    which you can manipulate lateron.'
+    e 'To retrieve it, simply type it in the shell.'
+    cmd '  @file_listing'
+    e 'Since Sep 2011 the following also works:'
+    cmd '  @_'
+    anm 'Since Jan 2012 we allow to shuffle the dataset stored in
+    <b class="variables">@file_listing</b> by doing:'
+    cmd 'shuffle'
+  }
+  # ========================================================================= #
+  # === Download tag downloading tag down tag load tag.
+  # ========================================================================= #
+  header 'Downloading'
+  p {
+    e 'You can download a package like so:'
+    br
+    cmd 'download http://ftp.gnome.org/pub/gnome/sources/pygtksourceview/2.3/pygtksourceview-2.3.0.tar.bz2'
+    br
+    e 'If you want to download <b>to</b> a specific directory, 
+    use the "<b>to</b>" keyword like this:'
+    br
+    cmd '
+    download 
+    http://ftp.gnome.org/pub/GNOME/sources/gtk+/3.15/gtk+-3.15.4.tar.xz
+    to /Depot/j'
+    cmd 'download  
+    http://ftp.gnome.org/pub/GNOME/sources/gtkmm/3.17/gtkmm-3.17.50.tar.xz
+    to /Depot/j'
+    br
+    anm 'Note that this can work with special targets/variables
+    as well for your conenvience. For example:'
+    cmd 'url = http://www.calno.com/evilvte/evilvte-0.3.1.tar.gz'
+    cmd 'download url to 1'
+    anm "would download to the location saved at slot 1, which defaults 
+    to ENV['MY_SRC'], or expanded, would become /Users/x/SRC on my system."
+    e '<b>url</b> in this case is a variable which was asigned to some url
+    before.'
+    br
+    e 'Whenever we download something, we will also set the variable
+    @last_downloaded.'
+    br
+    e 'You can then use this variable to manipulate the file in question.'
+    br
+    e 'For example, to <b>download</b>, and then <b>extract</b> the file, you
+    can use this:'
+    br
+    cmd 'download ftp://ftp.astron.com/pub/file/file-5.03.tar.gz to /Depot/j'
+    cmd '  extract last_downloaded'
+    br
+    e 'Also note that you can download Youtube videos by just passing
+    in the URL of it.'
+    br
+    e 'The Diamond Shell will automatically try to download and also
+    extract the audio file into a .mp3 file.'    
+  }
+  # ========================================================================= #
+  # === Displaying file content
+  #
+  # Header tag. Head Tag. cat tag.
+  # ========================================================================= #
+  header 'Displaying File Content'+sg(:develop,'marl1em')
+  p {
+    e 'Use cat or get_file_content to display the file content
+    of a file '+sg(:file)+'.'
+    br
+    e 'For example, if the file is called <b>foobar.txt</b>, do this:'
+    br
+    cmd '  cat foobar.txt'
+    br
+    e 'You can specify a range:'
+    br
+    cmd '  cat file 10-20'
+    br
+    e 'This would display only line 10 up to 20.'
+    br
+    anm '  This works only on files, i.e. not on directories.','marl2em'
+    br
+    anm '  Also note that this slicing for files should work in general,
+    and can even be extended. Look at playing video for an example.'
+    br
+    e 'You can also read a header, via:'
+    br
+    cmd '  header foo'
+    cmd '  header 5'
+    br
+    e 'How many lines will we display that way? By default we will
+    show the first 25 lines, but you can change this setting, by
+    doing something like:'
+    br
+    cmd '  header? 10'
+    br
+    e 'This setting can be saved, by issuing <b>save</b>.'
+    br
+    anm 'Note that if the file is a .rb file, we will try to use
+    the Coderay gem to parse the result.'
+    br
+    e 'As of August 2014, we will also allow you to use the
+    last file that was assigned when you use ?:'
+    br
+    cmd 'cat ?'
+    br
+    e 'You can append into a file directly by doing this:'
+    br
+    cmd '  cat this_file >> ~/A_FILE_IN_MY_HOME_DIR'
+    cmd '  cat 4 >> ~/A_FILE_IN_MY_HOME_DIR'
+  }
+  # ========================================================================= #
+  # Show source tag
+  # ========================================================================= #
+  header 'show-source'
+  p {
+    e 'You can show the source of a <b>ruby method</b> by
+    issuing this command:'
+    br
+    cmd '  show-source run'
+  }
+  # ========================================================================= #
+  # Undo tag
+  # ========================================================================= #
+  header 'undo'
+  p {
+    e 'You can undo certain actions. Right now <span class="ud">only</span>
+    file-move actions can be undone. For instance, let us assume that you
+    have a file called "test" in the directory /tmp, and that you moved
+    this file to the directory /home, like so:'
+    br
+    cmd '  mv /tmp/test /home'
+    br
+    e 'Now you can do this command:'
+    br
+    cmd 'undo'
+    br
+    e 'And the file will be moved back to its old place.'
+    br
+    e 'This is not extremely useful yet, but I will probably add code
+    to allow a more general purpose undo action at a later time.'
+  }
+  # ========================================================================= #
+  # Move tag, mv tag.
+  # ========================================================================= #
+  header 'Move'
+  p {
+    e 'You can move files and directories to new locations.'
+    br
+    e 'This can be done like so:'
+    br
+    cmd '  mv foo /tmp'
+    br
+    e 'The above command would move the file foo to the directory
+    <b>/tmp</b>. This is similar to how bash or zsh acts.'
+    br
+    e 'Note that you can also move multiple files.'
+    br
+    e 'The syntax for this would be:'
+    br
+    cmd 'mv temp{1,2,3,4} $JJJ'
+    br
+    e 'This would try to move these directories or files to
+    whatever value is stored in $JJJ (which, on my system,
+    points to the directory /Depot/jjj).'
+  }
+  # ========================================================================= #
+  # === Screenshot tag
+  # ========================================================================= #
+  header 'Screenshot'
+  p {
+    e 'You can use `scrot` to make a screenshot. A common alias is:'
+    br
+    cmd 'shot'
+    br
+    e 'The first argument is an <i>optional</i> name for the .png file
+    that will be created:'
+    br
+    cmd 'shot my_desktop'
+    br
+    e 'The second argument is an optional delay (in seconds)'
+    br
+    cmd 'shot my_desktop 5 # 5 seconds delay'
+    br
+    anm 'Note that as of April 2014, we will automatically upload that
+    screenshot to a remote host if the environmental variable
+    <b>IS_ROEBE</b> is set to 1.'
+    br
+    anm 'The code for screenshots is stored in the file
+    <b>screenshot.rb</b>.'
+  }
+  # ========================================================================= #
+  # === Keywords tag
+  # ========================================================================= #
+  header 'Ruby keywords'
+  p {
+    e 'To get a list of all ruby keywords, do this:'
+    br
+    cmd '  keywords?'
+  }
+  # ========================================================================= #
+  # === Save tag
+  # ========================================================================= #
+  header 'Saving'
+  p {
+    e 'You can save to a file, for instance, like this:'
+    br
+    cmd 'save to $J/foo'
+    br
+    e 'This would save whatever is inside <b class="variables">
+    @usher.string</b> into this file. (By default it will append,
+    though this behaviour may change lateron.)' 
+  }  
+  # ========================================================================= #
+  # === Merging files tag
+  # ========================================================================= #
+  header 'Merging files'
+  p {
+    e 'Merging ogg files can be done like so:'
+    br
+    cmd '  merge x.ogg file1.ogg file2.ogg file3.ogg'
+    br
+    e 'You can omit arguments too as in:'
+    br
+    cmd '  vobmerge # will pickup all .vob files in the directory'
+  }
+  # ========================================================================= #
+  # === Ftp tag. rf diatut ftp
+  # ========================================================================= #
+  personal_header 'Ftp'
+  p {
+    e "Now let's talk a bit about the FTP functionality in the Diamond Shell."
+    br
+    e 'You can upload a whole project by issuing this:'
+    br
+    cmd '  ftp_upload project dia'
+    br
+    e 'Of course that task must have been registered somewhere first.'
+    br
+    e 'To show all available tasks, do either of these:'
+    br
+    cmd '  show available tasks'
+    cmd '  stasks'
+    br
+    anm 'Note that upload is an alias.'
+    br
+    anm 'Tab-completion may be possible.'
+  }
+  # ========================================================================= #
+  # === Birthdays tag.
+  # ========================================================================= #
+  personal_header 'Birthdays'
+  p {
+    e 'The Diamond Shall has the - not too overfuly useful - option to
+    display upcoming Birthdays. This requires one to write or define a
+    custom yaml file.'
+    br
+    e 'Currently this is set to 5 days in advance.'
+    br
+    e 'It will report in ways like:'
+    br
+    cmd  '  We found these Birthday candidates:'                                                                               
+    cmd2 '  Wolfgang: 23.01.2012'
+    br
+    e 'To query this, you can do this:'
+    br
+    cmd '  bday?'
+    br
+    e 'If you wish to look n days into the future, you can pass it as
+    an argument:'
+    br
+    cmd '  bday? 30'
+    cmd '  bday? 120'
+    br
+    anm 'Do note that the whole Birthday subsection will only work if you
+    actually have such a yaml file defined. If you have not, the whole
+    subsection will be ignored.'
+  }
+  # ========================================================================= #
+  # === Aliases tag. Unalias tag.
+  # ========================================================================= #
+  header 'Aliases'
+  p {
+    e 'All aliases are kept in the instance variable
+    <b class="variables">@aliases</b>.'
+    br
+    e 'You can display this variable any time by issuing
+    either of the following two commands:'
+    br
+    cmd '  @aliases'
+    cmd '  aliases?'
+    br
+    e 'To get the content of an alias, either type this:'
+    br
+    cmd '  alias name_of_alias'
+    cmd '  alias pwr'
+    br
+    e 'Positional arguments are also possible (if an
+    alias with that number does not exist, that is):'
+    br
+    cmd '  alias 567'
+    br
+    e 'Or simply type the following to get all these aliases:'
+    br
+    cmd '  @aliases'
+    br
+    e 'You can of course also unset an alias. I recommend you 
+    use this syntax:'
+    br
+    cmd '  unalias name_of_alias'
+    cmd '  unalias pwr'
+    br
+    e 'You can also unalias if you give a number instead.
+    unalias 123 would try to unset the alias at position
+    123.'
+    br
+    e 'To set an alias, you can do something like this:'
+    br
+    cmd '  alias foo=55'
+    br
+    e 'This would set the key <b>foo</b> to the value
+    of 55.'
+    br
+    anm 'As of January 2014, I can <b>download my remote
+    aliases</b> by issuing:'
+    br
+    cmd '  download_aliases'
+  }
+  # ========================================================================= #
+  # === buffer tag
+  #
+  #   rf diacgi buffer
+  # ========================================================================= #
+  header 'The Clipboard buffer'
+  p(id: 'buffer') {
+    e 'The Diamond Shell uses a <b>Clipboard buffer</b>.'
+    br
+    lem2 'This file is stored at
+    `<b class="file">diamond_shell/base/clipboard.rb</b>`.'
+    br
+    e 'You can obtain the current value of the Clipboard buffer
+    via:'
+    br
+    cmd 'buffer?'
+    cmd 'b?'
+    br
+    e 'If you want to assign it to a specific string, do start
+    this with the token:'
+    br
+    cmd '{'
+    br
+    e 'Yup, this is the start command for the buffer. I thought that
+    using {} as delimiter to enter into the Buffer directly would be
+    nice, so that is why I added that featre.'
+    br
+    e 'Also note that since December 2011 we will additionally try
+    to use xclip when using the buffer. This way, you should be
+    able to manipulate the buffer on your own.'
+    br
+    e 'You can clear the buffer any time by doing:'
+    br
+    cmd 'clear buffer'
+    br
+    e 'Since <b>March 2012</b> we also use a file called <b class="file">
+    buffer.yml</b>. If this file exists on startup, then we will load it
+    into the current buffer.'
+    br
+    e 'Note that we also use the Xorg buffer on Linux.'
+    br
+    e 'This Xorg buffer understands some special commands such as:'
+    br
+    cmd '  buffer generate ruby'
+    br
+    e 'This will generate ruby code.'
+    br
+    e 'You can store this buffer to a file, as in the following way:'
+    br
+    cmd '  save buffer to $J/jtj.rb'
+  }
+  # ========================================================================= #
+  # === index tag.
+  # ========================================================================= #
+  header 'Index'
+  p {
+    e 'By default, Diamond Shell assigns every entry in a given 
+    directory a number, the so-called
+    <i class="orange">index number</i>.'
+    br
+    e 'This number is displayed on the left side usually, and it 
+    may be used by you as a shortcut to access a specific file as
+    well.'
+    br
+    e 'For example, if you have two files in a given directory,
+    called "long_name_of_a_file_1" and "long_name_of_a_file_2"
+    you can use numbers to work with them instead, like so:'
+    br
+    cmd '  cat 1'
+    cmd '  cat 2'
+    br
+    e 'The following small screenshot shows this - the <i class="orange">
+    index number</i> can be seen in green colour:'
+    imgbr 'PC/DIAMOND_SHELL/DIAMOND_SHELL_INDEX_NUMBER.png',
+          'thin_orange_border pad1em marl4em mart1em',:drag
+    br
+    cmd '  cp 2 $J # This would copy the file at second position
+    to whatever value is contained in $J.'
+    lem 'On my system, this defaults to the directory <b>/Depot/j</b>.'
+    br
+    anm 'Do note that you can turn off showing the index in your config
+    file (look at the configuration option <b>display_index</b>):'
+    br
+    cmd '  disable display_index'
+    cmd '  no index'
+  }
+  # ========================================================================= #
+  # === pc packages tag
+  # ========================================================================= #
+  header 'Query .pc Packages'
+  p {
+    e 'You can query <b>.pc files</b> in a simple manner through the Diamond
+    Shell. pkg-config allows you to query installed libraries on
+    your computer, in partcular software that was compiled from source.'
+    br
+    e 'In order to do so and query the information found in .pc files
+    and whether it is available on your system, you can simply append
+    a <b>?</b> to the name.'
+    br
+    e 'For instance:'
+    br
+    cmd2 '  libpng?'
+    cmd2 '  mono?'
+    cmd2 '  xtables?'
+    cmd2 '  ruby?'
+    br
+    anm 'This will not always work, but it will probably make your life 
+    a bit easier sometimes, whenever you want to know which .pc files
+    are installed on your system.'
+    br
+    anm 'Note that on Windows the above will not work - the reason for
+    this is that most ruby-users on Windows will possibly not have
+    pkg-config .pc files.'
+  }
+  # ========================================================================= #
+  # === Appending to a file
+  # ========================================================================= #
+  header 'Appending to a file'
+  p {
+    e 'As it is the case with other shells, you can use >> to save
+    something to a file:'
+    br
+    cmd2 'foobar >> this_new_file'
+    br
+    e 'This would save foobar into the file
+    `<span class="file">this_new_file</span>`'
+    br
+    e 'As a reminder, in Bash it works a bit differently, in that the
+    stream is redirected. In Diamond Shell, we use a simplified approach.'
+    br
+    e 'Also note that you can use macros here, such as the 
+    <b>@buffer</b> macro.'
+    br
+    e 'For instance, if you do:'
+    br
+    cmd '@buffer >> foo'
+    br
+    e 'Then we will store the content of the buffer into the
+    file <b>foo</b>.'
+    br
+    anm 'Note that you can also use > which will create a new 
+    file and then add the content to that file.'
+  }
+  # ========================================================================= #
+  # === copy tag cp tag.
+  # ========================================================================= #
+  header 'Copy'+sg(:copy, 'marl1em','drag_copy')
+  p {
+    e 'You can copy a complete directory. By default, we will copy to 
+    the current working directory if no argument was given.'
+    br
+    e 'You can test this by doing something like:'
+    br
+    cmd '  cp to $JJ'
+    br
+    cmd '  copy_dir to $JJ'
+    br
+    anm 'It is recommended to use the second variant if you wish to copy
+    a directory; copy_dir is a shortcut for copy_directory. Both variants
+    would work.'
+    br
+    e 'You can also copy whatever is stored inside 
+    <b class="orange">@file_listing</b> to another target.'
+    br
+    e 'The following example shows this, by first entering to your directory
+    containing all audio songs, then fetching all .ogg files, then copying
+    them to whatever is held in the environment variable J:'
+    br
+    cmd '  cd $SONGS'
+    cmd '  all ogg'
+    cmd '  cp to $J'
+    cmd '  cp here to # this willc opy the content of @_ variable
+    to the current working directory'
+    cmd '  cp to here # Same as above'
+    cmd '  cp all to $JJ # this copies the content of this directory to 
+    the environment variable $JJ'
+    cmd '  cp all to here # Copy to the current directory'
+    br
+    anm 'More about the environment can be read 
+    <a href="#environment" class="slateblue">here</a>.'
+    br
+    e 'Please also note that the variable @target_directory can be 
+    set to a specific directory like so:'
+    br
+    cmd '  target /Depot/Song'
+    br
+    e 'The effect is that this variable can now be used to copy files 
+    or directories to this target. So after you have done the above,
+    you can then do this:'
+    br
+    cmd '  cp /Home/OldSongs/'
+    br
+    e 'And it will, <b>in this situation</b>, copy it to this directory.
+    If this was not set, a notification will alert the user that the
+    target directory is missing in this action.'
+    br
+    e 'Of course, if you manually give another target, then we 
+    will use this instead.'
+    br
+    e 'If for some reason you want to copy all images under 
+    a specific directory to a new target, use this:'
+    br
+    cmd 'cp_images'
+    br
+    e 'Note that this will copy to the directory you are in.'
+    br
+    e 'Useful to have is that you can also assign all current files in a
+    directory, and then copy these to somewhere else even at a later time.'
+    br
+    e 'This works like so:'
+    br
+    cmd '  assign all'
+    cmd '  cp to here'
+    cmd '  cp to $J # you can use absolute targets too, of course.'
+  }
+  # ========================================================================= #
+  # Environment tag env tag.
+  # ========================================================================= #
+  header 'Environment'
+  p {
+    e 'To retrieve the value of an environment variable, do something
+    like this:'
+    br
+    cmd '  e $AUDIO'
+    cmd '  echo $AUDIO'
+    br
+    anm 'Note that if you input just $AUDIO then we will cd into that
+    variable if it is a directory.'
+    br
+    e 'The key lies in using $ to denote the variable in question, and 
+    e is used to echo the content.'
+    br
+    anm 'If the variable was not found or defined, we will display a 
+    little helpful note to the user.'
+    br
+    e 'Example:'
+    br
+    cmd '  e $A_VARIABLE_THAT_REALLY_DOES_NOT_EXIST'
+    br
+    e 'Also note that if you do something like:'
+    br
+    cmd '  e $L*'
+    br
+    e 'Then we will try to feedback all environment variables starting
+    with L.'
+    br
+    e 'To feedback all known environment variables, do this:'
+    br
+    cmd '  environment?'
+    br
+    e 'You can also sync towards the environment variables.'
+    br
+    e 'What this means is the following:'
+    lem 'Consider that you have defined an environment variable
+    called $EDITOR.'
+    br
+    e 'You can sync towards this by issuing:'
+    br
+    cmd2 '  sync_to_environment'
+    cmd2 '  sync_to_env'
+    br
+    e 'This will update the configuration settings, such
+    as by modifying the file called <b>editor.yml</b> which keeps
+    stored which editor we will be using.'
+  }
+  # ========================================================================= #
+  # === Help tag. rf diacgi help
+  # ========================================================================= #
+  header 'Help'
+  p {
+    e 'The helpfile section can be invoked via:'
+    br
+    cmd 'help'
+    br
+    e 'The colouring of the helpfile section is done via the class
+    DiamondHeader.'
+    br
+    e 'Additionally, we can display useful help information before we startup.'
+    br
+    e 'We do this via:'
+    br
+    cmd 'rda --help'
+    br
+    e 'Below is a (partial) screenshot from how the Diamond Shell Help Menu
+    looked in <b>April 2014</b>:'
+    br
+    img 'PC/DIAMOND_SHELL/DIAMOND_SHELL_HELP_MENU.png',
+        'marl5em bblack2', :drag
+    br
+    e 'As of September 2014, documentation was added for the commands
+    displayed when the input "help" is issued. This documentation is
+    stored in the <b>class DocumentedHelpOptions</b>, residing in the file
+    <b class="file">
+    standalone_classes/documented_help_options.rb
+    </b>.'
+    br
+    e 'You can obtain a slightly longer explanation for most of these options
+    by <b>prefix</b> a leading <b>?</b>, so for instance:'
+    br
+    cmd2 '  ?touch'
+    cmd2 '  ?grabc'
+    cmd2 '  ?symlink'
+    cmd2 '  ?windows'
+  }
+  # ========================================================================= #
+  # Gist tag.
+  # ========================================================================= #
+  header 'Gist'
+  p {
+    e 'You can use Gist from the Diamond Shell, via the gist gem.'
+    br
+    e 'Example:'
+    br
+    cmd 'gist foobar.rb'
+    br
+    anm 'This would upload the foobar.rb file to gist github.'
+  }
+  # ========================================================================= #
+  # === Modes tag.
+  # ========================================================================= #
+  header 'Modes'
+  p {
+    e 'There are several modes in the Diamond Shell, even a hidden mode - 
+    the play mode.'
+    br
+    e 'If the play mode is active, we will try to play all video
+    files in the currenty directory.'
+    br
+    e 'You can set a specific mode by doing something like this:'
+    br
+    cmd '  mode = editor'
+    br
+    e 'You can query the currently active mode like so:'
+    br
+    cmd 'mode?'
+    br
+    e 'This would output "edit" in the above example.'
+    br
+    anm 'Mode-specific code can be found in the file <b>mode.rb</b>.'
+    br
+    e 'The idea behind the modes is that we will attempt to provide a
+    "default action" onto a target file when otherwise no action
+    is associated with that file type.'
+    br
+    e 'If you type in the name of an existing .mp3 file, we will
+    try to play it. But what if you have some unknown file?
+    In this case, we may try to open it in the browser, or
+    open it in the editor. And this is the reasoning behind
+    the modes in Diamond Shell.'
+    br
+    e 'The default mode is edit by the way, so the Diamond Shell
+    will assume that you attempt to edit an existing file.'
+  }
+  # ========================================================================= #
+  # === View map
+  # ========================================================================= #
+  header 'Viewing a Map'
+  p {
+    e 'You can view a map (Stadtplan):'
+    br
+    cmd '  stadtplan landstrasse 22'
+    br
+    e 'Right now this defaults to Vienna, my hometown.'
+    br
+    e 'If anyone requires this for another town, well. Write to me so
+    that I can add it.'
+  }
+  # ========================================================================= #
+  # === Emails tag
+  # ========================================================================= #
+  header 'Emails'
+  p {
+    e 'Thanks to the mail gem, we can send emails to other people (or to
+    yourself).'
+    br
+    e 'Currently this is somewhat limited - simply type "email" and
+    an interactive section can be used.'
+    br
+    e 'I will possibly extend this lateron (Current date: December 2015)'
+  }
+  # ========================================================================= #
+  # Show tag. Output tag.
+  # ========================================================================= #
+  header 'Show something'
+  p {
+    e 'You can show files by doing something like:'
+    br
+    cmd 'll'
+    br
+    e 'By default this will <b>not show hidden files</b>. There are at least
+    two ways to show hidden files though, since obviously this is an important
+    part of working with a filesystem.'
+    br
+    e 'The first way is to explicitely tell the shell once that
+    you want to see hidden files.'
+    br
+    e 'You can do this simply by issuing:'
+    br
+    cmd '  show hidden'
+    br
+    e 'From this point onwards, you will always see hidden files.'
+    br
+    e 'The other way is to use a switch, such as:'
+    br
+    cmd '  ll --almost-all'
+    br
+    e 'This is akin to <b>Bash</b>.'
+    br
+    e 'You can show the content of a file via <b>cat</b>, as in:'
+    br
+    cmd '  cat foo.rb'
+    br
+    e 'If the file <b>foo.rb</b> does exist, this command will show
+    you the content of that file. If coderay is installed, and if
+    you enabled colours, we will use Coderay on the terminal output
+    to also display colours.'
+    br
+    anm 'You can disable coderay output, which will try to 
+    colourize ruby-code on the commandline, by doing:'
+    br
+    cmd '  disable Coderay'
+    cmd '  disable coderay # this also works'
+    br
+    e 'You can sort the output by doing something like:'
+    br
+    cmd '  sort_by size'
+    br
+    e 'Obviously, the above command will <b>sort by size</b>.'
+  }
+  # ========================================================================= #
+  # Removing directory tag. Remove Tag.
+  # ========================================================================= #
+  header 'Removing something - removing files or directories'
+  p {
+    e 'You can remove directories via the <b>remove</b> subcomponent
+    i.e. by doing this:'
+    br
+    cmd 'remove foobar/'
+    cmd 'remove /tmp'
+    br
+    in_file 'protected_directories.yml'
+    br
+    e 'You can specify directories which should <b>never</b> be removed,
+    within the file <b>protected_directories.yml</b>. I recommend to
+    add the directory / to that yaml file.'
+    br
+    e 'You can also <b>add new directories</b> to this list:'
+    br
+    cmd '  protect /some/directory'
+    cmd '  protect /tmp'
+    br
+    e 'Please also note that you can specify a number as well, e. g.
+    the following would remove the first entry in a directory:'
+    br
+    cmd '  remove 1'
+    br
+    anm 'This can sometimes be a bit confusing, so in this case you
+    can just use the real name; I once wanted to be able to also
+    make use of numbers, so this is why this functionality exists.'
+    br
+    e 'Syntactic sugar also exists. To remove all directories in a
+    given directory, you can issue the following command:'
+    br
+    cmd '  remove all directories'
+    br
+    anm 'Note that german words also work as aliases to these actions.'
+    br
+    e 'You can also remove files that contain a " " character.
+    For instance, consider a file that is called <b>foo bar.txt</b>.'
+    br
+    e 'In order to remove such a file, try this, including the quotes:'
+    br
+    cmd '  rm "foo bar.txt"'
+  }
+  # ========================================================================= #
+  # Reading content tag
+  # ========================================================================= #
+  header 'Reading content'
+  p {
+    e 'The most obvious way for reading content is by reading a file.'
+    br
+    e 'To do this one would do something like:'
+    br
+    cmd '  read_file /location/of/file.txt'
+    cmd '  read_file /Users/x/DATA/STD.bfproject'
+    cmd '  rfile /etc/hosts'
+    br
+    e 'Some aliases exist for this, i.e. "readfile" would work also,
+    as would "cat".'; br
+    e 'The configuration option "padding" is also used to pad the file
+    to the left.'
+    br
+    e 'You can obtain the current value of padding by doing:'
+    br
+    cmd 'padding?'
+    br
+    e 'And you can set it to a new value by doing something like this
+    here:'
+    br
+    cmd '  padding = 15'
+    br
+    anm 'As of January 2014, the padding of input is done when we
+    read in a file. This may change at a later time again.'
+    br
+    anm 'If you do not like any padding at all, you can either
+    set padding to 0, or do this:'
+    br
+    cmd '  disable padding'
+    br
+    e 'Disable is the general way to disable some functionality, either
+    as part of the Diamond Shell, or from the underlying system.'
+  }
+  # ========================================================================= #
+  # === Downcasing tag.
+  # ========================================================================= #
+  header 'Downcasing'
+  p {
+    e 'To <b>downcase every file in a given directory</b> (might be useful if
+    you want to downcase VIDEO1.VOB to video1.vob, for instance), simply do
+    one of the following variants:'
+    br
+    cmd '  downcase *'
+    cmd '  downcase all'
+    cmd '  downcase everything'
+  }
+  # ========================================================================= #
+  # === Upcasing tag, Upcase tag.
+  # ========================================================================= #
+  header 'Upcasing'
+  p {
+    e 'You can upcase directory and file names by doing something like
+    this:'
+    br
+    cmd 'upcase all directories'
+    br
+    e 'This would upcase all directories '+sg(:directory)+' in the current
+    directory.'
+    br
+    e 'Obviously you can also upcase single files too:'
+    br
+    cmd '  touch test_file'
+    cmd '  upcase test_file'
+    br
+    e 'Now you will have a file called <b>TEST_FILE</b>.'
+  }
+  # ========================================================================= #
+  # === Backtick tag, Backticks tag.
+  # ========================================================================= #
+  header 'Backticks'
+  p {
+    e 'You can use `` backticks to run a command, similar as to
+    how ruby allows you to do.'
+    br
+    e 'Usage example:'
+    br
+    cmd '`ls`'
+  }
+  # ========================================================================= #
+  # === enter directory tag, change directory. cd tag.
+  #
+  # rf diacgi#cd
+  # ========================================================================= #
+  header 'Enter directory'
+  p('','cd') {
+    lem 'If you want to enter a '+sg(:directory,'marr0_5em')+'directory,
+    you just type the <b>name</b> of it, or you prefix via "cd", such as
+    in "cd /tmp".'
+    br
+    e 'The Diamond shell will attempt to enter the upcased version
+    of said diretory as well if it exists, ie if you enter "foobar"
+    dia-shell will also try to enter a dir FOOBAR. (This will happen
+    silently - if a directory called FOOBAR does not exist, we will
+    not generate any warning message at all. This feature exists
+    only due to convenience.)'
+    br
+    e 'A partial match may also be possible. For instance, if you have
+    a directory called Reallife/ and you type "realli" then this will
+    be expanded towards Reallife.'
+    br
+    lem 'Also note that whenever you change the directory we will 
+    register the new directory in a yaml file, so that we can remember 
+    which directory was the last one you worked in. This information
+    is stored in the file '+sin_file('last_directory.yml')+' and
+    you can also query this via last_directory?.'
+    br
+    e 'You can use numbers instead of names to enter directories.'
+    br
+    e 'Number 1 will correspond to the first directory, number 2
+    will correspond to the second directory and so on.'
+    br
+    e 'Example:'
+    br
+    cmd 'cd 3 # would enter the third directory'
+    br
+    e 'This works with english words as well. For instance, the
+    two following examples mean the same - enter the
+    first directory.'
+    br
+    e 'Both examples work:'
+    br
+    cmd 'cd 1'
+    cmd 'cd first'
+    br
+    anm 'Note that if there is a directory called FOO and you
+    type "cd FOo", the shell will attempt to correct this to FOO
+    automagically.' 
+    br
+    e 'You can - by convenience - also enter an archive.'
+    br
+    e 'We will assume in this case that you want to extract
+    that specific archive before entering it.'
+    br
+    e 'Example:'
+    br
+    cmd 'cd rpm* # where rpm* points to the archive rpm-1.0.0.tar.bz2'
+    br
+    e 'Also note that the aliases wd1 wd2 etc.. are being treated 
+    as instruction to "jump to" specific directories. More about
+    this at the section
+    <a href="#jumpers" class="slateblue">Jumpers</a>.'
+    br
+    anm 'Note that every time you change directory or copy 
+    something, we set a variable called $LAST_DIR. You can
+    use this variable, like so:'
+    br
+    cmd 'cp * /System/Fonts'
+    cmd 'cd $LAST_DIR'
+    cmd 'cd $LD'
+    br
+    e 'You can also change directory to the last created directory by
+    issuing:'
+    br
+    cmd '  cd !#:1'
+    br
+    anm 'Also note that if you use cd(), and pass a number to it, we will
+    assume that you wish to enter only <b>directories</b> or archives
+    from the current directory.' 
+    br
+    e 'You can use the arrow keys too, if you want to navigate.'
+    br
+    e 'For instance, alt+left arrow key means "go down one directory
+    level". alt+right arrow key means to (randomly) go up one
+    hierarchy.'
+    br
+    e 'Since as of May 2017, if there is a file called NOTIFICATIONS.md
+    in the directory, we will read its content and display said 
+    content. That will work only if the file is not empty.'
+    br
+    e 'This allows you to give some notifications to your future
+    self, such as if you need to make some changes to files in
+    that directory at a later time - in this case, in case so that
+    you do not forget, simply put such a file into the directory.'
+  }
+  # ========================================================================= #
+  # === Jumper tag Jump tag.
+  # ========================================================================= #
+  header 'Jumper'+sg(:bike, 'marl1em')
+  p {
+    e 'Via jumpers you can quickly change to another directory.',
+      id: 'jumpers'
+    br
+    s2 'Expressed in another way, jumpers are "'
+    s2 'Bookmarks for Terminals','dodgerblue ud'
+    e '".'
+    br
+    e 'On startup we will load the variouos yaml files that constitute
+    our configuration, which should also include all of our
+    default jumpers, in other words making our jumpers "persistent".'
+    br
+    e 'You can add or remove entries to this list of jumpers easily,
+    as the following example will show - <i>how to add this directory
+    as a jumper-directory</i>:'
+    br
+    cmd '  jumper # will set a jumper to the current directory'
+    br
+    e 'Lateron, you can jump to this directory.'
+    br
+    e 'To see the list of available jumper positions, do this:'
+    br
+    cmd '  jumpers?'
+    br
+    e 'To jumper specifically to one of them, you can give a number, as in:'
+    br
+    cmd '  jumpto 3'
+    br
+    e 'Also note that you can use an alternate syntax as well, via cd:'
+    br
+    cmd '  cd ~3'
+    br
+    e 'or like this:'
+    br
+    cmd '  wd3'
+    br
+    anm 'This will be treated as "jump to position 3".'
+    e 'It is thus a shorter way to jump to a specific directory,
+    and "wd" will be treated as alias.'
+    br
+    cmd 'wd1'
+    br
+    e 'Would mean "jump to first jumper directory", wd2 would mean
+    "jump to second jumper directory", and so forth.'
+    br
+    e 'Note that you can <b>remove</b> a jumper again
+    like so:'
+    br
+    cmd '  remove jumper 6'
+    cmd '  remove_jumper 6'
+    cmd '  rmjumper 6'
+    br
+    e 'This would remove the jumper at position 6.'
+    br
+    anm 'I prefer the second variant, <b class="'+CMD_COLOUR+'">remove_jumper</b>.
+    It seems to be a useful mnemonic. You can omit the _ of course, so
+    you can use <b>removejumper</b> instead.'
+    br
+    e 'You can also integrate different jumpers at run-time. Every file
+    called <span class="file">jumpers.yml</span> will be treated as a
+    jumper directory.'
+    br
+    e 'You can add new directories with a jumper.yml file to the configuration
+    file. If anyone wants to extend this further, let me know - personally
+    I am quite happy with how it currently behaves. I do not use
+    jumper-directories that much myself, since I have regular aliases
+    that allow me to quickly change between directories.'
+  }
+  # ========================================================================= #
+  # extract tag
+  # ========================================================================= #
+  header 'Extracting'+sg(:staff,'marl1em','drag_staff')
+  p {
+    e 'To extract something, you simply do:'
+    br
+    cmd '  extract *tar.bz2'
+    br
+    e 'This should work with <b class="orange">.lzma</b> Files as well.'
+    br
+    e 'Additionally you can specify a location, i.e.:'
+    br
+    cmd '  extract gcc-4.3.1.tar.bz2 /tmp'
+    cmd '  extract gcc-4.3.1.tar.bz2 to /tmp'
+    cmd '  extract 1 to $MY_TEMP'
+    br
+    e 'Both instructions will work and extract the content of 
+    the tarball to the specified directory.'
+    br
+    e 'To extract the audio from a Flash .flv file, do this:'
+    br
+    cmd '  eaud # or extract_audio'
+    br
+    e 'You can also extract all files matching a certain criteria,
+    by doing something like this here:'
+    br
+    cmd '  extract all *bz2'
+    br
+    e 'You can also extract all archives given in a directory.'
+    br
+    e 'For example:'
+    br
+    cmd '  extract all archives'
+    br
+    e 'would extract all .tar.bz2 .zip .gz and so forth...'
+    br
+    anm 'Please note that there is a configuration option that
+    will allow you to automatically enter such an extracted
+    directory. <br>This configuration option is called
+    <b class="orange">enter_extracted_directory</b>. Set it 
+    o true if you want to automatically enter an extracted
+    tarball.'
+    br
+    e 'You can use this from the commandline as well, without
+    properly starting the Diamond Shell.'
+    e 'Example:'
+    br
+    cmd '  rda extract all dontstartup'
+    br
+    e 'This would extract all archives in the current directory.'
+  }
+  # ========================================================================= #
+  # record tag
+  # ========================================================================= #
+  header 'Record'+sg(:sync,'marl1em')
+  p {
+    e 'You can record stuff with the Diamond Shell. Right now this is limited 
+    to <i>streamtuner</i> (Audio Streams from the internet), i.e. do this:'
+    br
+    cmd '  record streamripper'
+    br
+    anm 'You may have to install/compile streamripper first.'
+  }
+  # ========================================================================= #
+  # === require tag
+  # ========================================================================= #
+  header 'Require'+sg(:sync,'marl1em')
+  p {
+    e 'You can require something in the Diamond Shell via:'
+    br
+    cmd '  require "sinatra"'
+    cmd "  require 'thor'"
+    br
+    e 'If it works, we will be silent. If it fails, we will report
+    that error.'
+    br
+    e 'This allows you to use the Diamond Shell a little bit like IRB.'
+    br
+    e 'You can also permanently add new requires to the DiamondShell.'
+    br
+    e 'From within the diamond shell itself, you can use any of
+    the following commands:'
+    br
+    cmd '  add_require NAME_OF_GEM'
+    cmd '  add_require roebe'
+    cmd '  addrequire  foo'
+    cmd '  addreq      foo'
+    br
+    e 'This would add the gem require to the file called '+
+      DiamondShell::FILE_ADDITIONAL_REQUIRE_FILES
+  }
+  # ========================================================================= #
+  # === Glob tag.
+  # ========================================================================= #
+  header 'Glob'
+  p {
+    e 'In the event that we do not find a certain input, we will
+    try a glob event.'
+    br
+    e 'First, we try with trailing * but if that fails we will also
+    try with leading *.'
+  }
+  # ========================================================================= #
+  # === Dictionary tag                                              (dic tag)
+  # ========================================================================= #
+  header 'Dictionary'
+  p {
+    e 'A dictionary allows you to translate words from one language to
+    another.'
+    br
+    e 'If you have a dictionary file in the YAML format, you can enable
+    autocompletion-support for them.'
+    br
+    e 'That is, you can autocomplete via the TAB key on the words.'
+    br
+    e 'In order for this to work, the <b>use_dictionary.yml</b> file must
+    have set a value of true.'
+    br
+    e 'This can be done in a running instance of Diamond Shell like this:'
+    br
+    cmd '  enable dictionary'
+    br
+    anm 'This can be disabled, e. g. via:'
+    br
+    cmd '  disable askeng'
+  }
+  # ========================================================================= #
+  # Autocompletion tag. Completion tag. Tab completion tag.
+  # ========================================================================= #
+  header 'Autocompletion' # rf diatut autocompletion
+  p {
+    e 'Autocompletion means that if you press the TAB key, you will be 
+    able to choose from a selection.'
+    br
+    e 'Before explaining this further, try it. Start your diamond shell
+    and do this:'
+    br
+    cmd '  extract|TAB|'
+    br
+    anm 'The <b class="'+CMD_COLOUR+'">|TAB|</b> notation here means
+    "<b>press the tab key here</b>". So first you write extract,
+    and then you press the tab key.'
+    br
+    e 'You will get a selection between <b>extract_audio</b> and
+    <b>extract_video</b> and possibly <b>extract_it</b> as well.'
+    br
+    e 'Press v and then TAB again. You will have selected video.'
+    br
+    e 'The file that handles autocompletion is readline.rb, which you can 
+    find in the base/ subdirectory.'
+    br
+    e 'Note note that we allow you to autocomplete to the list of
+    available instance variables.'
+    br
+    e 'For instance:'
+    br
+    cmd '  @al<TAB>'
+    br
+    e 'Would list which instance variables with a name starting with
+    @al exist.'
+    br
+    e 'Additionally, all entries found in $PATH will also be completed.'
+    br
+    e 'As of August 2014, we will also add support for some completions
+    of the Ruby stdlib.'
+    br
+    e 'Since as of September 2015, we will also tab-complete on leading
+    <b>@configuration.</b> entries. This way you can cycler through
+    the available configuration options more quickly.'
+    br
+    e 'Image screenshot for these options:'
+    img 'PC/DIAMOND_SHELL/DIAMOND_SHELL_TAB_COMPLETE_OF_CONFIGURATION.png',
+        'marl3em mart1em', :drag
+  }
+  # ========================================================================= #
+  # === Edit tag, Editor Tag.
+  # ========================================================================= #
+  header 'Editing'+sg(:present,'marl1em')
+  p {
+    e 'To find out which editor is your current main editor, do this:'
+    br
+    cmd '  editor?'
+    br
+    e 'You can switch to another editor by doing this:'
+    br
+    cmd '  seted bluefish'
+    br
+    e 'This setting is persistent, and will be stored in the file
+    <b class="orange">editor.yml</b>.'
+    br
+    e 'Also note that since September 2011, if you try to open a
+    directory, we will now open the content of the directory. (Before 
+    September 2011, we used to display an <i>error message</i> instead.)'
+    br
+    e 'You can also open based on the class name, if the file can be found.'
+    br
+    e 'For instance:'
+    br
+    cmd '  bl BirthdayNotifications:'
+    cmd '  bl BirthdayNotifications'
+    br
+    e 'The above will try to find a file called birthday_notifications.rb.'
+    e 'If it can be found then we will open it in the editor.'
+    br
+    e 'Note that as of 31.07.2015 you can also open a file based on the
+    name of a method defined, if this method is part of the Diamond Shell
+    Project.'
+    br
+    e 'Example:'
+    br
+    cmd 'bl show_completable_commands'
+    br
+    e 'This would open the file show.rb because the above method is
+    defined in that file.'
+    br
+    e 'Some editors, such as vim, allow you to jump to a specific line
+    position, such as by doing <b>vim foo.txt +55</b>. We attempt to
+    somewhat simulate this behaviour, in the event that you supply
+    a ":" character, and numbers after that.'
+    br
+    e 'For instance:'
+    br
+    cmd '  edit foobar.rb:55'
+    br
+    e 'We would assume this to mean "edit the file foobar.rb", and
+    "jump to position 55". Currently this works only via vim though.'
+    br
+    anm 'You can also use the traditional vim syntax directly:'
+    br
+    cmd '  vim $DIA/configuration/configuration.rb +371'
+    br
+    e 'Do note that we will also expand aliases. So if you try to open
+    an alias in your editor, we will expand towards the real file
+    that is used.'
+  }
+  # ========================================================================= #
+  # Path tag.
+  # ========================================================================= #
+  header 'Path'+sg(:gitarre, 'marl1em')
+  p(id:'path') {
+    e 'The Diamond shell will use the <span class="yel">$PATH environment</span>
+    variable, if it was set.'
+    br
+    e 'All binaries known there will be used for both the completion, and as
+    known-executables. This is similar to how other shells handle the
+    $PATH variable.'
+  }
+  # ========================================================================= #
+  # Audio tag Song tag. Aud tag.
+  # ========================================================================= #
+  header 'Audio'+sg(:gitarre, 'marl1em')
+  p('','cut') {
+    e 'The Diamond Shell simplifies dealing with audio data in quite some ways.
+    Please read this section carefully if you wish to manipulate audio
+    data with the Diamond Shell in any way.'
+    br
+    e 'You can remove a comment in an OGG File (<b>.ogg</b>) by issuing
+    this:'
+    br
+    cmd '  remove_comment your_ogg_file.ogg'
+    br
+    e 'If you want to play several songs and use a range 
+    specification, do this:'
+    br
+    cmd '  77-99'
+    br
+    e 'This would then play the songs from position 77 to position
+    99 in the current directory.'
+    br
+    e 'Also note that since Sep 2011 you can issue the following 
+    command, and we will play the song found in <span class="directory">
+    /Depot/Audio</span>'
+    br
+    cmd '  play song 33'
+    br
+    e 'Also note that when you play audio files, this is stored in 
+    an array.'
+    e 'To find out the last song played, do this:'
+    br
+    cmd '  last_song?'
+    br
+    e 'Since Nov 2011 we will try to glob whenever we try to play a
+    multimedia file.'
+    br # Audio conversions come next.
+    e 'You can convert Audio Formats to one another. For instance,
+    to convert a .mp3 file to a .wav file, you can do this:'
+    br
+    cmd '  assign foo.mp3'
+    cmd '  convert_to wav # Convert to .wav format.'
+    br # Slicing comes next.
+    e 'You can use the Diamond Shell to elegantly
+    <i class="gold">slice .mp3</i> files.'
+    br
+    e 'Currently we rely on <i class="lightblue">ffmpeg</i> to
+    do these conversions. Now, how can you <b>slice</b> a .mp3
+    file with the DiaShell?'
+    br
+    e 'Say you have a mp3 file, and <b>file?</b> also reports
+    this.'
+    br
+    e 'Specific Example - we first assign a .mp3 file as the main
+    file to work with:'
+    br
+    cmd '  assign Strack_MI1Theme_U2.mp3'
+    cmd '  file? # => "Strack_MI1Theme_U2.mp3"'
+    br
+    e 'Now you can then specify the start position:'
+    br
+    cmd '  cut_start 15'
+    br
+    e 'And then the end position'
+    br
+    cmd '  cut_end 45'
+    br
+    e 'in Seconds.'
+    br
+    e 'To start the actual cutting,'+sg(:knife,'mar4px', :drag)+' do:'
+    br
+    cmd '  cut'
+    br
+    anm 'To feedback the positions, do:'
+    cmd '  cut?'
+    br
+    anm 'This makes use of class CutAudio, which you may be
+    able to use standalone (thus, without the DiamondShell
+    as well).'
+    br
+    e 'You can also play all audio files in a given directory.'
+    br
+    e 'In order to do this, try this here:'
+    br
+    cmd '  play all audio'
+    br
+    anm 'This is almost the same as play * except that we
+    will know which files are audio files and which ones
+    are not.'
+    br
+    e 'You can also add or remove entries to the favourite audio file
+    listing.'
+    br
+    e 'To do this, do:'
+    br
+    cmd '  add_fav foo.mp3'
+    cmd '  rem_fav foo.mp3'
+    br
+    e 'To show your favourite audios, do:'
+    br
+    cmd '  show favourite audio'
+    cmd '  show_favourite_audio'
+    br
+    anm 'Either of these two will work fine.'
+  }
+  # ========================================================================= #
+  # Conversions tag
+  # ========================================================================= #
+  header 'Conversions'
+  p {
+    e 'You can use the DiamondShell to convert certain formats
+    into other formats. For instance, .mp3 into .ogg, but also
+    to "convert" or rather calculate Celsius into Fahrenheit,
+    and so forth.'
+    br
+    e 'The following subsection here shows how this is done.'
+    br
+    e 'To convert <b>55 celsius</b> to fahrenheit, do this:'
+    br
+    cmd '  convert 55 celsius'
+    br
+    e 'You can also output a list of Celsius to fahrenheit
+    table (convert into a table):'
+    br
+    cmd '  convert 10-100 celsius'
+    br
+    e 'If you want to convert audio tracks '+sg(:noten)+', just use this:'
+    br
+    cmd 'convert *mp3 towav'
+    br
+    e 'This would convert all mp3 files to .wav files.'
+    anm 'to_wav would also work.'
+    br
+    e 'To compare mp3 into ogg, do:'
+    br
+    cmd 'convert *mp3 toogg'
+    br
+    e 'Please also note that the DiaShell can try to automatically
+    convert numbers to file names or directory names.'
+    br
+    e 'This setting can be changed in the config file at:'
+    br
+    marl1em '  autoconvert_numbers: true/false','BO'
+  }
+  # ========================================================================= #
+  # === Variables explained.
+  # ========================================================================= #
+  header 'Variables explained'
+  p {
+    table2('mars1em','','',
+      '<b>@_</b>','The variable <span class="yel">@_</span> is a throwaway 
+      variable. It can be used for pretty much any data. I often tend
+      to assign all files in a directory to this variable.'
+    )
+  }
+  # ========================================================================= #
+  # === Assign tag
+  # ========================================================================= #
+  header 'Assignments in the DiaShell'
+  p {
+    e 'The DiaShell allows you to assign to a main file.'
+    br
+    e 'In order to do so, you can assign to the main file like this:'
+    br
+    cmd '  asssign foo.txt'
+    br
+    e 'Now, in several command actions, like copying, you can
+    omit typing the name.'
+    br
+    cmd '  copy to here'
+    br
+    e 'The above command would copy the main file to the current
+    location, aka Dir.pwd (current working directory).'
+    br
+    anm 'We will do this automatically for at the very
+    least these actions:'
+    br
+    cmd '  copy a file'
+    cmd '  create a new file'
+    cmd '  when we play an audio file'
+    cmd '  when we open a file in an editor'
+    cmd '  whenever we stat a file'
+    cmd '  whenever we match to a local URL'
+    cmd '  whenever we open a file in the browser'
+    cmd '  whenever we append to a file'
+    cmd '  whenever we use jp2a'
+    cmd '  whenever we play a video file'
+    cmd '  whenever we trigger an action'
+    cmd '  whenever we create an iso'
+    cmd '  whenever we read a file'
+  }
+  # ========================================================================= #
+  # === Collapse tag
+  #
+  # rf diatut collapse
+  # ========================================================================= #
+  header 'Collapse'
+  p {
+    e 'This means to display the full path to a given file or 
+    directory.'
+    br
+    e 'If collapse is <b>true</b>, then we will <b class="crimson">NOT</b>
+    display the full path to a given file or directory.'
+    br
+    e 'You can change this behaviour just as any of the other
+    configuration values.'
+    br
+    e 'One way would be this:'
+    br
+    cmd '  disable collapse'
+  }
+  # ========================================================================= #
+  # === Video tag. play tag.
+  # ========================================================================= #
+  header 'Video'
+  p {
+    e 'You can play Videos or songs, like so:'
+    br
+    cmd '  tosongs; mpl 3-5,33'
+    br
+    e 'The above would enter the song directory - tosongs
+    is my alias - and then mplayer (mpl is an alias for mplayer)
+    would try to play file 3, 4, 5, and also file 33.'
+    br
+    e 'The ; is a separator in this context. You can chain
+    command instructions separated by ; that way.'
+    br
+    e 'Note that you can search on IMDB via the shell too:'
+    br
+    cmd 'imdb dou fo sin # this would search for the movie
+    called "dou fo sin".'
+    br
+    anm 'Note that if you invoke "play" without any arguments, if we 
+    had assigned a file prior to this, we will play this file.'
+    br
+    e 'You can also play a video file based on the number or the 
+    name of the file in question, if you have registered it in a 
+    yaml file prior to that.'
+    br
+    e 'Examples:'
+    br
+    video '125'
+    video 'taxi driver'
+    br
+    e 'And you can also try to find a random video.'
+    br 
+    cmd 'video random'
+    br
+    e 'You can also use numbers, such as via:'
+    br
+    cmd '  play 1,3,4'
+    br
+    e 'This would play the files at position 1, 4 and 4.'
+  }
+  # ========================================================================= #
+  # === random tag
+  # ========================================================================= #
+  header 'random' # rf diatut random
+  p {
+    e 'Random allows you to do some random stuff.'
+    br
+    e 'You can play a random video by doing:'
+    br
+    cmd '  random video'
+  }
+  # ========================================================================= #
+  # === line tag
+  # ========================================================================= #
+  header 'line'
+  p {
+    e 'You can show a specific line in any file by doing this:'
+    br
+    cmd '  line 55 foobar.rb'
+    br
+    e 'Do note that the file in question has to exist.'
+    br
+    e 'The first argument here is the line position, e. g. 55
+    would mean "line number 55".'
+  }
+  # ========================================================================= #
+  # === Install tag
+  # ========================================================================= #
+  header 'Installation'+sg(:hang_man)
+  p {
+    e 'In the future this section is supposed to allow you to install
+    a <b>Linux distribution</b>. For now though, we will focus on
+    installing several packages in one go, i.e. compiling them.'
+    br
+    e 'To do this, try this command:'
+    br
+    cmd '  install default'
+    br
+    lem 'This will compile all programs which are listed in
+    the file:'
+    br
+    lem3 '/Users/x/DATA/PC/OS/LINUX/YAML/installation_procedere.yml',
+         'BO crimson FI'
+    br
+    e 'The file that will be used is 
+    <i class="crimson BO">$RUBY_SYS/profile_install.rb</i>.'
+    br
+    anm 'You may have to use your own installation_procedere.yml
+    file. I will make it available for RBT.'
+  }
+  # ========================================================================= #
+  # === Run tag
+  # ========================================================================= #
+  header 'Run'
+  p {
+    e 'You can "run" a file, and we attempt to run this file with the 
+    default application that was registered.'
+    br
+    e 'For example, if you do:'
+    br
+    cmd 'run foo.pdf'
+    br
+    e 'Then we would open this file.'
+    br
+    anm 'This is a bit similar to the command open, but run specifically
+    also works when we have files like .rb files, .py files and so on.<br>
+    It is a bit like an <span class="BG_Black pad1px pads4px orange">
+    instruction to <b>execute that file</b></span>.', :error_box
+    br
+    e 'Since as of September 2016 you can also use a require-statement
+    to start up a new instance of the Diamondshell.'
+    br
+    e 'Do the following:'
+    br
+    cmd "  require 'diamond_shell/run'"
+  }
+  # ========================================================================= #
+  # === Stat tag.
+  # ========================================================================= #
+  header 'Stat'
+  p {
+    e 'Stat is used similar to the <b>UNIX command stat</b>.'
+    br
+    cmd 'stat some_file'
+    br
+    e 'Additionally, we include information from <b>class BeautifulUrl</b>
+    so whatever you did add to that class will work with the stat command
+    too, no matter where that file is.'
+    br
+    e 'You can also apply stat on the @_ token, like:'
+    br
+    cmd '  stat @_'
+    br
+    e 'Additionally, you can do this:'
+    br
+    cmd '  stat {1,2}'
+    cmd '  stat 1,2'
+    br
+    e 'The above commands would stat the position 1 and 2.'
+    br
+    anm 'Note that leading file: entries will be removed from the
+    given input.'
+  } 
+  # ========================================================================= #
+  # === PDFS tag PDF tag. Manual tag.
+  # ========================================================================= #
+  div {
+    header 'PDFs'+sg(:pdf,'marl1em', 'drag_pdf'); highlight :drag_pdf
+    br
+    e 'If you want to find all PDFs, do this:'
+    br
+    cmd'  find all pdf'
+    br
+    e 'There is also a configuration option called 
+    <b>@open_downloaded_pdf_files_at_once</b>.'
+    br
+    e 'If this configuration option is true, then we will open PDF
+    files the moment we downloaded them.'
+    br
+    anm 'You can also generate a new Manual for the DiamondShell
+    by issuing:'
+    br
+    cmd '  manual'
+    cmd '  create manual'
+    br
+    e 'This will create a .pdf file.'
+    br
+    e 'Also note that you can, thanks to prawn, create a .pdf file out
+    of a .txt file (any text file). We support this in the Diamond
+    Shell as well.'
+    br
+    e 'To do this, issue:'
+    br
+    cmd '  to_pdf foo.txt'
+    br
+    anm 'Here we assume that foo.txt exists and can be used to create
+    a foo.pdf file.'
+  }
+  # ========================================================================= #
+  # === Available Components
+  # ========================================================================= #
+  div {
+    header 'Available components'
+    e 'Sometimes you may want to find out whether all add-ons are
+    available.'
+    br
+    e 'You can use the following commands to find out whether
+    something is missing or not:'
+    br
+    cmd '  missing?'
+    cmd '  available_components?'
+  }
+  # ========================================================================= #
+  # === Find tag
+  # ========================================================================= #
+  div {
+    header 'Find - finding something'+sg(:huhn, 'marl1em')
+    br
+    e 'We can find something in the DiaShell, by doing something
+    like:'
+    br
+    cmd '  dfind threads.rb'
+    br
+    e 'This will find threads.rb on your HDD and also set it to the
+    @last_file used, which you can query via <b>file?</b>.'
+    br
+    e 'You can also find where binaries may be, similar to the UNIX
+    where_is.'
+    br
+    e 'Do either of the following, in order to find the binary
+    called <b>tar</b>:'
+    br
+    cmd '   where is tar?'
+    cmd '   where is tar'
+    cmd '   where? tar'
+  }
+  # ========================================================================= #
+  # === Repeat last action. (repeat tag)
+  # ========================================================================= #
+  div {
+    header 'Repeat last action'
+    e 'You can repeat the last action by doing:'
+    br
+    cmd'  ~'
+    cmd'  +'
+    cmd'  -'
+    cmd'  ++'
+    cmd'  --'
+    br
+    e 'Positional modifiers work too, to some extent. +30 would mean "play
+    the song at position +30 in relative terms to the last song played".'
+  }
+  # ========================================================================= #
+  # === DiamondShell Parameters Tag.
+  # ========================================================================= #
+  div {
+    header 'DiamondShell Parameters'
+    br
+    e 'You can get all the parameters of the methods in the DiamondShell.'
+    br
+    e 'In order to do this, do the following command from within a 
+    running instance of DiamondShell:'
+    br
+    cmd '  parameters?'
+    br
+    e 'Here is a <b>partial screenshot</b> showing the output of that
+    command:'
+    br
+    img 'PC/DIAMOND_SHELL/DIAMOND_SHELL_PARAMETERS.png',
+        'marl6em', :drag # The Parameters.
+  }
+  # ========================================================================= #
+  # === Home directory
+  # ========================================================================= #
+  div {
+    header 'The Diamond Shell Home Directory'
+    e 'You can designate a new home directory for the Diamond Shell.'
+    br
+    e 'In other words, this will be the new directory where we will
+    save files to, and so on.'
+    br
+    e 'The syntax to designate a new home directory, as can be seen
+    if you use --help from the commandline, is:'
+    br
+    cmd '  dia --home-dir=/opt' 
+  }
+  # ========================================================================= #
+  # === DiaShell on windows.  Win tag, Windows Tag.
+  # ========================================================================= #
+  div {
+    header 'Diamond Shell on Windows'
+    br
+    e 'The Diamond Shell works on Windows too, but some problems may exist
+    there, as Windows is not the main OS for the Diamond Shell to be tested.'
+    br
+    e 'First, to check whether you are running on windows or not,
+    run this check:'
+    br
+    cmd '  if OPERATING_SYSTEM == :windows'
+    br
+    e 'The DiaShell should of course also work on <b>Windows</b>. For
+    this to work, some convenience methods were added.'
+    br
+    cmd '  dcomcnfg'
+    br
+    e 'Also try out this:'
+    br
+    cmd '  config windows'
+    br
+    e 'This should enable some windows-specific configuration settings.'
+    br
+    e 'But note that this has not been very thoroughly tested.'
+  }
+  # ========================================================================= #
+  # === Config tag. Configuration tag.
+  #
+  # Important Configuration Files for the Diamond Shell.
+  #
+  # Will also have a subsection about diamondrc.
+  # ========================================================================= #
+  div(id: 'config') {
+    header 'Configuration'
+    br
+    le 'Important Configuration Files for the DiamondShell and how to
+    handle them.'
+    br
+    s2 'default_applications.yml','BO orange'
+    e sg(:pfeil8)+'This file will include your favourite applications 
+    for specific file types.'
+    br
+    e 'In here you can specify which program to use whenever you
+    want to open a .pdf file, open a .png file and so on.'
+    br
+    cmd '  bl $RUBY_DIA/lib/diamond_shell/YAML/default_applications.yml'
+    br
+    e 'To show the current values set in that file, you can do this:'
+    br
+    cmd 'default_applications?'
+    br
+    e 'Note that you can reload the yaml config by doing:'
+    br
+    cmd '  reload configuration'
+    br
+    e 'This will also reload the aliases at run-time.'
+    br
+    e 'Another configuration option allows you to display shorter 
+    file names, i.e. if a file name is too long we will simply 
+    truncate it.' # truncate tag.
+    br
+    e 'Every available configuration option can be found in the
+    <b>main configuration directory</b>.'
+    br
+    cmd '  cd $RUBY_DIA/lib/diamond_shell/yaml/configuration'
+    br
+    e 'For local use I recommend you to only use the saving option.
+    The following example illustrates this:'
+    br
+    cmd '  config.debug = true'
+    br
+    e 'This changes the configuration of the shell during runtime.'
+    br
+    e 'To make this change permanent, do this:'
+    br
+    cmd '  save'
+    br
+    e 'or'
+    br
+    cmd '  save config'
+    br
+    e 'Now, on next startup, we will load this saved config file.'
+    br
+    e 'You can also save individual components. For instance,
+    you can save the debug value, or the padding value.'
+    br
+    cmd '  save debug'
+    cmd '  save padding'
+    br
+    anm 'But this is no longer that useful. Since March 2014, I
+    recommend you to simply to just "save" alone.'
+    br
+    e 'If you have set shorten_directory_names to true, then a 
+    leading * will indicate that the name was shortened.'
+    br
+    e 'You can toggle this at run-time too, and untoggle again,
+    as in:'
+    br
+    cmd 'shorten'
+    cmd 'unshorten # or "longen"'
+    br
+    anm 'Note that <b>shorten</b> will also get rid of the ModTime
+    information.'
+    br
+    anm 'You can also deliberately disable the display of the
+    modification time. In order to do so, do:'
+    br
+    cmd 'no_mod_time'
+    br
+    e 'And to undo, do:'
+    br
+    cmd 'show_mod_time'
+    br
+    e 'You can modify every configuration option directly like so:'
+    br
+    cmd '  config.use_colours = false'
+    br
+    e 'To feedback this option, do this:'
+    br
+    cmd '  config.use_colours'
+    br
+    e 'You can also append a <b>?</b> if you want to:'
+    br
+    cmd '  config.use_colours?'
+    br
+    e 'Rather than use <b>config.</b>, some aliases exist, such as
+    @configuration, @config and so on. Use whatever suits you best,
+    although <b>config.</b> is probably the shortest and simplest
+    notation for accessing the DiaShell Configuration Settings.'
+    br
+    e 'Of course, if you want to disable the colours, you could
+    also use this:'
+    br
+    cmd '  disable colours'
+    br
+    e 'You can reload your original configuration by issuing this:'
+    br
+    cmd '  reload config'
+    br
+    e 'This will also reload the colours, so you can use it to
+    change the currently running shell.'
+    br
+    e 'The option <b>run_simulation</b> is used to run in a 
+    simulation mode - currently this means that we do not
+    actually burn a CD or DVD, no. It means we will feedback
+    which command we would use.'
+    br
+    e 'Also note that when you are on windows, you could do 
+    something like:'
+    br
+    cmd '  config windows'
+    br
+    e 'To conveniently switch to a windows-based configuration.'
+    br
+    e 'If you look at the configuration, it is a simple key => value
+    mapping, a hash. You can modify values of this hash in a fairly
+    simple manner:'
+    br
+    cmd '  editor = bluefish'
+    br
+    e 'This would set your editor to bluefish.'
+    br
+    e 'You can change specific parts of the config by using aliases.
+    For instance, this will work to change the location of Firefox:'
+    br
+    cmd '  firefox.location = /Programs/Firefox/Current/bin','browser'
+    br
+    e 'Another option is to simply use this instead:'
+    br
+    cmd '  set_browser /Programs/Firefox/Current/bin'
+    cmd '  set_firefox /Programs/Firefox/Current/bin'
+    br
+    e 'Since <i>March 2012</i> we are using a specialized class called
+    <b class="orange">Configuration</b> to handle all configuration
+    aspects of the Diamond Shell.'
+    br
+    e 'You can also query the config directly by issuing a command
+    query such as the following:'
+    br
+    cmd '  config.padding?'
+    cmd '  config.use_irc?'
+    br
+    e 'An alternative syntax also exists such as:'
+    br
+    cmd '  Diamond.configuration.padding = 5'
+    br
+    e 'You can designate another Encoding format to use via the
+    configuration option preferred_encoding.'
+    br
+    e 'Additionally, you can overrule the encoding via the
+    method <b>DiamondShell.set_encoding()</b>. For instance,
+    to designate to the binary encoding, use this:'
+    br
+    cmd '  DiamondShell.set_encoding :binary'
+    br
+    e 'I tend to use an ISO encoding, you may use UTF there
+    instead.'
+    br
+    e 'This encoding format will be used several times during
+    a DiamondShell session so make sure to have it properly
+    set.'
+    br
+    # ======================================================================= #
+    # === diamondrc file
+    #
+    # rf diatut diamondrc
+    # ======================================================================= #
+    lem 'If a file called <b id="diamondrc">diamondrc</b> exists in the base
+    directory of the DiamondShell home directory, then we will try to
+    <b>parse it</b> and use its values. For instance, if you set
+    "colours: false" in this diamondrc file, then we will not make
+    use of colours. (You can also use US spelling such as "colors: false")'
+    br
+    lem 'This is similar to using the yaml files to control the
+    behaviour or other instructions such as "disable colours"
+    at runtime. More about this in the <b>disable-subsection</b>.'
+    br
+    e 'The class responsible for the parsing is stored here:'
+    br
+    cmd '  $DIA/diamondrc_parser/diamondrc_parser.rb'
+    br
+    e 'You can dump the configuration options by issuing:'
+    br
+    cmd '  dump_config'
+  }
+  # ========================================================================= #
+  # === Debug tag
+  #
+  # Enable or disable debug.
+  # ========================================================================= #
+  div(id: 'debug') {
+    h2 'Debugging'
+    e 'You can enable or disable debugging.'
+    br
+    e 'The command may be:'
+    br
+    cmd '  debug+'
+    br
+    e 'To enable debugging.'
+    br
+    cmd '  debug-'
+    br
+    e 'To disable debugging.'
+    br
+    e 'You can also use the longer variants such as enable_debugging or
+    enable debugging. And of course also disable debuggung - see the
+    other entries for <b>enable</b> and <b>disable</b> functionality.'
+  }
+  # ========================================================================= #
+  # === Conventions for the Diamond Shell
+  # ========================================================================= #
+  div {
+    h2 'Conventions for the Diamond Shell','mart1px slategray',
+       'conventions' # Conventions tag.
+    p('s0_5em'){
+      e '- All * are meant to be a shortcut for "all files". Or
+      more precisely, all files, directories and symlinks.'
+      br
+      e '- @this_file and @_. Not sure about the differences.
+      I think @this_file is used to denote the main file right
+      now, whereas @_ is more like a <b>throwaway variable</b>.'
+    }
+  }
+}
+
+div('pad1em','','border: 1px inset aquamarine;') {
+  h1 sg(:monkey)+'External Links','gold mart0_1em'
+  p {
+    PFEIL = sg(:pfeil2,'marr6px')
+    abr 'c',content: PFEIL+'C Programming Language',css_class: 'slateblue'
+    abr 'rbt',content: PFEIL+'Ruby Build Tools',css_class: 'slateblue'
+    abr 'master_pipe',content: PFEIL+'Master Pipe',css_class: 'slateblue'
+  }
+}
+
+div('posab smaller','','right:0.1em;top:0.1em') {
+  h2 'Sitemap','yel FI'
+  ARRAY_HEADER_IDS.sort.each { |id|
+    abr '#'+id,
+        content: sg(:pfeil1,'smaller marr4px')+id.capitalize,
+        css_class: 'smaller slateblue FI'
+  }
+}}