[Pmwiki-users] markup musings, with missing #7 restored

Patrick R. Michaud pmichaud
Thu May 20 16:42:12 CDT 2004


[Sorry, I got interrupted by a phone call while writing point #7 on url
fragments/anchors, and then sent the message without finishing it.  
The corrected text is here.]

These are just some random thoughts I've had about link markup and
the like over the past couple of weeks -- I'm only posting these to
see what anyone has to say about these ideas, not because I'm planning
to adopt any of them.  So don't panic and assume that I'm about to 
change the PmWiki-world, I'm not there yet.  :-)  And if/when I do 
change the markup, it will only be with a clear, robust upgrade path.

1.  Link markup should be something relatively easy to type and read
    inline with the markup.  The best candidates seem to be [...],
    [[...]], and {{...}}.  

    [...] has advantages of being easier to type and perhaps 
    easier to read, but disadvantages of possibly being
    confused with other existing markup or occuring in normal text.
    It also has the advantage of not significantly conflicting with
    PmWiki existing markup.

    [[...]] has advantages of being able to be clearly identified as
    "link markup".  It has the disadvantage of possibly conflicting
    with existing PmWiki directives and features.  However, this
    could likely be worked around over a series of major releases.

    {{...}} is also clearly link markup, and wouldn't conflict with
    existing PmWiki markup.  However, it's not in common use by
    other wiki engines and may encounter resistance from people
    working in other wiki environments.

    For the rest of this document I'll use both [...] and [[...]]
    to denote link markup just to see side-by-side examples of each
    to help select between them.

2.  Any page target specified inside of link markup should be a
    "free link", i.e., able to contain spaces and selected other
    special characters.  

3.  (Corollary to #2)  If separate link text is to be used instead
    of the target, it has to be delimited from the target by something
    other than a space.  The most common choice seems to be
    the vertical brace:

        [free link | link text]
        [[free link | link text]]

    but nested brackets to separate the two also has merit.

        [[free link] link text]
        [free link [link text]]

    I tend to prefer the | versions because it more clearly appears to
    me that the link text is indeed "replacing" the target text and
    is not somehow "parenthetical".

4.  Character entities should be supported inside of any alternate
    text, if not inside of the target itself (but possibly stripped
    when building the target name).  Thus 

        [PmWiki | Pm"s favorite wiki engine]

5.  Suffix characters immediately following the link should be
    appended to the link, thus "[[document]]ation" would link to
    "Document" but display "documentation" as the link text.

6.  It's useful to be able to suppress part of the target name when
    creating the link text.  Currently PmWiki uses '|' for this, as
    in {{free link|s}}, but another approach would be to use a 
    matched character sequence such as braces or parentheses.  This
    would also allow suppression somewhere other than the end.  
    Possibilities/examples:

        [text {format}] -- links to TextFormat, displays as "text"
        [{text} format] -- links to TextFormat, displays as "format"
        [free link{s}]ing  -- links to FreeLinks, displays as "free linking"
        [free link(s)]ing  -- same but using parens instead of curly braces
        All links should be [free {Links}] -- another example
        [{Meatball:}WikiMarkupStandard] -- displays as "WikiMarkupStandard"
        [{Attach:}my file name{.txt}] -- displays as "my file name"

    (N.B.:  This last example does not preclude the concept that
    InterMap-style links such as "Attach:myfile.txt" could still have 
    "Attach:" automatically suppressed in output to display as "myfile.txt".)

7.  Anchors (link fragments) always belong directly with the target.  This
    becomes easier to swallow since the display of the fragment can be
    suppressed.  Thus:

        [[home page#sec]]           -- HomePage#sec, displays as "home page#sec"
        [[home page{#sec}]]         -- same target, displays as "home page"
        [[home page{#sec}]]s        -- same target, displays as "home pages"
        [[home page#sec | link me]] -- same target, displays as "link me"

8.  Perhaps a good way to implement alternate text (images, acronyms,
    abbreviations) is to simply introduce a new markup for it.  In playing
    around with the above ideas I came up with [(alt text)], which would add
    a alt= or title= attribute to whatever immediately preceeds it.  Thus:

        Attach:filename.jpg[(my photos)] 
        [W3C | Attach:w3c.jpg][(World Wide Web Consortium)]
        HTML[(HyperText Markup Language)]
        [http://www.pmichaud.com/toast][(Strawberry Pop-Tart Blow Torches)]

9.  Reference links (link text automatically numbered as [1], [2], [3]) 
    are not that commonly used, so it's useful to build a special 
    markup for them rather than overloading an existing markup.  A good
    choice may be to simply use '' or '#' as alternate link text:

        [http://www.pmichaud.com/toast|]  
        [http://www.pmichaud.com/toast|#]
      
10. It's worth considering the markup choices being made by other wiki
    engines, if only to make it easy for people to migrate between
    PmWiki and other engines.  The 600-pound gorilla is Wikipedia (MediaWiki),
    which has thousands of authors.  This demonstrates that the Wikipedia
    markup is indeed usable by authors of differing backgrounds.  For
    reference, here are some of MediaWiki's link markups :

        [[free link]]           -- link to "FreeLink" displays as "free link"
        [[free link]]s          -- link to "FreeLink" displays as "free links"
        [[free (link)]]         -- link to "FreeLink" displays as "free"
        [[free link | clickme]] -- link to "FreeLink" displays as "clickme"

    and a choice I *don't* agree with:

        [http://someserver.com/ some server] -- displays as "some server"

    Note the use of single brackets instead of double, and the lack of
    a delimiter to separate the link text from the target.

11. It'd be nice to have "wiki engine emulation" modules that enable the
    use of markup sequences used by other wiki engines, as well as
    "wiki migration" modules that allow people to easily migrate pages
    from other wikis to PmWiki.  Fortunately, PmWiki's design and
    markup language seems to make this a very achievable goal.

All comments, suggestions, and other items greatly appreciated.

Pm



More information about the pmwiki-users mailing list