Skip to content

Commit cb6e011

Browse files
bedneebednee
committed
Merge pull request #50 from tmotyl/migrate_docs
[TASK] Migrate documentation from sxw to rst
2 parents 2129fc0 + 7a5b934 commit cb6e011

26 files changed

Lines changed: 755 additions & 0 deletions

File tree

‎Documentation/ChashIssue/Index.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
.. include:: ../Includes.txt
2+
3+
4+
5+
.. _cHash-issue:
6+
7+
cHash issue
8+
-----------
9+
10+
It's an ugly parameter, that needs to be removed from URLs. To remove
11+
cHash, you have to put
12+
13+
::
14+
15+
<part>
16+
<parameter>cHash</parameter>
17+
</part>
18+
19+
20+
into predefinedparts. But it can cause trouble, when it's not used
21+
right. The easiest way is to make an extension COA\_INT and you don't
22+
have to care about the rest. But if you care about performance, this
23+
is not the best way to go.
24+
25+
The crucial thing is that ALL parameters need to be translated into
26+
"cool" form. I'll explain the reason. Let's say that there are 2
27+
URLs:
28+
29+
`id=10&par=foo&cHash=abc`
30+
31+
`id=10&par=bar&cHash=xyz`
32+
33+
now, the "par" is not translated, "id" is (as it's page id) and
34+
"cHash" is removed. Then the cache is at first filled with this
35+
double:
36+
37+
`id=10&par=foo&cHash=abc || /page/path/`
38+
39+
as you can see, the "par" is not cached, because it hasn't been
40+
translated. Now, the second URL is generated and since the "cool part"
41+
is again only "/page/path", no new value is created in the cache,
42+
because the "/page/path" value is already in the database.
43+
44+
Now, if a request for "/page/page/?par=bar" comes, first double is
45+
found and cHash that belongs to par=abc is fetched. And that's
46+
obviously wrong.
47+
48+
So, to make cHash work as expected, all parameters need to be
49+
translated into the cool form. That means, no ? in any URL.
50+
51+

‎Documentation/Contact/Images.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. |img-1| image:: ../Images/manual_html_img-1.png
2+
.. :align: left
3+
.. :border: 0
4+
.. :height: 32
5+
.. :id: Graphic1
6+
.. :name: Graphic1
7+
.. :width: 102

‎Documentation/Contact/Index.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. include:: ../Includes.txt
2+
.. include:: Images.txt
3+
4+
5+
.. _Contact:
6+
7+
Contact
8+
-------
9+
10+
Please post bugreports to Forge: `http://forge.typo3.org/projects/show
11+
/extension-cooluri <http://forge.typo3.org/projects/show/extension-
12+
cooluri>`_
13+
14+
Ask questions in the typo3-english newsgroup. To make sure, I'll read
15+
your message there, put “cooluri” keyword into your subject.
16+
17+
|img-1| EXT: CoolURI - 6
18+
19+

‎Documentation/Faq/Index.rst‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
.. include:: ../Includes.txt
2+
3+
4+
5+
.. _FAQ:
6+
7+
FAQ
8+
---
9+
10+
11+
.. _Q-How-to-change-order-of-fields-from-which-a-title-is-retrieved:
12+
13+
Q: How to change order of fields from which a title is retrieved?
14+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
15+
16+
**A:** Order is set in element title. Default order is:
17+
`<title>alias,subtitle,title</title>`
18+
19+
20+
.. _Q-How-to-set-a-translation:
21+
22+
Q: How to set a translation?
23+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
24+
25+
**A:** You need to add a subelement <part> to element <uriparts>. Most
26+
rewriting is from "param[key]=value" to "somecoolvalue". Where the
27+
rewriting looks for "somecoolvalue" in the database:
28+
29+
::
30+
31+
<part>
32+
<parameter>param[key]</parameter>
33+
<lookindb>
34+
<to>SELECT title FROM table WHERE uid=$1</to>
35+
<urlize>1</urlize>
36+
</lookindb>
37+
</part>
38+
39+
40+
.. _Q-Value-isn-t-translated-OK-Instead-of-national-characters-I-get-dashes:
41+
42+
Q: Value isn't translated OK. Instead of national characters I get dashes.
43+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
44+
45+
**A:** The problem is with Debian server, that doesn't support iconv
46+
translit conversion very well. The way to fix this is replace all
47+
occurences of ``<urlize>1</urlize>`` to ``<sanitize>1</sanitize>`` in
48+
the XML configuration.
49+
50+
**A2:** Instead of sanitize use ``<t3conv>1</t3conv>`` at the same
51+
places sanitize would be used. And place it into the pagepath element
52+
as well.
53+
54+
55+
.. _Q-I-get-PHP-error-after-installing-CoolURI-extension:
56+
57+
Q: I get PHP error after installing CoolURI extension
58+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59+
60+
**A:** Please, make sure, you meet all requirements (see above).
61+
62+
63+
.. _Q-How-to-migrate-from-simulateStaticDocuments-to-CoolUri:
64+
65+
Q: How to migrate from simulateStaticDocuments to CoolUri
66+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
67+
68+
**A:** You need to update your rewrite rules.
69+
70+
::
71+
72+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
73+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
74+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-l
75+
RewriteRule ^/.+\.(.+)\.[0-9]\.html /index.php?id=$1 [R=301,L,QSA,NE]
76+
77+
Here's description from *Peter Bücker* :
78+
79+
First of all, the left hand side obviously matches the URL format
80+
generated by SSD. The right hand side redirects all requests to
81+
/index.php with the id extracted from the request. It does this
82+
externally, with a HTTP 301 (permanently moved), so that users start
83+
using the new URLs. Of course, this is the last rule to be evaluated
84+
(L). In combination with "config.redirectOldLinksToNew = 1", this is
85+
really nice :-)
86+
87+
Furthermore, QSA tells Apache to append all query strings originally
88+
found in the request URI to /index.php?id=$1. Without QSA, those query
89+
strings would be discarded. NE stands for "no escape", which means
90+
that characters like '[' won't be replaced by their percent-coded
91+
counterparts. I didn't do further research, but without NE, plugin
92+
parameters break.
93+
94+
Also note that the 4 mod\_rewrite directives have to be placed just
95+
above the usual RewriteCond... RewriteRule .\* /index.php stuff. So in
96+
effect, for httpd.conf, it will look like this:
97+
98+
::
99+
100+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
101+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
102+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-l
103+
RewriteRule ^/.+\.(.+)\.[0-9]\.html /index.php?id=$1 [R=301,L,QSA,NE]
104+
105+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
106+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
107+
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-l
108+
RewriteRule .* /index.php
109+
110+
111+
.. _Q-CoolUri-doesn-t-work-in-ISS-with-ISAPI:
112+
113+
Q: CoolUri doesn't work in ISS with ISAPI
114+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115+
116+
**A:** Try to add this line to localconf.php. Or set this value using
117+
the install tool:
118+
119+
`$TYPO3_CONF_VARS['SYS']['requestURIvar'] = '_SERVER|HTTP_X_REWRITE_URL';`
120+
121+
122+
.. _Q-How-to-mix-pagepath-with-other-parameters:
123+
124+
Q: How to mix pagepath with other parameters
125+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126+
127+
**A:** First you need to map parts of pagepath on parameters:
128+
129+
::
130+
131+
<part pagepath="1">
132+
<parameter>p1</parameter>
133+
</part>
134+
<part pagepath="1">
135+
<parameter>p2</parameter>
136+
</part>
137+
<part pagepath="1">
138+
<parameter>p3</parameter>
139+
</part>
140+
<part pagepath="1">
141+
<parameter>p4</parameter>
142+
</part>
143+
144+
this will map 4 parts of a pagepath to parameters p1 – p4.
145+
146+
Then you need to insert these parameters into paramorder:
147+
148+
::
149+
150+
<paramorder>
151+
<param>p1</param>
152+
<param>L</param>
153+
<param>p3</param>
154+
<param>p2</param>
155+
</paramorder>
156+
157+
this will produce URL like: firstlevel/english/thirdlevel/secondlevel.
158+
159+
160+
161+
162+
.. _Q-I-ve-got-multilanguage-tt-news-and-it-doesn-t-work-just-right:
163+
164+
Q: I've got multilanguage tt\_news and it doesn't work just right
165+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
166+
167+
**A:** Try this setup:
168+
169+
::
170+
171+
<part>
172+
<parameter>tx_ttnews[tt_news]</parameter>
173+
<lookindb>
174+
<to>SELECT title FROM tt_news WHERE (uid=$1 or l18n_parent=$1) AND sys_language_uid={L=0}</to>
175+
<t3conv>1</t3conv>
176+
</lookindb>
177+
</part>
178+
179+
180+
181+
.. _Q-I-ve-got-news-with-same-titles-and-I-d-like-to-append-X-where-X-would-be-an-increasing-number:
182+
183+
Q: I've got news with same titles and I'd like to append -X, where X would be an increasing number.
184+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
185+
186+
**A:** Use this query:
187+
188+
::
189+
190+
SELECT CONCAT(tt1.title,IF(tt2.number>1,CONCAT('-',tt2.number),''))
191+
FROM tt_news as tt1,
192+
(SELECT COUNT(*) AS number FROM tt_news WHERE title=(SELECT title FROM tt_news WHERE uid=$1)) AS tt2
193+
WHERE tt1.uid=$1
194+
195+
196+
197+
198+
.. _Q-I-ve-changed-XML-configuration-but-nothing-happens:
199+
200+
Q: I've changed XML configuration but nothing happens
201+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
202+
203+
**A:** Parsed XML is now stored in users session. However, when user
204+
is logged in BE the session is omited, but this is still not working
205+
very well. So when you tweak your XML, you may need to close browser
206+
before you'd see some results.
207+

‎Documentation/Images/manual_html_img-1.png‎

4.43 KB
Loading

‎Documentation/Includes.txt‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. This is 'Includes.txt'. It is included at the very top of each and
2+
every ReST source file in THIS documentation project (= manual).
3+
4+
.. role:: aspect (emphasis)
5+
.. role:: html(code)
6+
.. role:: js(code)
7+
.. role:: php(code)
8+
.. role:: typoscript(code)
9+
10+
.. role:: ts(typoscript)
11+
:class: typoscript
12+
13+
.. default-role:: code
14+
.. highlight:: php

‎Documentation/Index.rst‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.. include:: Includes.txt
2+
3+
4+
5+
.. _start:
6+
7+
============
8+
EXT: CoolURI
9+
============
10+
11+
.. only:: html
12+
13+
:Classification:
14+
cooluri
15+
16+
:Version:
17+
|release|
18+
19+
:Language:
20+
en
21+
22+
:Description:
23+
RealURL alternative. Have nice URLs instead of ugly with parameters.
24+
CoolUri has user-friendly XML configuration file. For simple setup, just use the one supplied with extension and you are ready to go.
25+
26+
:Author:
27+
Jan Bednařík
28+
29+
:Email:
30+
info@bednarik.org
31+
32+
:License:
33+
This document is published under the Open Publication License
34+
available from http://www.opencontent.org/openpub/
35+
36+
:Rendered:
37+
|today|
38+
39+
The content of this document is related to TYPO3,
40+
a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
41+
42+
**Table of Contents**
43+
44+
.. toctree::
45+
46+
Introduction/Index
47+
UsersManual/Index
48+
ChashIssue/Index
49+
ThingsYouWontFindInTheManual/Index
50+
Faq/Index
51+
Support/Index
52+
Contact/Index
53+
Links
54+
Targets
55+
56+
57+
58+
59+

‎Documentation/Introduction/Index.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. include:: ../Includes.txt
2+
3+
4+
5+
.. _Introduction:
6+
7+
Introduction
8+
------------
9+
10+
11+
.. toctree::
12+
13+
WhatDoesItDo/Index
14+
UriTransformer/Index
15+
Requirements/Index
16+

‎Documentation/Introduction/Requirements/Index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.. include:: ../../Includes.txt
2+
3+
4+
5+
.. _Requirements:
6+
7+
Requirements
8+
^^^^^^^^^^^^
9+
10+
\- PHP 5+ with SimpleXML enabled!
11+
12+
MySQL 4.1+
13+

0 commit comments

Comments
 (0)