
Installation problems

  Broken public views after upgrading Silva to a newer version

    (for 0.9.3: AttributeError on get_title_html or KeyError on
    silva_icon_32.gif).

    Because some API changes in Silva might break the layout templates and 
    scripts in the Silva root, you should either replace those templates 
    and scripts with the default ones (by removing the old ones and placing
    the default ones using the 'Install default layout' button in 
    service_extensions) or, if you have custom versions of these objects 
    available, modify your custom templates and scripts to work with the 
    current Silva version.

    For more information see UPGRADE.txt.
    

  The Silva (and XMLWidgets and ParsedXML) Product is broken after
  installation.

    Most of the installation problems do have their source in an
    improper installation of the PyXML python module.

    Usually this can be diagnosed by the following lines in the error
    message one gets after a Zope start::

      ImportError: cannot import name expat

    Another symptom is that one gets the following error when trying
    to add a Silva Root::
 
       Error Type: AttributeError
       Error Value: StartDoctypeDeclHandler

    This is a problem occurring frequently with binary distributions
    of Zope; as the writing of this the corresponding issue in the
    collector is still pending, see
    http://collector.zope.org/Zope/678/view

    You can test for a proper PyXML installation by typing in the
    following lines into the python interpreter used to run Zope::

       from xml.parsers import expat

    (The full path to the python binary can be found in the shell
    script or batch file used to start Zope.)

    If the above statement fails with an ImportError, please try to
    fix the PyXML installation. Usually getting the version from the
    PyXML project home page http://pyxml.sourceforge.net helps fixing
    the problem.

    If this does not help, or is not an option for some reason, a
    possible workaround (read *hack*) is to create a file "pyexpat.py"
    in the directory 'lib/python2.1/xml/parsers' of the Zope
    installation, containing only the line::

      from _xmlplus.parsers.pyexpat import *

    or

      from Shared.DC.xml.pyexpat import *

    (or wherever the "pyexpat" module has been installed).


  After installing the Silva Product and restarting Zope, the server
  does not respond to HTTP request.

    This problem has been reported when using some binary
    distributions for the Debian Linux distribution. The server seems
    to start properly according to its own event log, but does not
    send any response to HTTP requests.

    The source of this problem is not known. The recommended work
    around is to use Python and Zope versions built from source.
    Especially for the operation systems where this issue has been
    reported this is rather painless; see
    e.g. http://www.infrae.com/products/silva/docs/SysAdmin/LinuxInstallation

   
  "AttributeError: _add_ordered_id"

    This happens if one imports the "demo.zexp" outside a Silva Root.
    Please first create a Silva Root via the ZMI and import the
    demo.zexp inside the Silva Root.


  Brokenness after upgrading Silva to a newer version

    Most of the problems after upgrading Silva are caused by missing
    product refresh via the 'service_extensions' object in the Silva
    Root. Please check with the instructions in the 'UPGRADE.txt' of
    the installed release, if you need to run a refresh after
    upgrading.

    Major releases usually need a content upgrade, too. This is also
    available via the 'service_extensions' by the 'upgrade content'
    button.

    Please try at least a 'refresh all' from the 'service_extensions'
    before reporting any problems with upgrading.

    Also please note in case of several Silva Roots within one Zope
    instance you need to run the upgrade for all Silva Roots
    separately after installation of an upgrades Silva version.


    Another possible source of problems arises if one installs
    a newer version of Silva in place over an existing one (i.e.
    by unpacking a *.tgz into a directory where an older version
    of Silva is installed, overwriting the older version.

    This will not remove files present in the older version.
    As it often happens that some files are move around 
    (or removed at all)  between releases, one would have some old 
    files still around after the upgrade, which may lead to malfunction 
    of the product.

    Especially there have been reports of an "AttributeError" with an 
    error value of "__hash__" after upgrading which seemed to be caused 
    by this upgrade strategy.

    Please remove (or move away) any old installation of Silva
    (and its companion products) before unpacking the new version 
    in your Products directory to avoid any problems.


  Silva only displays '?' for non-ascii characters in the public view
  after upgrading
 
    The cause of the problem is most probably a missing http header,
    which should be set by the 'index_html'. If you do not have a
    custom 'index_html', remove the current 'index_html' and select
    'install default layout' in the 'service_extensions'.

    If you have a custom 'index_html' and do not want to overwrite
    this with the default, be sure your custom 'index_html' sets up
    the 'Content-Type' header in the response properly; it should do
    something like:

      context.REQUEST.RESPONSE.setHeader('Content-Type', 'text/html;charset=utf-8')


  Some links, image references, etc. are broken after the upgrade which
  have been valid before the upgrade

    The cause of the problem is that Silva has added some new methods
    or other internal structures which impose new restrictions on the
    set of valid content object ids. To operate properly Silva renames
    content objects with conflicting ids to new ids in the upgrade 
    process. However it does not fix links in other content objects
    which reference theses objects.
    
    The upgrade process should leave a warning in the 'event.log' if it
    needs to rename a content object. As Silva does not have a operable
    reference management yet, You will have to check an possibly fix
    references to the renamed objects manually after the upgrade. 



Problems when using Silva 

  Unicode problems with Silva Images when Localizer is installed.

    There're some reports of unicode problems regarding Silva images when
    when the Localizer Product is installed. So far the only solution found
    is to uninstall Localizer, or set the environment variable
    LOCALIZER_USE_ZOPE_UNICODE in the script starting Zope.
    This may break other products which rely on Localizer to apply its
    unicode patches, however.

  Error when Adding a Silva Document
    
    After 0.9.2, Silva Document has been taken out of Silva in its own Product.
    You need to ensure you have no trailing empty directories in Silva Product.
    or with a cvs up -dP or by deleting them manually.

  Errors when editing a Silva Document via the SMI

    If the session got lost while editing a Document via the SMI some
    inconvenient error message may occur. The session loss may happen
    for the following reasons:

      - The session timed out due to a longer period of inactivity
        (aka the "lunchbreak error").

      - The session cookie has not been stored by the browser.

      - The Zope server has been restarted, wiping out all current
        sessions.

    Note that with Silva 0.9.2 we have added code to the "Editor" page
    that automatically pops up a window after some idle time, asking
    you if you want to save (thereby refreshing the session). If more
    time passes still, the user is automatically redirected to the
    "Preview" page. From there the user can safely return to the
    "Edit" page.

    If the session timeout happens to you as an author, follow these
    steps to recover:

      - use the "back button" to get a view of the "Editor" page.

      - click on the "Editor" tab to get a fresh session cookie.

      - proceed with editing; you may need to reopen the section you
        currently wanted to edit.

    If this does not help getting rid of the error, please check if
    your browser accepts cookies from the Zope server, and if you
    really got a cookie from the server when entering the "Editor"
    page.

    In any case the latest edits will be lost.

    Site managers may want to increase the session timeout to avoid
    problems due to the first reason. The session timeout can be found
    in the '/temp_folder/session_data' object in a default Zope
    installation. Changing the settings there will get lost after a Zope 
    restart.  
    Alternatively one can set the environment variable 
    ZSESSION_TIMEOUT_MINS in the script used to start Zope (2.6)
    You should be able to find more information about this in the 
    doc/ENVIRONMENT.txt of the Zope installation.
    Since Zope 2.7 (which is not yet supported by Silva),
    check with the variable "session-timeout-minutes" in the servers
    configuration file.


  "KeyError" in the user lookup view of the "Access" tab

     This is a session loss error for similar reasons as for errors in
     the "Editor" tab discussed in the first item of this
     section. Going to the page again should normally fix the issue.


  When inserting/saving/deleting, etc something in the "Editor" tab,
  the browser seems to reload the next page infinitely, but displays
  nothing

    This is a known issue when using Opera, see
    http://issues.infrae.com/silva/issue285. This should be fixed in
    Silva 0.9.2; if you still get this problem, please send a bug
    report. Do not forget to add the version of the browser you are
    using, the version of Silva and the last action you did when the
    problem occurs.

  When inserting/saving/deleting, etc something in the "Editor" tab,
  nothing has changed in the next page.

    This may be an issue with your browsers cache; e.g. you still have
    an old copy of the page viewed by your browser, because the
    browser did not reflect the change. Try to force a reload of the
    page.  (e.g. With IE press the "Ctrl" key while clicking the
    reload symbol).  If this solves the problem, please check with the
    caching policy of your browser; set the caching policy so the
    browser checks for a newer version every time it loads the page.

  "AttributeError: is_id_valid" or other errors when adding a Silva
  object via the ZMI

    Most probably the source of the error is that you have added a
    Silva object outside of a Silva Root. Most Silva objects cannot be
    added outside a Silva Root object, as they rely on the
    infrastructure (services etc) in the Silva Root object.

    Some special objects cannot be added via the ZMI even inside a Silva
    Root; they only should be created automatically by an installation
    script.

    Normally one should only create a Silva Root object via the ZMI
    and add other objects via the SMI inside this Silva Root object.


  "UnicodeError: ordinal not in range(128)"

    This may happen due to an undiscovered bug in Silva. Actually all
    bugs of this type should be fixed since 0.9.2, but if you see the
    error message it is likely one of them escaped.

    These bugs are somewhat complicated to track down. Please check
    the issue tracker at http://issues.infrae.com/silva for open
    issues with the topic "encoding".

    If there are no issues related to this, you may want to ask for
    help on silva-dev@lists.infrae.com. It would help a lot if you
    could provide a *.zexp exported file of the content object
    triggering the error.

    Additionally please provide information about where the bug
    appeared. Did this happen inside the SMI, and if it does, in which
    tab did this happen (e.g. "Editor", "Preview" ...)  If it happened
    in the "Editor" tab, which element did you edit when the problem
    appeared? E.g. Had this been in the nested subeditor of a table
    cell of complex list element, or when opening a paragraph for
    editing or when saving?

    If the problem happens in the public view only, and you did not
    use the standard layout shipped with Silva but a custom one,
    please try to reproduce this with the standard layout. Ask your
    site admin for assistance if necessary.

    See the section "Unicode Problems In-Depth" below if you would
    like to read more detailed information about this issue.


  Exporting Silva objects in XML format via the ZMI fails:
  "TypeError: object has read-only attributes"

    This simply does not work. Please use either the "Export"
    functionality in the *SMI* available from the "Status" tab, or
    export the object via the usual *.zexp format

  Objects from a freshly installed Silva extension are not in the list of 
  addables
  
    When the list of 'allowed addables' (which meta-types are allowed to be 
    added to the current publication and it's children) is set for an object
    (you can set those in the Settings tab of publications), a list of objects
    that *are* allowed to be added is stored on the publication. This means 
    that if a new extension is installed, the meta-types of the extension are 
    not in those lists. Each object on which the allowed addables is not set 
    to 'acquire' will have to be modified manually to allow adding the meta
    types of the extension product. Hopefully this will be changed in a later
    version of Silva.

  Indexer object doesn't work properly

    If you update the indexer object and get an 'Index updated'
    message, but the indexer doesn't change anyway, you'll likely have
    a missing 'xml.xpath' library. This is due to a missing or
    incomplete installation of PyXML.

  The SMI (or even the Zope server) seems to hang when copying a folder
  with a lot of contents.

    A possible cause may be that the data base cache is set to a too
    small value. The default value of 400 is far too small for most
    production systems.

    To change the size of the data base cache, visit the "Control_Panel"
    in the Zope root and choose "Database Management". The cache size
    can be set in the tab "Cache Parameters" in the input field:
    "Target number of objects in memory per cache".
    In the (not yet supported) Zope 2.7 you may set the cache size via
    the "cache-size" variable in the servers configuration file, section
    "Database"

  Unicode Problems In-Depth

    A computer is only able to work with digits. Therefore a computer
    uses numbers internally to represent characters. In the old days
    of computing, most computers were only able to represent a small
    subset of all characters used in natural languages. This subset
    was called ASCII. ASCII is a set of 128 characters that consists of
    the plain Roman script characters (the Western alphabet) and
    common printable and non-printable characters such as the question
    mark, dot, space, tab, etc.

    To be able to use other languages, people started creating
    different additional supersets of ASCII (usually defining another
    128 characters on top of ASCII) to represent characters from other
    natural languages. One of the best known of those ASCII supersets
    is called Latin-1 (ISO-8859-1), a set that describes more western
    characters used in languages such as Dutch, German and
    French. Some other character sets, in particular those for Asian
    languages like Japanese, are not supersets of ASCII at all but
    define their own meaning to each of 256 characters.
  
    The different encodings mean that these sets are not
    interchangeable. In fact, a computer can not even determine from a
    text which character encoding scheme was used, since character
    sets reuse the same numeric encoding for different
    encodings. Thus, character 100 in ASCII represents something
    completely different than 100 in a Japanese encoding such as
    JIS. With ASCII supersets such as Latin-1 the first 128 characters
    are displayed correctly as they conform to the ASCII set, but it
    will not be clear what to do with characters that fit in second
    range of 128.

    To overcome this limitation, a new set was developed called
    unicode. Unicode uses a far wider number space than just 128 or
    256 numbers; tens of thousands of different characters in a one
    set are supported. The goal is to assign a unique number to every
    character used in every natural language (and several unnatural
    ones) in the world.  There are unicode characters for virtually
    each language currently in use, and a lot more (e. g. ancient
    languages). This way different natural languages can be used
    together in the same text, and this text can be exchanged freely
    without running into encoding troubles, as all characters fit
    within a single encoding -- that of unicode.

    A common way to represent unicode in computer memory is to use 2
    or even more bytes per character instead of the single byte per
    character typically used for the ASCII and Latin-1 encodings.

    Unfortunately, much computer software was written that only deals
    with single-byte characters, including much of the software that
    makes up the internet. In order to interoperate an 8 bit encoding
    of the unicode set has been defined, called UTF-8. UTF-8 has the
    property that the first 128 characters are actually the same as in
    ASCII, so that older software can display at least any information
    that fits within the ASCII range properly. Most browsers are able
    to display UTF-8 characters correctly nowadays, so to be able to
    support as much different natural languages as possible in web
    applications, UTF-8 is the best choice.

    When writing an application, using unicode is currently the best
    way to store textual data. UTF-8 is the best way to send and
    receive data. This is exactly the setup Silva uses since
    0.9.2. Previous versions of Silva however used latin-1 in some
    areas, and encoded to latin-1; with Zope 2.6 some limitations were
    lifted which allowed us to switch over to the UTF-8/unicode scheme
    more easily.

    When Silva shows a 'Unicode error: ordinal not in range 128'
    error, that means that the computer has run into a piece of text
    that is not unicode, and it isn't able to turn it to unicode as
    well, because it contains characters from a character set other
    than ASCII (so with a number higher than 128).
  
    The error is caused because Zope (through Python's mechanisms)
    will try to implicitly convert these snippets to unicode,
    assuming the ASCII encoding for the 8 bit strings. The bad thing
    about this is that the conversion table only contains the 128
    ASCII characters; anything outside of this range cannot not be
    converted. This explains the somewhat obscure "ordinal not in
    range(128)" message.

    Characters not in the 128 range typically includes characters with
    accents and umlauts if you're in a latin language that uses a
    character encoding that supersets ASCII. These characters will
    typically trigger the bug while ASCII characters won't.

    If you're in a language that commonly uses a character encoding
    that is a not a superset of ASCII you'll probably see this problem
    right away.

    If there are non-unicode text in Silva content, this means there
    is a bug somehow. There are three possible sources of such text:

     - old text (in particular metadata) was stored as non-unicode in
       Silva 0.9.1 and earlier. Due to a bug in the upgrade script
       some of this code might not have been converted and this in the
       end triggers a unicode error when trying to present this
       content somewhere in a web page (mixing it with true unicode).
     
     - Silva tries to catch all user input and convert it to unicode
       right away. We might have missed a place in the Silva UI and
       non-unicode text might enter the system by this route. This is
       also a bug that needs to be found and plugged.

     - A custom layout template contains some text outside the ascii
       character range in the rendering code. The layout template
       needs to be fixed.

    If you run into a UnicodeError we would therefore appreciate it if
    you'd file in a bug report.

    If the content object triggering the problem is no longer
    accessible for edits from the Silva UI there is a temporary
    workaround: edit the XML representation via the ZMI and remove the
    offending XML element that triggers the bug by hand. Typically you
    can reach the XML by going to a url like this:

    http://myserver/path/to/content/0/content/manage_main

    where 0 should be the version number that you're currently
    editing.

    Again, this is a only a workaround to continue working; the real
    solution is to solve the bug, so send us a bug report!
