12 Apr
2016
12 Apr
'16
2:56 p.m.
Hi devs,
We need to decide what is the expected link reference serialization
produced by the WYSIWYG editor when you create a link to a wiki page. I
think we have to choose between 3 options:
(1) Output untyped (ambiguous) link references whenever possible
(2) Always output unambiguous (typed) link references (both 'doc:' and
'space:')
(3) Always output 'doc:' link references (no 'space:' references)
Let's see the details:
= OPTION 1: Output untyped link references whenever possible =
== <7.2 ==
Link from A.B
* to A.WebHome (space home page) => [[WebHome]]
* to A.C (same space) => [[C]]
* to X.Y (different space) => [[X.Y]]
* to X.WebHome => [[X.WebHome]]
== 7.2+ ==
Link from A.B.WebHome
* to A.WebHome (its parent) => [[space:A]]
* to A.B.C or A.B.C.WebHome or A.C or A.C.WebHome (child or sibling) =>
[[C]] (very ambiguous)
* to A.B.C.D or A.B.C.D.WebHome (nested page two levels or more below) =>
[[.C.D]] (ambiguous)
* to A.C.D or A.C.D.WebHome (nested page under sibling) => [[A.C.D]]
(ambiguous)
* to X.Y.Z or X.Y.Z.WebHome => [[X.Y.Z]] (ambiguous)
Link from A.B (terminal)
* to A.WebHome (its parent) => [[space:A]]
* to A.C or A.C.WebHome (sibling) => [[C]] (ambiguous)
* to A.C.D or A.C.D.WebHome (nested page under sibling) => [[A.C.D]]
(ambiguous)
* to X.Y or X.Y.WebHome => [[X.Y]] (ambiguous)
Link from A.B.C (terminal) or A.B.C.WebHome
* to A.B.WebHome (its parent) => [[A.B]] (ambiguous)
PROS:
* shorter link references
* hides WebHome from source syntax on 7.2+
CONS:
* ambiguous link references
* complex code
* different output for <7.2 and 7.2+ in case of top level space [[WebHome]]
or [[A.WebHome]] vs. [[space:A]] (we need to check if support for nested
spaces is available)
= OPTION 2: Always output unambiguous link references =
== <7.2 ==
Link from A.B
* to A.WebHome (space home page) => [[doc:WebHome]] (relative)
* to A.C (same space) => [[doc:C]] (relative)
* to X.Y (different space) => [[doc:X.Y]]
* to X.WebHome => [[doc:X.WebHome]]
== 7.2+ ==
Link from A.B.WebHome
* to A.WebHome (its parent) => [[space:A]]
* to A.B.C (terminal child) => [[doc:C]] (relative)
* to A.B.C.WebHome (non-terminal child) => [[space:A.B.C]] (absolute)
* to A.C (terminal sibling) => [[doc:A.C]]
* to A.C.WebHome (non-terminal sibling) => [[space:A.C]]
* to A.B.C.D (terminal descendant) => [[doc:.C.D]] (relative)
* to A.B.C.D.WebHome (non-terminal descendant) => [[space:A.B.C.D]]
(absolute)
* to A.C.D (terminal descendant of sibling) => [[doc:A.C.D]]
* to A.C.D.WebHome (non-terminal descendant of sibling) => [[space:A.C.D]]
* to X.Y.Z => [[doc:X.Y.Z]]
* to X.Y.Z.WebHome => [[space:X.Y.Z]]
Link from A.B (terminal)
* to A.WebHome (its parent) => [[space:A]]
* to A.C (terminal sibling) => [[doc:C]] (relative)
* to A.C.WebHome (non-terminal sibling) => [[space:A.C]] (absolute)
* to A.C.D (terminal descendant of sibling) => [[doc:.C.D]] (relative)
* to A.C.D.WebHome (non-terminal descendant of sibling) => [[space:A.C.D]]
* to X.Y => [[doc:X.Y]]
* to X.Y.WebHome => [[space:X.Y]]
Link from A.B.C (terminal) or A.B.C.WebHome
* to A.B.WebHome (its parent) => [[space:A.B]] (absolute)
PROS:
* unambiguous link references ("what you link is what you get")
* slightly less complex code (but still complex)
* hides WebHome from source syntax on 7.2+
CONS:
* longer link references (because of "doc:" and "space:" prefixes)
* cannot specify relative 'space:' references
* different output for <7.2 and 7.2+ in case of [[doc:WebHome]] vs.
[[space:A]]
= OPTION 3: Always output 'doc:' references =
== <7.2 ==
Link from A.B
* to A.WebHome (space home page) => [[doc:WebHome]] (relative)
* to A.C (same space) => [[doc:C]] (relative)
* to X.Y (different space) => [[doc:X.Y]]
* to X.WebHome => [[doc:X.WebHome]]
== 7.2+ ==
Link from A.B.WebHome
* to A.WebHome (its parent) => [[doc:A.WebHome]]
* to A.B.C (terminal child) => [[doc:C]] (relative)
* to A.B.C.WebHome (non-terminal child) => [[doc:.C.WebHome]] (relative)
* to A.C (terminal sibling) => [[doc:A.C]]
* to A.C.WebHome (non-terminal sibling) => [[doc:A.C.WebHome]]
* to A.B.C.D (terminal descendant) => [[doc:.C.D]] (relative)
* to A.B.C.D.WebHome (non-terminal descendant) => [[doc:.C.D.WebHome]]
(relative)
* to A.C.D (terminal descendant of sibling) => [[doc:A.C.D]]
* to A.C.D.WebHome (non-terminal descendant of sibling) =>
[[doc:A.C.D.WebHome]]
* to X.Y.Z => [[doc:X.Y.Z]]
* to X.Y.Z.WebHome => [[doc:X.Y.Z.WebHome]]
Link from A.B (terminal)
* to A.WebHome (its parent) => [[doc:WebHome]] (relative)
* to A.C (terminal sibling) => [[doc:C]] (relative)
* to A.C.WebHome (non-terminal sibling) => [[doc:.C.WebHome]] (relative)
* to A.C.D (terminal descendant of sibling) => [[doc:.C.D]] (relative)
* to A.C.D.WebHome (non-terminal descendant of sibling) =>
[[doc:.C.D.WebHome]] (relative)
* to X.Y => [[doc:X.Y]]
* to X.Y.WebHome => [[doc:X.Y.WebHome]]
Link from A.B.C (terminal)
* to A.B.WebHome (its parent) => [[doc:WebHome]] (relative)
Link from A.B.C.WebHome
* to A.B.WebHome (its parent) => [[doc:A.B.WebHome]] (absolute)
PROS:
* unambiguous link references ("what you link is what you get")
* relative references for nested non-terminal descendants
* same output for <7.2 and 7.2+
* simpler code (easier to maintain)
CONS:
* doesn't hide WebHome from source syntax
* longer link references (because of "doc:" prefix and "WebHome"
suffix)
I don't like ambiguous links so I'm against option (1). I don't think the
WYSIWYG editor users care too much about the wiki syntax (option 2), as I
commented on http://jira.xwiki.org/browse/XWIKI-13083, so I'm +1 for option
(3).
WDYT?
Thanks,
Marius