[pmwiki-users] RFC: Simple link markup for a "nearly WYSIWYG" editor

[Petko Yotov]

Hello,

I'm looking for a simple to learn and type link markup.

I am working on an easy to use "structured page editor" module. It will 
allow users to modify text in a paragraph, a heading, a list item and a 
table cell; to add, remove or rearrange headings, paragraphs, ordered 
and bulleted lists, list items, tables, table rows. It aims to be 
touch-screen-friendly, but to work even with old browsers like MSIE 6 
(with some features enabled depending on browser capacity, eg. Ajax 
uploads of files).

The module will have its own areas inside a wiki page text like 
{{{[=Module text here=]}}} so it can use its own markup rules without 
modifying or disabling existing markups.

I'll detail the features and the reasons for choosing them in a few days 
or weeks.

I'd like to read your ideas for a simple to type and understand link 
markup. The module allows editing of text blocks, but inside the regular 
textarea, I'd like to allow some inline wiki markup, for example for 
'''bold''' or ''italic'' text, and links:

* to external URLs,
* to pages in the same group, (preventing accidental cross-group 
linking)
* to pages in other groups, (not a priority)
* to files attached to the current upload directory (per page or per 
group),
* to pictures/videos/audios that would be embedded into the page rather 
than linked.

I wouldn't use a WikiWord link markup because there are many page names 
with a single word like "Telephones". I prefer to search for a markup 
other than [[PageName | link text]] because the characters [, | and ] 
are not easily accessible on a touch screen keyboard, and it is not easy 
to go left, eg. typing "[" "[" "]" "]" "left" "left" to position the 
cursor between the brackets, type the link, type "end" to go after the 
brackets.

I looked at different text markup engines like Textile, Markdown, 
txt2tags, reStructured text, Creole and the only one that appears simple 
enough is the Textile-style link:

   "Link text":PageName or
   "Link text":http://www.example.org

However this markup is redundant when a link text is the same as a page 
name, eg.

   "Telephones":Telephones

and, I have observed that many users will first enter the link address, 
then the link text, and for left-to-right languages this markup above 
means that the user has to reposition the cursor before the link in 
order to type the link text (and on a touch screen this is not as easy 
as with a hardware keyboard and mouse).

I have also looked at our Cookbook:AtLinks recipe which I took as 
inspiration for a simple link markup:

   http://www.pmwiki.org/wiki/Cookbook/AtLinks

It only handles internal links like this:

   @HomePage
   @"HomePage | Link text"


So, my current best idea for a link markup would be:

   @PageName
   @PageName "Link text"

@HomePage would link to Group.HomePage and would display the 
"{$Titlespaced}" text, that is, when a page has a title, it will be 
shown, otherwise the "spaced" name, eg "Home Page".

The "@" prefix implies a direction or a location, so I feel it may be 
easy to learn for new authors when linking to other pages. It is also 
easy to type.

External links (http:// optional):
   http://www.example.org/
   www.example.org
   http://www.example.org "link text"

no need to escape ( and ) into %28 and %29:
   https://en.wikipedia.org/wiki/Colon_(punctuation)

E-mail links, "mailto:" optional:
   user at example.org "optional link text"
   mailto:user at example.org

Attached files:
   Attach:uploaded-file.ext
   Attach:uploaded-file.ext "link text"

   Attach:picture.jpg             (embed a picture)
   Attach:picture.jpg "link text" (link to a picture)

   +uploaded-file.ext
   +uploaded-file.ext "link text"
   +picture.jpg

While "Attach:" is easy to understand and type, it is in the English 
language so it will not be that easy for people from different cultures, 
that's why I wonder if the "plus" prefix can define an attached file?

Or if we can support a translated "Attach:" prefix like they do in 
Wikipedia, for example "Fichier:" in French and "Файл:" in Bulgarian?

Additionally, I'd like to prevent accidental cross-group linking as this 
is a frequent mistake on every young wiki community I've reviewed. So 
I'd like, for the new editor module, have these links:

   @Page/Name.in.the,same/group links to [[PageNameInTheSameGroup]]
   @We.are.open:24/7            links to [[WeAreOpen247]]

   @OtherGroup::PageName        links to [[OtherGroup/PageName]]

Note, 2 colons separate a group from a page.

I am not entirely comfortable with these propositions, that's why I ask 
for your comments and ideas. Once again, these new markups will not 
remove or disable existing link markups in a wiki, either from the core 
or from a local customization. They will only apply to the content 
created in the new structured page text editor module.

Additionally, I think the '''bold''' and ''italic'' inline markups are 
easy enough to type and can be included. The apostrophe key is more 
easily accessible than for example the "*" asterisk key used in some 
markup languages for *bold text*.

Do you think any other inline markups could be included? For example, 
the module will not support %wikistyle bgcolor=orange apply=block% ... 
%% markups because they are somewhat large and new authors can get 
overwhelmed by such complex code. And advanced users are able to write 
in the regular PmWiki text editor.

Also, the new editor will only allow limited styling and organizing, 
unlike a full WYSIWYG editor. This is simpler to implement, use and 
maintain, but most importantly, different pages will look consistently 
similar which wouldn't be the case if everyone was allowed to use any 
font, color, style and size of any word they type.

Put yourselves in the place of newcomer authors who know how to use an 
office suite (but rarely type links), and a social media website or a 
mobile phone text message, where all typing fields are tiny regular 
textareas (non-WYSIWYG), and they do fine.

So in that spirit, can we find any simple link markups, and are there 
any other inline markups that are worth including?

Looking forward to your thoughts.

Petko

-- 
Change log     :  http://www.pmwiki.org/wiki/PmWiki/ChangeLog
Release notes  :  http://www.pmwiki.org/wiki/PmWiki/ReleaseNotes
If you upgrade :  http://www.pmwiki.org/wiki/PmWiki/Upgrades