WIP ....

adapt-and-extend/config/intro.rst

@@ -44,7 +44,7 @@ Mail
 Navigation
     Configure :doc:`how navigation is constructed <navigation>`. Which content types should appear in navigation, should folders on the top level become tabs, and which workflows to show.
 Site
-    Various :doc:`site wide settings <site>`: Site name, logo, metadata, default settings for handling of icons and preview images, settings for search engines and more.
+    Various :doc:`site wide settings <site>`: Site name, logo, metadata, default settings for handling of icons and preview images, toolbar options, settings for search engines and more.
 Add-ons
     :doc:`Activate and deactivate <add-ons>` add-ons that enhance Plone's functionality.
 Search

adapt-and-extend/config/site.rst

@@ -51,13 +51,13 @@ No thumbs in summary views
 No thumbs in table views
    Suppress thumbs in all tableviews and in folder contents view; this default can be overriden individually
 Thumb size for portlets
-   this default can be overriden individually
+   Choose from a pull down populated by available scales defined in the :doc:`Image handling control panel<image-handling.rst>`. This default can be overriden individually
 Thumb size for listings
-   e.g. standard view; this default can be overriden individually
+   E.g. for standard view; this default can be overriden individually
 Thumb size for tables
-   e.g., tabular view, folder content listing; this default can be overriden individually
+   E.g. for tabular view,  this default can be overriden individually. **This setting is also used for the folder content listing (can not be overridden).**
 Thumb size for summary view
-   this default can be overriden individually
+   This default can be overriden individually
 Toolbar position
     On modern wide-screen monitors, having the Toolbar to the side provides most usable space. But some people prefer it to be on the top of their screen.
 Site based relative URL for toolbar Logo

develop/addons/upgrade_to_50.rst

@@ -81,3 +81,9 @@ The version of plone.app.iterate used in Plone 5 implements this already making
 You should remove any hard dependency on plone.app.stagingbehavior from your add-on to avoid issues.
 
 See https://github.com/collective/collective.cover/pull/577/files for an example on how to achieve that.
+
+Content type icons
+==================
+
+A major breaking change from Plone 4.x to Plone 5 is how content type icons are handled.
+See :ref:content-type-icons-changed` for details. 

develop/addons/upgrade_to_51.rst

@@ -386,7 +386,138 @@ When you do not need them both, you can let the other return an empty list, or y
         @implementer(INonInstallable)
         class NonInstallable(object):
             ...
+.. _content-type-icons-changed
 
+Content type icons
+==================
+Since Plone 3 there have been several breaking changes relating to content type icon rendering.
+
+**Plone 3**
+
+Content type icons where rendered as HTML tags, which were rendered with methods from plone.app.layout.icon ...:
+
+.. code-block:: html
+
+   <span class="contenttype-document summary">
+          <img width="16" height="16" src="http://192.168.1.230:8322/Plone/document_icon.gif" alt="Page">
+          <a href="http://192.168.1.230:8322/Plone/front-page" class="state-published url">Welcome to Plone</a>
+   </span>
+
+
+.. note::
+
+    Related code in plone.app.layout  (especially `getIcon()` and  `IContentIcon`) and other locations was more then deprecated - it is obsolete and confusing and is getting removed.
+    The catalog metadata item getIcon used to be a string containing the file name of the appropriate icon (unused since Plone 4).
+
+    Since Plone 5.02 the catalog metadata item **getIcon** is reused for another purpose.
+    Now it is boolean and it is set to `True` for items which are images or have an image property (e.g. a lead image).
+
+
+
+**Plone 4**
+
+Content type icons are rendered as background images using a sprite image and css:
+
+.. code-block:: html
+
+   <span class="summary">
+         <a href="http://192.168.1.230:8412/Plone/front-page" class="contenttype-document state-published url">Welcome to Plone</a>
+   </span>
+
+   .icons-on .contenttype-document {
+       background: no-repeat transparent 0px 4px url(contenttypes-sprite.png);
+
+**Plone 5**
+
+Content type icons are rendered as ¸`fontello fonts <http://fontello.com/>`_ using css elements *before* or *after*.
+
+.. code-block:: html
+
+   <span class="summary" title="Document">
+        <a href="http://192.168.1.230:8082/Plone/front-page"
+             class="contenttype-document state-published url"
+             title="Document">Welcome to Plone</a>
+   </span>
+
+   body#visual-portal-wrapper.pat-plone .outer-wrapper [class*="contenttype-"]:before, .plone-modal-body [class*="contenttype-"]:before {
+       font-family: "Fontello";
+       font-size: 100%;
+       padding: 0;
+       margin: 0;
+       position: relative;
+       left: inherit;
+       display: inline-block;
+       color: inherit;
+       width: 20px;
+       height: 20px;
+       text-align: center;
+       margin-right: 6px;
+       content: '\e834';
+   }
+
+Example from plonetheme.barceloneta/plonetheme/barceloneta/theme/less/contents.plone.less:
+
+.. code-block:: 
+
+     body#visual-portal-wrapper.pat-plone .outer-wrapper, .plone-modal-body{
+      [class*="contenttype-"]:before {
+         font-family:"Fontello"; font-size: 100%;
+         padding: 0; margin:0; position: relative; left: inherit; display: inline-block; color: inherit;
+         width: 20px; height: 20px; text-align: center; margin-right: @plone-padding-base-vertical;
+         content: '\e834';
+      }
+      .contenttype-folder:before {  content: '\e801';}
+      .contenttype-document:before {   content: '\e80e';}
+      .contenttype-file:before {   content: none;}
+      .contenttype-link:before {    content: '\e806';}
+      .contenttype-image:before {      content: '\e810';}
+      .contenttype-collection:before {content: '\e808';}
+      .contenttype-event:before {      content: '\e809';}
+      .contenttype-news-item:before {  content: '\e80f';}
+   }
+The wildcard definition :code:`[class*="contenttype-"]:before ....content: '\e834'` renders the default icon for dexterity content types for all dexterity items 
+which have no specific css rule (e.g. custom dexterity content types). 
+
+
+The rule :code:`.contenttype-file:before {   content: none;}` prevents rendering a fontello font for **file** type items (e.g. *.pdf, *.docx, etc..).
+
+Instead a **mimetype icon** (fetched from the mime type registry) is rendered as html tag ( - there would be too many fonts needed for all the mime types)in affected templates e.g. in plone.app.contenttypes.browser.templates.listing.pt:
+
+.. code-block:: 
+   <span class="summary" tal:attributes="title item_type">
+     <a tal:condition="python:item_type == 'File' and showicons" 
+       tal:attributes="href item_link;
+                       class string:$item_type_class $item_wf_state_class url;
+                       title item_type">
+       <image class="mime-icon" 
+               tal:attributes="src item/MimeTypeIcon">
+     </a>
+     <a tal:attributes="href item_link;
+                          class string:$item_type_class $item_wf_state_class url;
+                          title item_type"
+         tal:content="item_title">Item Title
+     </a>
+    .....
+   </span>
+          .
+
+.. image:: /_static/content-type-icons.png
+   :align: center
+   :alt: content type icons
+
+The design decision to use Fontello fonts throws up the question how to easily create custom fonts for new created custom dexterity items.
+
+A workaround for that is to use an icon url in the :before clause.
+For the custom dexterity type *dx1* you might add the line :code:`.contenttype-dx1:before {content: url('dx1_icon.png')}` to your less file and place the icon file in to the same folder.
+
+Preview Images (Thumbs)
+=======================
+
+Preview images (aka thumbs) can be shown in listings, tables and portlets. 
+
+
+.. TODO::
+   to be ctd.
 
 Retina image scales
 ===================

working-with-content/introduction/visual-design-of-plone.rst

@@ -59,12 +59,13 @@ Traditionally, the out-of-the-box look is like that shown at the top of this pag
 But using the flexible "Diazo" theme engine of Plone, each aspect can be made to look any way the designer chooses, and can also be shown different depending on the device of the visitor.
 
 
-Icons and Preview Images (aka Thumbs)
--------------------------------------
+.. _content-type-icons-intro
+Content Type Icons
+------------------
 
 **Icons** are used to highlight actions, options etc. in menu bars, property sheets and the like:
 
-.. figure:: /_static/icons.png
+.. image:: /_static/icons.png
    :align: center
    :alt: Icons used in Plone user interface
 
@@ -73,34 +74,35 @@ Icons and Preview Images (aka Thumbs)
 Furthermore **icons** can be used to help to visually identify **content types** in any kind of listing or tables.
 For the content type *File* mime type icons are used to visualize the format of the given file.
 
-This feature is adjustable to a very high degree. There are default settings which can be configured in the `Site Configuration panel </adapt-and-extend/config/site.html>`_.
+This feature is adjustable to a very high degree. There are default settings which can be configured in the :doc:`Site Configuration panel </adapt-and-extend/config/site>`.
 This default settings can be overidden for each content item (edit: settings) or portlet respectively. 
 
 
-.. figure:: /_static/icons2.png
+.. image:: /_static/icons2.png
    :align: center
    :alt: Content type icons
 
-
+Preview Images (aka Thumbnails, Thumbs)
+---------------------------------------
 **Preview Images (or thumbnails, thumbs)**  for image items or any other content items which have a lead image
 (or teaser image) can be shown in any listing or table. 
 Additional to the same configuraion options for icons above you can define default sizes for the preview images for, tables, lists or portlets and also overwrite these settings individually.  
 
 
-.. figure:: /_static/thumbs-example-1.png
+.. image:: /_static/thumbs-example-1.png
    :align: center
    :alt: Example: preview images and icons with different settings
 
 
 Depending on the default settings for table views the  content view of a folder will show preview images or not:
 
 
-.. figure:: /_static/contents-with-thumbs-suppressed.png
+.. image:: /_static/contents-with-thumbs-suppressed.png
    :align: center
    :alt: Example: content view with thumbs not shown
 
 
-.. figure:: /_static/contents-with128x128.png
+.. image:: /_static/contents-with128x128.png
    :align: center
    :alt: Example: content view with thumbs  shown