sandbox/html4trans/README.txt

   1 ..                            -*- rst-mode -*-
   2
   3 ===============================================
   4 HTML writer for lightweight browsers
   5 ===============================================
   6
   7 :Author: Guenter Milde <milde@users.sf.net>
   8 :Date: $Date$
   9
  10 .. contents::
  11
  12 Motivation
  13 ==========
  14
  15 The HTML Writer module, `docutils.writers.html4css1` produces XHTML
  16 compatible with the XHTML 1.0 specification.  Correct rendering of the HTML
  17 produced depends on the CSS support of the browser.  Browsers without full
  18 CSS support (lightweight browsers, older browsers, text-only browsers, help
  19 viewers) produce inferior results.
  20
  21 CSS is the state-of-the art technology for styling of html output and
  22 provides many advantages.
  23 However, correct rendering of HTML+CSS requires considerable resources in
  24 form of program code, memory space and computation time.
  25
  26 On older machines or in embedded devices this might pose a serious problem.
  27 Another example is a HTML help viewer of a program. It should start up fast
  28 ("immediately") and not take too much resources.
  29
  30 Editing and generating documentation with reStructuredText is possible with
  31 modest requirements on computer power. Viewing the result should be as well.
  32
  33 Solution
  34 ========
  35
  36 A separate HTML-transitional writer producing non-CSS based HTML.
  37
  38 The `html4trans`_ writer module subclasses the `html4css1.HTMLTranslator`
  39 and modifies it to remove the dependency on CSS browser support.
  40
  41 The output conforms to the XHTML version 1.0 Transitional DTD and contains
  42 enough formatting information to be viewed without a cascading style sheet by
  43 a lightweight html browser (e.g. Dillo_ or the console browser elinks_).
  44
  45 Drawbacks
  46 =========
  47
  48 Doing without CSS styling comes at a cost.
  49
  50 * The clear distinction of content and layout is lost. The HTML output
  51   contains a fair amount of "hard-coded" visual markup.
  52 * CSS style sheets can still be used but cannot override the non-CSS layout
  53   code. It is no longer possible to e.g. modify the colour of a warning text
  54   with a style sheet.
  55
  56 * Some more advanced features of CSS layout are hard or impossible to
  57   achieve with pure HTML code. Less important features, not implemented in
  58   this version of the "html4trans" writer are:
  59
  60   * Arabic, roman and alpha list markers for enumerated lists.
  61
  62   * Grey background for inline literal and literal blocks.
  63
  64   * Leading indentation in line-block objects.
  65
  66   * ``:Dedication:`` and ``:abstract:`` bibliographic fields.
  67
  68   * Topics, Sidebars, and Rubrics.
  69
  70   * Custom Roles with class attributes
  71
  72
  73 Files
  74 ========
  75
  76 * `<html4trans.py>`_ Simple Hypertext Markup Language document tree Writer.
  77
  78 * `rst2html_trans.py`_
  79   Front end to the Docutils Publisher, producing HTML not requiring
  80   a CSS stylesheet.
  81
  82 * `<docs>`_ Documentation
  83
  84 * `<tools>`_ Front-end and debugging scripts
  85
  86 * `<data>`_ sample documents
  87
  88
  89 Installation
  90 ============
  91
  92 Place `rst2html_trans.py`_ in the binary PATH and `html4trans.py`_ in the
  93 PYTHONPATH or in the working directory
  94 (from where you start ``rst2html_trans.py``).
  95
  96 Usage
  97 =====
  98
  99 Similar to the standard ``rst2html`` front end::
 100
 101   rst2html_trans.py [options] [<source> [<destination>]]
 102
 103 The full usage_ text can be obtained with the ``--help`` option.
 104
 105 Links
 106 =====
 107
 108 * DocArticle_
 109   is a comparable project by Bill Bumgarner. It is more specific
 110   in its approach, however, producing non-CSS based HTML that is compliant
 111   with the O'Reilly DevCenter's article submission guidelines.
 112
 113 * `Inside A Docutils Command-Line Front-End Tool`_
 114   How to roll your own Docutils front end. (Also see the other
 115   `API Reference Material for Client-Developers`_.)
 116
 117
 118 .. References
 119
 120 .. _html4trans:
 121 .. _html4trans.py: html4trans.py
 122 .. _rst2html_trans.py: tools/rst2html_trans.py
 123 .. _usage: docs/usage.html
 124
 125 .. _dillo: http://www.dillo.org
 126 .. _elinks: http://elinks.cz
 127 .. _DocArticle: ../bbum/DocArticle
 128 .. _Inside A Docutils Command-Line Front-End Tool:
 129      http://docutils.sourceforge.net/docs/api/cmdline-tool.html
 130 .. _API Reference Material for Client-Developers:
 131      http://docutils.sourceforge.net/docs/index.html#api-api-reference-material-for-client-developers
 132
 133
 134
 135
 136