[Typo3-typo3org] Fwd: Broken Link In "Inside TYPO3"

[Robert Lemke]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hey Kasper,

Kasper Skårhøj wrote:

>>   - pro: cleaner hirarchical representation of the content
>>   - con: what if we change the category of a manual?
>>
>> The question is: Will the latter ever happen? Will an extension manual
>> become a tutorial?
> 
> Personally I would leave the category out of the URL and rely only the the
> extension key.

Yes, sure. But I'd like to have some overview pages which only show the
documents of a certain category. 

   typo3.org/documentation/document-library/tutorials/
   ... shows a list of all tutorials.

   typo3.org/documentation/document-library/extension-manuals/
   ... displays a two-column list of extension manuals.

But even if we left out the category, the URLs would still not be
backwards-compatible, because we need the keyword "view":

   .../document-library/extension-manuals/view/templavoila/...

"view" is mapped to the keyword "ter_doc_html_readonline" which is the key
of the service which renders the HTML output. Another possible key is
ter_doc_html_oppctgz which lets you download a tgz with the HTML version,
one page per chapter.

>>    A) use chapter titles
> All cons are handled perfectly with realurl at present time. if a database
> lookup is not possible with the docbook implementation a user function
> call is needed. I will implement that right away for you (meaning today!

Okay, persuaded ;-) So the URL would look like this:

typo3.org/documentation/document-library/extension-manuals/view/templavoila/introduction/what-does-it-do

However, _currently_ the URL with TER 1 looks like that:

typo3.org/documentation/document-library/templavoila/What_does_it_do-f9aaecd761/

Therefore I suggest we just leave the current scheme and create a mapping
from old to new URLs in some way. I don't think that it's a good idea if we
keep the hash for example.

>>    B) use chapter numbers
> This is in my eyes big problem since documents with new sections will have
> new chapternumbers.

Agreed.

> What I don't get is why Open Office (or docbook?) doesn't apply unique id
> numbers to any header created? This would solve all these trouble for us.

I don't get that either. Even worse: OpenOffice uses the heading text itself
as an ID internally (at least in version 1.x). That means you cannot link
to the second appearance of a heading because the id is the same and the
link would always bring you to the first heading with that id.

> As long as they don't I guess we have to rely on the current
> mapping-system we are using. Or?

I strongly suggest to drop that mapping. As you said: it's a huge task
trying to keep that updated and most people didn't. Furthermore I created
the TER 2 in way that no further action is necessary after uploading an
extension and it would be great if could stay like it.

What I sugesst is to not only use the heading as a parameter but have
chapter and section title. Here's my example again:

typo3.org/documentation/document-library/extension-manuals/view/templavoila/0.1.0/introduction/what-does-it-do
typo3.org/documentation/document-library/templavoila/What_does_it_do-f9aaecd761/

If someone changes the title of "what does it do" and someone links to it,
he will at least land at the chapter were the section originally was (if
section not found, display first section of chapter). If the chapter
doesn't exist anymore, the TOC will be shown.

And now comes the part with the version number: I still think we should have
the version number in the URL, because *the document of a certain version
never changes*! If you link to a certain version of the document you can
always be sure that the chapter and sections exist.

To provide backwards compatibility and offer another way of accessing the
documents, we could agree on this rule: If the version parameter (0.1.0) is
not a valid version number, it is assumed that this is the chapter title of
the most recent version.

These two links would link to the same place provided that "0.1.0" is the
latest version of the document:

typo3.org/documentation/document-library/extension-manuals/view/templavoila/0.1.0/introduction/what-does-it-do
typo3.org/documentation/document-library/extension-manuals/view/templavoila/introduction/what-does-it-do

Finally I have to create a plugin or RealURL configuration which accepts
this URL:

typo3.org/documentation/document-library/templavoila/What_does_it_do-f9aaecd761/

Displays a message that the URL has changed and points to the new location.
We can also send some HTTP header which tells the search enginges that the
document location has changed.

So, what do you think? Would

typo3.org/documentation/document-library/extension-manuals/view/templavoila/0.1.0/introduction/what-does-it-do

be a solution which we could live with for a very long time?

Cheers,
robert

- -- 
Robert Lemke
TYPO3 Association - Research & Development
Member of the board
http://association.typo3.org

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFDT5c6Du+3qCHvGSIRAn2SAJ9WZ/WPq3CpzOpl7im4X/ACegQnIACfQcaU
HziGrjtUDB/tkFuvLaEA10A=
=TqkY
-----END PGP SIGNATURE-----