=======================================
gocept.linkchecker feature descriptions
=======================================

Meta
====

Copyright (c) 2003-2006 gocept gmbh & co. kg,
See also LICENSE.txt

:Valid for: gocept.linkchecker 3.0
:Author: Christian Zagrodnick <cz@gocept.com>
:CVS: 


Reference Checking
==================

Asserting that links, that is URLs to put into your document to reference
other ressources, are available is the primary goal of gocept.linkchecker.

What it does
++++++++++++

.. image:: BrokenLinksPortlet.png
    :align: right

When you save a document the system looks at it and gathers all references it
finds. References are both links to other web pages (internally or externally)
and embedded images. 

Broken references are shown in the 'broken links' portlet. Links which are
affected by the reference management are colour coded in the following ways:

green 

  Everything is fine, the reference is ok 
  
orange

  The reference is temporarily not available, meaning it could just be
  available again at a later time. Reasons for the orange states are for
  example name resolution problems or 'Internal Server Errors'

red

  The reference is broken and will most likely not come back. A web server
  returning 'File not found' is one reason for this.
      
grey

  Grey refernces are either not tested (yet) nor not testable at all. Not
  testable are amongst others email addresses or javascript links.
  

The colour coding even affects the content area:

.. image:: ColouredLinks.png
    :align: center


After saving you get imediate feedback about the references the server already
knows about. This is if you link to http://www.gocept.com for instance and
you (or somebody else) has done so before you will see if it is reachable
without any delay.

References which are unknown yet, are scheduled for checking [#]_. When a
result is known, it's shown in the portlet and links overview.

Author's overview
+++++++++++++++++

Content authors have two overview pages.


Links of a Certain Object
-------------------------


.. image:: ObjectOverview.png
    :align: center


My Links
--------

The 'My Links' actions shows all broken links in the objects you have created,
grouped by their state (red, orange, grey)

.. image:: MyLinks.png
    :align: center

    
Manager's overview
++++++++++++++++++

The 'Link Management Overview' gives a high level overview about the site. It
refers to pages which show links by state and documents by state. 


.. image:: ManagementOverview.png
    :align: center

.. [#] Technical note: The actual checking is not handled within Plone, but by
       a separate server (the lms) and completely asynchronous. This means the
       lms notifies Plone about the result, the user does not have to wait for
       it.


Bi-directional Reference Checking
=================================

What it does
++++++++++++

.. image:: ReferencedByPortlet.png
   :target: ReferencedBy.png 
   :align: right

Every object which is being referenced shows this via a new portlet, the
"referenced by" portlet, which looks like this (click to see it in context)


Another way of recognising whether an object is being referenced is a new icon
in the folder listing. [#]_


.. image:: ReferencedByFolderListing.png
    :align: center


Limits
++++++

For several reasons there is *no* automatic updating of broken references, yet.
Automatic updating means for instance that when you rename a document, all
references pointing to that document are magically updated. 

The problem with this approach is the edge conditions. 

1. May be you do not *want* the refernces update because you just want to
   replace that document.

2. You might not have write permissions to the referencing documents.

3. How does this relate to workflows?

We decided to leave it with the user to care for those issues for now. 


.. [#] Note that you require another product, called glome, for the folder
       listing icon to work.
