[TYPO3-doc] DocBook: id attributes naming scheme

[François Suter]

Hi all,

Although the sample manual and the sample reference make heavy use of id 
attributes with a rather (I hope) consistent syntax, the latter has not 
been discussed openly. It's an important topic. We need to make sure that:

- it's consistent
- it's easy to "guess" so that documentation writers can easily create 
cross-links without having to think too much
- it must be useful for the online references

That last point is particularly important in my opinion. Indeed what I 
hope we can achieve with the new references in DocBook (the TSref for 
example) is to have shortcuts to access information just like functions 
on php.net, but more on that later (yes, it's a long mail, sorry, 
couldn't make it shorter).

Currently the id's are of this kind:

typo3v4.guides.sample.introduction.about

so we have the major version, the document category, the manual's key, 
and then we start we parts (if any), chapters and sections. Plus there 
are id attributes for pictures and procedures (one side question is 
whether we should have id's for tables and code listings too).

I think this is structure is rather fine for sample manuals, but feel 
free to comment on it.

However for references, I think it needs to be improved. Let's look at 
that id for example:

typo3v4.core.typoscript.function.stdWrap.setContentToCurrent

Again we first have the major version and the manual category, the the 
key to the manual (so we would probably have "tsref" for example 
instead). Then comes the part, the reference and the refentry.

Now the aim IMO when rendering references online is that we can achieve 
something like accessing function references on the PHP web site, i.e. 
in the same way that you can type:

http://php.net/strtotime

in the future we should be able to type:

http://typo3.org/typoscript/stdwrap

for example. In this case "typoscript" would be the keyword that 
triggers a reference to a manual (so we could also have "tsconfig", 
"tca") - perhaps with the additional help of Apache rewrite directives 
on the server. After that keyword the rest of the URL would reflect the 
TS hierarchy, e.g.:

http://typo3.org/typoscript/stdwrap

To achieve this the id's need to be shortened by removing the part, so 
the id in this case would be

typo3v4.core.typoscript.stdWrap

and would lead to the general stdWrap description, while:

http://typo3.org/typoscript/gifbuilder/text/text

would refer to the "text" property of the "TEXT" object inside the 
GIFBUILDER object (with id attribute 
"typo3v4.core.typoscript.gifbuilder.text.text").

This naming scheme has the following advantages:

- the categorization of TypoScript elements (function, object, data 
type) is not "visible" anymore (I know someone who will be happy about 
that), although it is still present as a part of the manual when 
browsing the full manual (just as in the current sample).
- it is easy to refer to a given function/object/property because it's 
quite a logical construction.
- the "landing pages" when someone shortens the URL is quite obvious 
(i.e. if typing only:

http://typo3.org/typoscript/gifbuilder/text

you get to the general page of the TEXT object of GIFBUILDER.)

We just have to take care of having really unique id's.

The thing with the URLs mentioned above is really just some 
brainstorming for now, there are many other related questions (like how 
to refer to a particular version), I just wanted to start raising this 
topic because of its influence on id attributes.

I hope this mail was clear enough :-) So what do you think?

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch