sandbox/gschwant/htmlnav/README.txt

   1 ==================
   2  README: htmlnav_
   3 ==================
   4
   5 ----------------------------------------------------------
   6 An HTML writer for docutils which supports navigation-bars
   7 ----------------------------------------------------------
   8
   9 :Author:    Gunnar Schwant
  10 :Contact:   g.schwant@gmx.de
  11 :Date:      $Date$
  12
  13 .. contents::
  14
  15 Introduction
  16 ============
  17
  18 This is the writer which I use to build my homepage: http://schwant.gmxhome.de.
  19 [#]_ The name **htmlnav** is a short term for *HTML with navigation-bars*.
  20
  21 System Requirements
  22 ===================
  23
  24 Docutils and everything needed to use docutils has to be
  25 installed.
  26
  27 Installation
  28 ============
  29
  30 Perform the usual ``setup.py install`` procedure.
  31
  32 Usage
  33 =====
  34
  35 Most parts of the writer are inherited from David Goodger's ``html4css1``.
  36 In fact, if no ``.nav``-files do exist in the destination directory, it
  37 produces the same output as David's writer.
  38
  39 Short example
  40 -------------
  41
  42 1. Go to docutils' "``tools``"-directory and create a file called
  43    "``left.nav``" with the following contents::
  44
  45      colors  | #000000  | #8E8E8E
  46      section | Home
  47      link    | Python   | http://www.python.org
  48      link    | Docutils | http://docutils.sf.net
  49      raw     | <br>
  50      raw     | &copy; 2003 MyCompany
  51
  52 2. Process "``test.txt``" to HTML using "``rst2htmlnav.py``"::
  53
  54     rst2htmlnav.py test.txt test.html
  55
  56    Open "``test.html``" in your browser. You will notice the left
  57    navigation-bar.
  58
  59 3. Create a file called "``right.nav``" in docutils' "``tools``"-directory.
  60    This time the contents are::
  61
  62      colors  | #000000 | #8E8E8E
  63      section | Contact
  64      link    | me@MyCompany.org | mailto:me@mycompany.org
  65
  66 4. Now perform step 2 again and open "``test.html``" in your browser.
  67    You will notice that there is a right navigation-bar now.
  68
  69 5. Create a file called "``top.nav``" in docutils' "``tools``"-directory
  70    with the following contents::
  71
  72     color     | #C8DBEB
  73     cornerpic | ../docs/rst/images/ball1.gif
  74     link      | Home     | test.html
  75     link      | Python   | http://www.python.org
  76     link      | Docutils | http://docutils.sf.net
  77     link      | Search   | http://www.google.com
  78
  79 6. Once again perform step 2 and open "``test.html``" in your browser.
  80    Now a top navigation-bar is there, too.
  81
  82 .nav-files
  83 ----------
  84
  85 In order to get navigation-bars in the output-page you have to create
  86 ``.nav``-files in the destination directory. There are 4 types of
  87 ``.nav``-files:
  88
  89 [file].nav
  90   This defines the left navigation-bar of the output-file ``[file].html``.
  91   (``[file]`` is the name of the output-file without extension.)
  92
  93 left.nav
  94   This defines the left navigation-bar of all output-files for which
  95   no ``[file].nav``-file is present.
  96
  97 right.nav
  98   This defines the right navigation-bar of all output-files.
  99
 100 top.nav
 101   This defines the top navigation-bar of all output-files.
 102
 103 .. important:: At least one of the files ``[file].nav`` and ``left.nav``
 104                has to be present. Otherwise no navigation-bars will be
 105                added to the output file.
 106
 107 .nav-file-entries
 108 -----------------
 109
 110 ``.nav``-files contain a one-liner for each navigation-bar-entry.
 111 In general such a one-liner is of the form
 112
 113 ::
 114
 115   parameter | value 1 | value 2
 116
 117 These are the different types of parameters:
 118
 119 color
 120 ~~~~~
 121
 122 :Used in: ``top.nav``
 123 :Value 1: Background-color of all navigation-bars.
 124 :Value 2: Not used.
 125 :Example: ``color | #8E8E8E`` sets the navigation-bars' background-color
 126           to ``#8E8E8E``. (The default color is white.)
 127
 128 colors
 129 ~~~~~~
 130
 131 :Used in: ``[file].nav``, ``left.nav``, ``right.nav``
 132 :Value 1: Background-color of section entries.
 133 :Value 2: Background-color of any other (non-section) entry.
 134 :Example: ``colors | #000000 | #8E8E8E`` sets the background-color to be
 135           ``#000000`` (black) for sections to be ``#8E8E8E`` (gray) for
 136           any other entry.
 137
 138 cornerpic
 139 ~~~~~~~~~
 140
 141 :Used in: ``top.nav``
 142 :Value 1: Path to the graphics file which will be displayed in the upper
 143           left corner of the top navigation-bar. (The *width* of a
 144           corner-picture should be 150 pixel.)
 145 :Value 2: Not used.
 146 :Example: ``cornerpic | pics/home.png`` sets the path of the corner-picture
 147           to ``pics/home.png``.
 148
 149 raw
 150 ~~~
 151
 152 :Used in: ``[file].nav``, ``left.nav``, ``right.nav``
 153 :Value 1: Any kind of text.
 154 :Value 2: Not used.
 155 :Example: ``raw | <br>`` will create an empty cell (a spacer) in
 156           the navigation-bar.
 157
 158 section
 159 ~~~~~~~
 160
 161 :Used in: ``[file].nav``, ``left.nav``, ``right.nav``
 162 :Value 1: Title of the section.
 163 :Value 2: Not used.
 164 :Example: ``section | Home`` will create a section with title *Home* in
 165           the navigation-bar.
 166
 167 link
 168 ~~~~
 169
 170 :Used in: ``[file].nav``, ``left.nav``, ``right.nav``, ``top.nav``
 171 :Value 1: Text to be displayed.
 172 :Value 2: URL
 173 :Example: ``link | Docutils | http://docutils.sf.net`` creates a link to
 174           Docutils' homepage in the navigation-bar.
 175
 176 Footnotes
 177 =========
 178
 179 .. [#] Sorry, my homepage is in german language. However, even if you
 180        don't understand what the text says, you'll get an impression of the
 181        writers output.
 182
 183 .. _htmlnav: writer/htmlnav.py