%W is not as weird as it looks at first glance

[ikiwiki.git] / doc / plugins / shortcut / discussion.mdwn

diff --git a/doc/plugins/shortcut/discussion.mdwn b/doc/plugins/shortcut/discussion.mdwn
index 0ecf29537787c4adc634227926d393db441c0528..7f0d58dbe1d52a3eb0a6c62a759a1c12668014f6 100644 (file)
--- a/doc/plugins/shortcut/discussion.mdwn
+++ b/doc/plugins/shortcut/discussion.mdwn
@@ -1,16 +1,49 @@
-I'd like to use a shortcut like \[[gnumach-1-branch ddb/db_expr.h]] to link to
-<http://cvs.savannah.gnu.org/viewvc/gnumach/ddb/db_expr.h?view=log&root=hurd&pathrev=gnumach-1-branch>.
+The plugin depends on [[mdwn]].  If you have
+disabled [[mdwn]], to get [[shortcut]] work, you need
+commit in a shortcuts.ext (ext is `rcs|creole|html|txt|etc`),
+and edit/patch [[shortcut]].
 
-* Dashes are not allowed in shortcut identifiers.  Why?
+Maybe use the `default_pageext` is better than hardcode .mdwn?
 
-* The URL is rewritten to
-    <http://cvs.savannah.gnu.org/viewvc/gnumach/ddb%2Fdb%5Fexpr%2Eh?view=log&root=hurd&pathrev=gnumach-1-branch>,
-    which the remove server doesn't like.  Mind the esacping of [^A-Za-z0-9].
-    Might this be a problem of the web server?
+--[[weakish]]
 
-Also, I'd like to put the shortcut usages into backticks
--- `[[iki shortcuts]]` --
-to have them displayed in the usual backtick-formatting.
-That also doesn't work, but this is an already-reported issue, as far as I know.
+> done, it will use `default_pageext` now --[[Joey]] 
 
---[[tschwinge]]
+---
+
+Instead of modifying the [[basewiki]]'s [[shortcuts]] file for local needs --
+thus copying it at some point and losing continuity with upstream enhancements --
+what about handling a `shortcuts-local.mdwn` or `shortcuts/local.mdwn` (if such
+a file exists in the wiki), and additionally process that one.  Possibily a
+conditional `\[[!inline]]` could be used.  --[[tschwinge]]
+
+----
+
+The page says
+
+> Additionally, %W is replaced with the text encoded just right for Wikipedia
+
+with the implication that this is odd. However, it appears the escapes
+actually mean:
+
+=%s=
+    If every character in the string is in the Latin-1 range, encode each
+    character as a http %xx escape: ö -> %F6. If not,
+    mangle the string: ☃ (U+2603 SNOWMAN) -> %2603 which
+    actually means "&03".
+=%S=
+    Leave the string as-is.
+=%W=
+    Encode the string as UTF-8, then encode each byte of the UTF-8
+    individually as a http %xx escape: ö -> %C3%B6, ☃ (U+2603 SNOWMAN) ->
+    %E2%98%83.
+
+http %xx encoding is defined in terms of input bytes, not input characters,
+so you can't encode arbitrary Unicode into URLs without knowing which
+encoding the destination server is going to use. UTF-8 is what's
+recommended by the [[!wikipedia Internationalized resource identifier]]
+specification, so I suspect %W is right more often than it's wrong...
+
+I wonder whether %s should mean what %W does now, with a new format
+character - maybe %L for Latin-1? - for the version that only works
+for strings that can be encoded losslessly in Latin-1? --[[smcv]]