doc for :transfomer

[hermanhel]

One important tip I found about using :transformer is that if you prepend any text, you need to make sure the returned string have the proper text-property org-marker at position 0, or org-agenda-goto (usually bound to TAB that let you jump to the headline in file) would not work.

Since this is a must I think it's probably good idea to include in the doc? Following is an example

                 :transformer (let* ((effort (get-text-property 0 'effort it))
                                     (org-marker (get-text-property 0 'org-marker it))
                                     )
                                (concat (propertize (concat "[effort: " effort "]")
                                                    'face 'italic
                                                    'org-marker org-marker ;; (1)
                                                    )
                                        it)
                                )

If remove line (1), in resulting org-agenda buffer, TAB on those lines will show in message org-agenda-error: Command not allowed in this line; if with, will behave as intended and jump to the corresponding position.

[alphapapa]

Hello Herman,

Thanks for noticing this; it's a good point.

We could "fix" this by documenting this requirement, but it would probably be better to fix the code to ensure that the necessary text properties are taken from the original string and applied to the transformed string.

What do you think?