Initial attempt at user documentation

README

@@ -3,15 +3,16 @@ Midori is a lightweight web browser.
 * Full integration with GTK+2.
 * Fast rendering with WebKit.
 * Tabs, windows and session management.
-* Bookmarks with XBEL and keyword support.
+* Flexibly configurable Web Search.
-* Flexibly configurable Web Searchbox.
-* Custom context menu actions.
 * User scripts and user styles support.
+* Straightforward bookmark management.
+* Customizable and extensible interface.
 * Extensible via Javascript.
+* Custom context menu actions.
 
 Requirements: GTK+ 2.6, WebkitGtk, libXML2
 
-Optional: Glib 2.16, GtkSourceView 2.0
+Optional: Glib 2.16, GtkSourceView 2.0, Unique 0.9, xdg-open
 
 For installation instructions read INSTALL.
 

docs/user/midori.css

@@ -0,0 +1,114 @@
+/*
+:Author: Christian Dywan
+:Contact: christian@twotoasts.de
+:Copyright: This stylesheet has been placed in the public domain.
+
+Stylesheet for Midori's documentation based on a version of Enrico Troeger.
+*/
+
+@media screen {
+
+    body {
+        background-color: #f6fff3;
+        color: #404040;
+        margin-left: 0.4em;
+        width: 60em;
+        font-size: 90%;
+    }
+
+    a {
+        color: #013100;
+    }
+
+    a:visited {
+        color: #7E558E;
+    }
+
+    a:hover {
+        text-decoration: none;
+    }
+
+    h1, h2, h3 {
+        font-family: sans-serif;
+        color: #002a00;
+    }
+
+    h1 {
+        border-top: 1px dotted;
+        margin-top: 2em;
+    }
+
+    h1.title {
+        text-align: left }
+
+    h2 {
+        margin-top: 30px;
+    }
+
+    h2.subtitle {
+        text-align: left }
+
+    h3 {
+        padding-left: 3px;
+    }
+
+    blockquote, pre {
+        border: 1px solid;
+        padding: 0.4em;
+    }
+
+    blockquote {
+        font-family: sans-serif;
+        background-color: #DBEDD5;
+        border: 1px dotted;
+        border-left: 4px solid;
+        border-color: #9FD98C;
+    }
+
+    pre {
+        background-color: #deefd4;
+        border: 1px dotted;
+        border-left: 4px solid;
+        border-color: #9acb7d;
+    }
+
+    tt, pre, code {
+        color: #002a00;
+    }
+
+    table {
+        border: 1px solid #9acb7f;
+    }
+
+    th {
+        border: none;
+        background-color: #9acb7d;
+    }
+
+    tr:nth-child(even) {
+        background-color: #d3eac6;
+    }
+
+    td {
+        border: none;
+    }
+
+    .docinfo-name {
+        color: #002a00;
+    }
+
+    p.admonition-title {
+        color: #990000;
+        font-weight: bold;
+    }
+
+    div.note {
+        margin: 1em 3em;
+        padding: 0em;
+    }
+
+    dt {
+        font-style: italic;
+    }
+
+}

docs/user/midori.txt

@@ -0,0 +1,202 @@
+.. |(version)| replace:: 0.0.21
+
+'''''''
+ Midori
+'''''''
+
+-----------------------------------------
+ A lightweight, portable GTK+ web browser
+-----------------------------------------
+
+:Authors: Christian Dywan
+:Date: $Date: 2008-08-03 20:30:35 +0100 (Sat, 28 Sep 2008) $
+:Version: |(version)|
+
+Copyright © 2008
+
+This documentation is distributed under the terms of the
+`GNU Lesser General Public License`_; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+
+.. contents::
+
+
+
+Introduction
+''''''''''''
+
+
+What is Midori
+--------------
+
+Midori is a lightweight and portable web browser based on Gtk+. The
+interface is designed to be intuitive yet powerful.
+
+* Full integration with GTK+2.
+* Fast rendering with WebKit.
+* Tabs, windows and session management.
+* Flexibly configurable Web Search.
+* User scripts and user styles support.
+* Straightforward bookmark management.
+* Customizable and extensible interface.
+* Extensible via Javascript.
+* Custom context menu actions.
+
+
+Running Midori
+--------------
+
+
+* If you are using a graphical desktop environment you will usually find
+  Midori in the menu under Network.
+
+* You can also run Midori from a console or a Run dialog.
+  See also `Command line usage`.
+
+  $ midori
+
+A browser window appears where you can start navigating the web right away.
+
+
+The main interface
+--------------------------
+
+
+The main browser window consists of a few basic elements:
+
+
+* The menubar. It's pretty much standardized and gives you access to
+  allmost all features, many of the items have a keyboard shortcut by default.
+  See also `Keyboard shortcuts`_.
+
+* The navigationbar. It lets you open tabs, go back and forward, enter
+  addresses, search the web and reopen closed tabs.
+  See also `The navigationbar`.
+
+* The sidepanel. It takes a pretty central role in the functionality it provides,
+  yet it can be hidden and resized to not distract you.
+  See also `The sidepanel`.
+
+* The statusbar. It displays informational text when hovering something
+  with a pointer. That's it.
+
+
+Taking a closer look
+''''''''''''''''''''
+
+
+Command line usage
+------------------
+
+
+Running Midori normally works as follows:
+
+
+* $ midori
+
+  Just run a new instance of Midori. If an instance of Midori is already
+  running a new window in that instance will be opened.
+
+* $ midori [URIs]
+
+  You can supply any number of URIs to open as arguments. If you have a
+  saved session or a running instance they will be added to the last
+  active window.
+
+* $ midori [URI1]|[URI2]|...
+
+  You can separate URIS by a pipe (|) as well. They are handled as if you
+  provided all URIs as separate arguments.
+
+* $ midori [JAVASCRIPT]
+
+  If you pass a filename ending with ".js" Midori will attempt to run
+  the contents of the file as javascript code.
+
+
+Note that support for opening tabs in an existing instance depends on
+your build and may not be available on some platforms.
+
+
+The following arguments are supported if you call Midori from a command line.
+
+
++--------------+--------------+------------------------------------------------+
+| Short option | Long option  | Function                                       |
++==============+==============+================================================+
+| -i           | --id         | This is an internal identifier. It is used to  |
+|              |              | spawn child processes for new tabs. Do not use |
+|              |              | it unless you know what you are doing.         |
++--------------+--------------+------------------------------------------------+
+| -v           | --version    |  Show version information and exit.            |
++--------------+--------------+------------------------------------------------+
+
+
+Keyboard shortcuts
+------------------
+
+
+...
+
+
+The navigationbar
+-----------------
+
+
+...
+
+
+
+The sidepanel
+-------------
+
+
+...
+
+
+Frequently asked questions
+''''''''''''''''''''''''''
+
+
+How do you pronounce Midori and what does it mean anyway?
+---------------------------------------------------------
+
+Pronounce it "midoɺi", with a Bavarian/ Japanese "r" or "Mee-Doh-Ree"
+in English or read it Italian. The name comes from the Japanese word
+緑 (みどり) for the colour "green".
+
+
+What does the logo mean?
+------------------------
+
+The paw of a green cat. Obviously. Also it resembles the letter "M"
+in "Midori". The curving is supposed to emphasize speed.
+
+
+On which platforms does Midori run currently?
+---------------------------------------------
+
+Midori is basically very portable and should run on all platforms that
+its dependencies support.
+
+
+
+Under which license is Midori distributed?
+------------------------------------------
+
+Midori, documentation and all delivered artwork are licensed under the LGPL2.
+
+
+GNU Lesser General Public License
+'''''''''''''''''''''''''''''''''
+
+::
+
+    GNU LESSER GENERAL PUBLIC LICENSE
+    Version 2.1, February 1999
+
+    FIXME: Provide full license text
+

wscript

@@ -5,6 +5,7 @@ import Params
 import pproc as subprocess
 import Common
 import platform
+import os
 
 APPNAME = 'midori'
 VERSION = '0.0.21'
@@ -23,6 +24,19 @@ blddir = '_build_'
 def configure (conf):
     conf.check_tool ('compiler_cc')
 
+    if not Params.g_options.disable_docs:
+        conf.find_program ('rst2html.py', var='RST2HTML')
+        # debian renames the executable, check that as well :(
+        if not conf.env['RST2HTML']:
+            conf.find_program ('rst2html', var='RST2HTML')
+        if conf.env['RST2HTML']:
+            docs = 'yes'
+        else:
+            docs = 'not available'
+    else:
+        docs = 'no'
+    conf.check_message_custom ('generate', 'user documentation', docs)
+
     if not Params.g_options.disable_nls:
         conf.check_tool ('intltool')
         if conf.env['INTLTOOL'] and conf.env['POCOM']:
@@ -45,6 +59,20 @@ def configure (conf):
         update_po = 'no'
     conf.check_message_custom ('localization file', 'updates', update_po)
 
+    # We support building without intltool
+    # Therefore datadir may not have been defined
+    if not conf.is_defined ('DATADIR'):
+        if Params.g_options.datadir != '':
+            conf.define ('DATADIR', Params.g_options.datadir)
+        else:
+            conf.define ('DATADIR', os.path.join (conf.env['PREFIX'], 'share'))
+
+    if Params.g_options.docdir == '':
+        docdir =  "%s/doc" % conf.env['DATADIR']
+    else:
+        docdir = Params.g_options.docdir
+    conf.define ('DOCDIR', docdir)
+
     if Params.g_options.enable_api_docs:
         conf.find_program ('gtkdoc-scan', var='GTKDOC_SCAN')
         conf.find_program ('gtkdoc-mktmpl', var='GTKDOC_MKTMPL')
@@ -104,6 +132,10 @@ def configure (conf):
 def set_options (opt):
     opt.tool_options ('compiler_cc')
     opt.tool_options ('intltool')
+    opt.add_option ('--docdir', type='string', default='',
+        help='documentation root', dest='docdir')
+    opt.add_option ('--disable-docs', action='store_true', default=False,
+        help='Disables user documentation', dest='disable_docs')
 
     opt.add_option ('--disable-nls', action='store_true', default=False,
         help='Disables native language support', dest='disable_nls')
@@ -121,6 +153,24 @@ def set_options (opt):
 def build (bld):
     bld.add_subdirs ('katze midori icons')
 
+    install_files ('DOCDIR', '/midori/', 'AUTHORS ChangeLog COPYING README')
+
+    if bld.env ()['RST2HTML']:
+        # FIXME: Build only if needed
+        if not os.access (blddir, os.F_OK):
+            os.mkdir (blddir)
+        if not os.access (blddir + '/docs', os.F_OK):
+            os.mkdir (blddir + '/docs')
+        if not os.access (blddir + '/docs/user', os.F_OK):
+            os.mkdir (blddir + '/docs/user')
+        os.chdir (blddir + '/docs/user')
+        subprocess.call ([bld.env ()['RST2HTML'], '-stg',
+            '--stylesheet=../../../docs/user/midori.css',
+            '../../../docs/user/midori.txt',
+            'midori.html',])
+        os.chdir ('../../..')
+        install_files ('DOCDIR', '/midori/user/', blddir + '/docs/user/midori.html')
+
     if bld.env ()['INTLTOOL']:
         bld.add_subdirs ('po')