Merge pull request #50 from tmotyl/migrate_docs

[TASK] Migrate documentation from sxw to rst

Documentation/ChashIssue/Index.rst

@@ -0,0 +1,51 @@
+.. include:: ../Includes.txt
+
+
+
+.. _cHash-issue:
+
+cHash issue
+-----------
+
+It's an ugly parameter, that needs to be removed from URLs. To remove
+cHash, you have to put
+
+::
+
+   <part>
+         <parameter>cHash</parameter>
+   </part>
+
+
+into predefinedparts. But it can cause trouble, when it's not used
+right. The easiest way is to make an extension COA\_INT and you don't
+have to care about the rest. But if you care about performance, this
+is not the best way to go.
+
+The crucial thing is that ALL parameters need to be translated into
+"cool" form. I'll explain the reason. Let's say that there are 2
+URLs:
+
+`id=10&par=foo&cHash=abc`
+
+`id=10&par=bar&cHash=xyz`
+
+now, the "par" is not translated, "id" is (as it's page id) and
+"cHash" is removed. Then the cache is at first filled with this
+double:
+
+`id=10&par=foo&cHash=abc || /page/path/`
+
+as you can see, the "par" is not cached, because it hasn't been
+translated. Now, the second URL is generated and since the "cool part"
+is again only "/page/path", no new value is created in the cache,
+because the "/page/path" value is already in the database.
+
+Now, if a request for "/page/page/?par=bar" comes, first double is
+found and cHash that belongs to par=abc is fetched. And that's
+obviously wrong.
+
+So, to make cHash work as expected, all parameters need to be
+translated into the cool form. That means, no ? in any URL.
+
+

Documentation/Contact/Images.txt

@@ -0,0 +1,7 @@
+.. |img-1|      image:: ../Images/manual_html_img-1.png
+.. :align: left
+.. :border: 0
+.. :height: 32
+.. :id: Graphic1
+.. :name: Graphic1
+.. :width: 102

Documentation/Contact/Index.rst

@@ -0,0 +1,19 @@
+.. include:: ../Includes.txt
+.. include:: Images.txt
+
+
+.. _Contact:
+
+Contact
+-------
+
+Please post bugreports to Forge: `http://forge.typo3.org/projects/show
+/extension-cooluri <http://forge.typo3.org/projects/show/extension-
+cooluri>`_
+
+Ask questions in the typo3-english newsgroup. To make sure, I'll read
+your message there, put “cooluri” keyword into your subject.
+
+|img-1| EXT: CoolURI - 6
+
+

Documentation/Faq/Index.rst

@@ -0,0 +1,207 @@
+.. include:: ../Includes.txt
+
+
+
+.. _FAQ:
+
+FAQ
+---
+
+
+.. _Q-How-to-change-order-of-fields-from-which-a-title-is-retrieved:
+
+Q: How to change order of fields from which a title is retrieved?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** Order is set in element title. Default order is:
+`<title>alias,subtitle,title</title>`
+
+
+.. _Q-How-to-set-a-translation:
+
+Q: How to set a translation?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** You need to add a subelement <part> to element <uriparts>. Most
+rewriting is from "param[key]=value" to "somecoolvalue". Where the
+rewriting looks for "somecoolvalue" in the database:
+
+::
+
+   <part>
+        <parameter>param[key]</parameter>
+        <lookindb>
+          <to>SELECT title FROM table WHERE uid=$1</to>
+          <urlize>1</urlize>
+        </lookindb>
+   </part>
+
+
+.. _Q-Value-isn-t-translated-OK-Instead-of-national-characters-I-get-dashes:
+
+Q: Value isn't translated OK. Instead of national characters I get dashes.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** The problem is with Debian server, that doesn't support iconv
+translit conversion very well. The way to fix this is replace all
+occurences of ``<urlize>1</urlize>`` to ``<sanitize>1</sanitize>`` in
+the XML configuration.
+
+**A2:** Instead of sanitize use ``<t3conv>1</t3conv>``  at the same
+places sanitize would be used. And place it into the pagepath element
+as well.
+
+
+.. _Q-I-get-PHP-error-after-installing-CoolURI-extension:
+
+Q: I get PHP error after installing CoolURI extension
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** Please, make sure, you meet all requirements (see above).
+
+
+.. _Q-How-to-migrate-from-simulateStaticDocuments-to-CoolUri:
+
+Q: How to migrate from simulateStaticDocuments to CoolUri
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** You need to update your rewrite rules.
+
+::
+
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-l
+   RewriteRule ^/.+\.(.+)\.[0-9]\.html     /index.php?id=$1 [R=301,L,QSA,NE]
+
+Here's description from  *Peter Bücker* :
+
+First of all, the left hand side obviously matches the URL format
+generated by SSD. The right hand side redirects all requests to
+/index.php with the id extracted from the request. It does this
+externally, with a HTTP 301 (permanently moved), so that users start
+using the new URLs. Of course, this is the last rule to be evaluated
+(L). In combination with "config.redirectOldLinksToNew = 1", this is
+really nice :-)
+
+Furthermore, QSA tells Apache to append all query strings originally
+found in the request URI to /index.php?id=$1. Without QSA, those query
+strings would be discarded. NE stands for "no escape", which means
+that characters like '[' won't be replaced by their percent-coded
+counterparts. I didn't do further research, but without NE, plugin
+parameters break.
+
+Also note that the 4 mod\_rewrite directives have to be placed just
+above the usual RewriteCond... RewriteRule .\* /index.php stuff. So in
+effect, for httpd.conf, it will look like this:
+
+::
+
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-l
+   RewriteRule ^/.+\.(.+)\.[0-9]\.html     /index.php?id=$1 [R=301,L,QSA,NE]
+
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
+   RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-l
+   RewriteRule .*     /index.php
+
+
+.. _Q-CoolUri-doesn-t-work-in-ISS-with-ISAPI:
+
+Q: CoolUri doesn't work in ISS with ISAPI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** Try to add this line to localconf.php. Or set this value using
+the install tool:
+
+`$TYPO3_CONF_VARS['SYS']['requestURIvar'] = '_SERVER|HTTP_X_REWRITE_URL';`
+
+
+.. _Q-How-to-mix-pagepath-with-other-parameters:
+
+Q: How to mix pagepath with other parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** First you need to map parts of pagepath on parameters:
+
+::
+
+   <part pagepath="1">
+         <parameter>p1</parameter>
+       </part>
+       <part pagepath="1">
+         <parameter>p2</parameter>
+       </part>
+       <part pagepath="1">
+         <parameter>p3</parameter>
+       </part>
+       <part pagepath="1">
+         <parameter>p4</parameter>
+       </part>
+
+this will map 4 parts of a pagepath to parameters p1 – p4.
+
+Then you need to insert these parameters into paramorder:
+
+::
+
+   <paramorder>
+       <param>p1</param>
+       <param>L</param>
+       <param>p3</param>
+       <param>p2</param>
+     </paramorder>
+
+this will produce URL like: firstlevel/english/thirdlevel/secondlevel.
+
+
+
+
+.. _Q-I-ve-got-multilanguage-tt-news-and-it-doesn-t-work-just-right:
+
+Q: I've got multilanguage tt\_news and it doesn't work just right
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** Try this setup:
+
+::
+
+   <part>
+         <parameter>tx_ttnews[tt_news]</parameter>
+         <lookindb>
+           <to>SELECT title FROM tt_news WHERE (uid=$1 or l18n_parent=$1) AND sys_language_uid={L=0}</to>
+           <t3conv>1</t3conv>
+         </lookindb>
+   </part>
+
+
+
+.. _Q-I-ve-got-news-with-same-titles-and-I-d-like-to-append-X-where-X-would-be-an-increasing-number:
+
+Q: I've got news with same titles and I'd like to append -X, where X would be an increasing number.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** Use this query:
+
+::
+
+   SELECT CONCAT(tt1.title,IF(tt2.number>1,CONCAT('-',tt2.number),''))
+   FROM tt_news as tt1,
+   (SELECT COUNT(*) AS number FROM tt_news WHERE title=(SELECT title FROM tt_news WHERE uid=$1)) AS tt2
+   WHERE tt1.uid=$1
+
+
+
+
+.. _Q-I-ve-changed-XML-configuration-but-nothing-happens:
+
+Q: I've changed XML configuration but nothing happens
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**A:** Parsed XML is now stored in users session. However, when user
+is logged in BE the session is omited, but this is still not working
+very well. So when you tweak your XML, you may need to close browser
+before you'd see some results.
+

Documentation/Includes.txt

@@ -0,0 +1,14 @@
+.. This is 'Includes.txt'. It is included at the very top of each and
+   every ReST source file in THIS documentation project (= manual).
+
+.. role:: aspect (emphasis)
+.. role:: html(code)
+.. role:: js(code)
+.. role:: php(code)
+.. role:: typoscript(code)
+
+.. role:: ts(typoscript)
+   :class: typoscript
+
+.. default-role:: code
+.. highlight:: php

Documentation/Index.rst

@@ -0,0 +1,59 @@
+.. include:: Includes.txt
+
+
+
+.. _start:
+
+============
+EXT: CoolURI
+============
+
+.. only:: html
+
+   :Classification:
+      cooluri
+
+   :Version:
+      |release|
+
+   :Language:
+      en
+
+   :Description:
+      RealURL alternative. Have nice URLs instead of ugly with parameters.
+      CoolUri has user-friendly XML configuration file. For simple setup, just use the one supplied with extension and you are ready to go.
+
+   :Author:
+         Jan Bednařík
+
+   :Email:
+         [email protected]
+
+   :License:
+      This document is published under the Open Publication License
+      available from http://www.opencontent.org/openpub/
+
+   :Rendered:
+      |today|
+
+   The content of this document is related to TYPO3,
+   a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
+
+   **Table of Contents**
+
+.. toctree::
+
+   Introduction/Index
+   UsersManual/Index
+   ChashIssue/Index
+   ThingsYouWontFindInTheManual/Index
+   Faq/Index
+   Support/Index
+   Contact/Index
+   Links
+   Targets
+
+
+
+
+

Documentation/Introduction/Index.rst

@@ -0,0 +1,16 @@
+.. include:: ../Includes.txt
+
+
+
+.. _Introduction:
+
+Introduction
+------------
+
+
+.. toctree::
+
+   WhatDoesItDo/Index
+   UriTransformer/Index
+   Requirements/Index
+

Documentation/Introduction/Requirements/Index.rst

@@ -0,0 +1,13 @@
+.. include:: ../../Includes.txt
+
+
+
+.. _Requirements:
+
+Requirements
+^^^^^^^^^^^^
+
+\- PHP 5+ with SimpleXML enabled!
+
+MySQL 4.1+
+