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

[Kasper Skårhøj]

Hi Rob.

>lementation creates URLs like this one:
>
> http://typo3.org/documentation/document-library/tutorials/doc_tut_quickstar
>t/0.1.0/view/1/9/
>
> This would point to chapter 1, section 9 of version 0.1.0 of the getting
> started tutorial.

The category "tutorial" might be acceptable since it doesn't change too often. 
Your choice.

Adding the version number "0.1.0" is a no-go. This will invalidate old links 
on _any_ update of a document. If you intend to keep old documents I suppose 
you will have to use "doc_tut_quickstart/current/view/1/9/" where "current" 
simply looks up in the most recent document. In the archive you can use 
version numbers then.

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

Personally I would leave the category out of the URL and rely only the the 
extension key.

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

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! :-)

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

This is in my eyes big problem since documents with new sections will have new 
chapternumbers.

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

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

Interesting. 


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

- kasper


> Cheers,
> robert
>
> [1] http://docbook.org/tdg/en/html/olink.html

-- 
- kasper

-----------------
Think future, not feature