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

[Robert Lemke]

Hi Kasper,

Kasper Skårhøj wrote:

> Regarding the documentation library it will actually keep its URLs if
> people will do the mapping correctly. But I have no hope they will because
> I couldn't. What if someone completely rearranged the document or re-wrote
> it? Not only will it be an incredible task to remap the URls to new
> chapters but it will be pointless because any link to a chapter can't be
> expected to make semantic sense anymore now that the information there
> might be much different.
> 
> Tim seems to imply that once-published-never-changed and that is pretty
> naive.

generally I agree with your points. Especially moving content within a
document is a problem we cannot solve really. 

My current ter_doc implementation creates URLs like this one:

http://typo3.org/documentation/document-library/tutorials/doc_tut_quickstart/0.1.0/view/1/9/

This would point to chapter 1, section 9 of version 0.1.0 of the getting
started tutorial.

After reading Tims article I'd rather drop the category part in the url
("tutorials"), but on the other hand I do want a page which shows all
documents of a certain category. So for the category question I have these
pros and cons:

  - 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?

As for the chapter number / title issue I see the following choices:

   A) use chapter titles
      PROs: 
         - human readable path
         - if chapter moves within the document, the URL is still correct
       CONs:
        - disadvantages: if chapter title changes, URL is invalid. 
        - If chapter titles exist more than once, we need a hash. 
        - requires a DB lookup for RealURL to determine the chapter 
          title. However, that information is not available in the DB
          (in the TER 2 implementation)! Another solution would be
          to call a user function to determine the chapter title - is
          that possible with RealURL yet?

   B) use chapter numbers
      PROs: 
         - It's unique and short
         - Technically simple to achieve
         - If chapter titles change, the URL still works
      CONs:
         - Not nice to read for humans
         - If chapters move within the document, URL works but is wrong

And finally about crosslinking between documents:

I don't see a clean solution as long as we're only working with the
capabilities of OpenOffice. 

I might reveal a secret here that my documentation implementation for TER
2.0 is based on DocBook. That means, you're still working with OpenOffice
manuals if you like, but internally they are converted to DocBook. This
feature also allows you to write the manual directly in DocBook format and
use some of the features DocBook offers.

One feature which is quite interesting in this regard is the "olink" tag
[1]. This tag allows you to create links to other documents without
specifying the URL and also allows you to add some application specific
data (in our case: extension key and version number). The actual URL will
then be rendered by the TER frontend plugin.

So I would like to freeze this topic for a while, at least until we have the
TER2 up and running. It will then be quite easy to implement one or the
other solution.

Comments?

Cheers,
robert

[1] http://docbook.org/tdg/en/html/olink.html

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