doc/todo/shortcut_with_different_link_text.mdwn

   1 I'd like the ability to use a shortcut, but declare an explicit link text
   2 rather than using the link text defined on [[/shortcuts]].  For example, if I
   3 create a shortcut `protogit` pointing to files in the xcb/proto.git gitweb
   4 repository, I don't always want to use the path to the file as the link text;
   5 I would like to src/xcb.xsd, but use the link text "XML Schema for the X
   6 Window System protocol".  --[[JoshTriplett]]
   7
   8 > If I understand you correctly, you can use Markdown \[your link text\]\(the path or URL\) . Using your example:
   9 > [XML Schema for the X Window System protocol](src/xcb.xsd)
  10 >
  11 > If I don't understand this, can you give an HTML example? --[[JeremyReed]]
  12
  13 >> The problem is like that in [[bugs/shortcuts_don't_escape_from_Markdown]]. We would like to use
  14 >> the shortcuts plugin but add a descriptive text -- in this case \[[!xcbgit src/xcb.xsd|XML Schema...]]
  15 >> The file src/xcb.xsd could be any url, and the point of shortcuts is that you get to shorten it.
  16 >> --Ethan
  17
  18 >>> Some clarifications:
  19 >>> You can always write something like
  20 >>> `[XML Schema for the X Window System Protocol](http://gitweb.freedesktop.org/?p=xcb/proto.git;a=blob;hb=HEAD;f=src/xcb.xsd)`
  21 >>> to get [XML Schema for the X Window System Protocol](http://gitweb.freedesktop.org/?p=xcb/proto.git;a=blob;hb=HEAD;f=src/xcb.xsd).
  22 >>> However, I want to define a [[plugins/shortcut]] to save the typing.  If I
  23 >>> define something like `protogit` pointing to
  24 >>> `http://gitweb.freedesktop.org/?p=xcb/proto.git;a=blob;hb=HEAD;f=%s`, then
  25 >>> I can write `\[[!protogit src/xcb.xsd]]`; however, I then can't change the
  26 >>> link text to anything other than what the shortcut defines as the link
  27 >>> text. I want to write something like
  28 >>> `\[[XML Schema for the X Window System Protocol|protogit src/xcb.xsd]]`,
  29 >>> just as I would write a wikilink like
  30 >>> `\[[the_shortcuts_on_this_wiki|shortcuts]]` to get
  31 >>> [[the_shortcuts_on_this_wiki|shortcuts]]. (The order you suggest, with the
  32 >>> preprocessor directive first, seems quite confusing since wikilinks work
  33 >>> the other way around.) --[[JoshTriplett]]
  34
  35 > How about [xcbgit XML_Schema|src/xcb.xsd]. That's the same way round
  36 > as a wikilink, if you look at it the right way. The syntax Josh suggests
  37 > is not currently possible in ikiwiki.
  38 >
  39 > However.. [[Short_wikilinks]] has some similar objectives in a way, and
  40 > over there a similar syntax to what Josh proposes was suggested. So maybe
  41 > I should modify how ikiwiki preprocessors work to make it doable.
  42 > Although, I seem to have come up with a clear alternative syntax over
  43 > there. --[[Joey]]
  44
  45 ---
  46
  47 One possible alternative, would be a general `\[[!url ]]` scheme for all kinds of links. As mentioned in [[Short_wikilinks]], I have wanted a way to enter links to the wiki with markdown-style references,
  48 specifying the actual target elsewhere from the text, with just a short reference in the text. To facilitate automatic conversion from earlier (already markdownised) "blog", I finally ended up writing a custom plugin that simply gets the location of wikipage, and use markdown mechanisms:
  49
  50     Here [is][1] a link.
  51
  52       [1]: [[!l a_page_in_the_wiki]]
  53
  54     Obviously [this]([[!l another_page]]) also works, although the syntax is quite cumbersome.
  55
  56 So that the 'l' plugin inserts the location the page there, and markdown does the rest. My plugin currently fails if it can't find the page, as that is sufficient for my needs. Differing colouring for non-existing pages is not doable in a straightforward manner with this approach.
  57
  58 For external links, that is no concern, however. So you could define for each shortcut an alternative directive, that inserts the URL. Perhaps `\[[!url shortcutname params]]` or `\[[@shortcutname params]]` (if the preprocessor supported the @), and this could be extended to local links in an obvious manner: `\[[!url page]]` or `\[[@page]]`. Now, if you could just get rid off the parantheses for markdown, for the short inline links --[[tuomov]] (who'd really rather not have two separate linking mechanisms: ikiwiki's heavy syntax and markdown's lighter one).
  59
  60 ---
  61
  62 I've added code to make the \[[!foo 123]] syntax accept a _desc_
  63 parameter. I've named it like this to signal that it overrides the
  64 _desc_ provided at description time. `%s` is expanded here as well.
  65
  66 [[todo/done]] -- Adeodato Simó
  67