Edgewall Software

Version 49 (modified by Mikael Relbe, 12 years ago) ( diff )

added ticket ref

  1. Topics
    1. Tables
    2. Definition lists
    3. Lists
    4. Headings
    5. Enhanced processors
    6. TracLinks
  2. Compatibility with other Wiki Markups
  3. The really advanced stuff…
    1. Transclusion

Trac Wiki Syntax enhancements

Note: all the syntax enhancements that went into 0.12 can be seen in version 25 of this page.

Topics

Tables

  • support WikiCreole single pipe style (#6630)
    If we support single pipe tables, then it would be worth supporting +----... either as a no-op or a row separator (like |----...), in order to handle the following: 
    +--------------------+
|  Boxed  |  Tables  |
+--------------------+
    Note that "natural" spans will be quite difficult to get right… 
        +------------+------------+---------------------------+
    |  Column 1  |  Column 2  | Column 3 & 4 span (Row 1) |
    +------------+------------+------------+--------------+
    |    Column 1 & 2 span    |  Column 3  | - Column 4   |
    +------------+------------+------------+ - Row 2 & 3  |
    |      1     |      2     |      3     | - span       |
    +------------+------------+------------+--------------+
    (​[Doc-SIG] Problems With StructuredText 8. Tables)
  • add |+ MediaWiki style caption or #!caption
  • annotation for specifying vertical alignment (top ||^ and bottom ||.) (ticket:9309#comment:9)
  • annotation for specifying vertical spans (<|2>) 
    ||<|2> 2 rows   ||    row 1 ||
||                    row 2 ||
||<-2> row 3 over 2 columns ||
  • also support MediaWiki style??? (#1424)

Definition lists

  • nesting definition lists (#7721)
  • terms should automatically get an anchor, much like headings (but nice anchors, see #Headings below)

Lists

There are several enhancements that come to mind:

  • 1) style numbered items and o style numbered items (see also #5498)
Wiki Markup Display 
 o  this is a list
 o  that's another list

1) Point 1

2) Point 2

o this is a list o that's another list

1) Point 1

2) Point 2

Note however some valid concerns about o bullets, expressed in ​[Doc-SIG] Problems With StructuredText 5. Bullet List Markup (this is one of the design mails for reStructuredText)

  • support empty lines between items (#1936, #6482 and more specifically #8140)
Wiki Markup Display 
1. start a list

1. continue in the same list

   another paragraph in the //same item//
  1. start a list
  1. continue in the same list

another paragraph in the same item

Note: the above looks OK, but the another paragraph is actually within an indented blockquote…

  • when continuing an item on the next line, one should stay within the item if we don't dedent past the item starter symbol (nearly works, but see #4848)
  • support for WikiCreole-style lists (gains compatibility with e.g. MediaWiki and Textile derived markups)
Wiki Markup Display 
* start a list
** subitem
*** sub-subitem
# ordered list
## numbered subitem
  • start a list

subitem * sub-subitem # ordered list ## numbered subitem

Notes:

  • issue #6482 is at work here, as the tables are not part of their corresponding item
  • slight difficulty for the VerticalHorizontalParsing, need to consider empty lines as potential "no-ops" in some situations.

Headings

The automatic ids generated for headings are not readable. We should replace spaces by hyphens instead of squashing them, at the very least. Compatibility with the old compact style could be achieved by using the name attribute, whereas id would be used for the new, more readable style. This is especially important for languages when titles use sentence-style capitalization, not title-style capitalization (see e.g. ​Section_headings in Wikipedia). See #8645.

Enhanced processors

For div and tables, add some more "standard" classes (we already have "important" for divs and "listing" for tables):

  • see ​MoinMoin:HelpOnAdmonitions
  • ​admonitions and ​sidebars in docutils.
    Note that sidebars could have their own syntax, a bit like citations (> ...): 
    | This will appear in a sidebar:
|  - any content
|    || will || do ... ||
    which should be fully equivalent to: 
    {{{#!sidebar
This will appear in a sidebar:
 - any content
   || will || do ... ||
}}}
  • ​collapsible and collapsed (#9214)
  • sortable (#8949)
  • wiki processors "quick help" {{{#!div? like for macros (idea from Mikael Relbe, #10201)
  • in general, each wiki structural syntax construction could have its corresponding processor (e.g. description, listitem, quote, citation, …)

Alternative forms of linking

  • shorthand for [[Image(<img>)]]: {{<img>}}, see ​MoinMoin:HelpOnLinking; {{...}} will also be used for transclusion
  • shorthand for footnotes? see #9037
    plus a {{{#!footnote processor (with optional parameter name); references could be written as ((1)) or ((name)) and "inline" short footnotes could be written in ((...)).

Link to filenames

In some contexts (changeset comment), it would make sense to have automatic links to source files, leading to the specific changes for that file (#1200). The detection of file names could be inspired from Doxygen:

All words that contain a dot (.) that is not the last character in the word are considered to be file names. If the word is indeed the name of a documented input file, a link will automatically be created to the documentation of that file. ​ Doxygen, Link to files

Compatibility with other Wiki Markups

While achieving universality is likely not possible, there are both many interesting ideas that could be grabbed from other Wiki markups and incompatibilities than could be eased out.

Here are several other markups that are very interesting for us as they also target similar kinds of users that we do:

The really advanced stuff…

Transclusion

The basic idea is that the content of a Wiki page can be reused and displayed in some other places, typically another wiki page which aggregates the content of several other pages.

One typical use case is to transclude a parametric page used as a template (Template: namespace - #3021). In order to be really useful, this implies having wiki variables, and some control structures (at the very least simple conditionals, and ​noinclude/includeonly blocks).

Also, we could have ways to include only parts of a page, by using some kind of selector mechanism (XPath or CSS inspired?) on the WikiDom tree.

Some existing implementations can serve as good starting points ​ParameterizedIncludes in TWiki, ​Template in MediaWiki, ​Embedding and ​Include in MoinMoin and the ​plugin:include of DokuWiki.

Trac could use both the {{<resource>}} syntax and a more explicit Include macro/WikiProcessor. The latter form would allow to pass "complex" parameters for template, e.g. 

{{{#!include page="Template:ReleaseInfo" version="1.0"
 {{{#!param name="description"
 This version is feature complete, mind you.
  - all existing tickets are implemented
  - there are no known (or unknown) bugs
  - there's even no feature left to be implemented, all is there
 }}}
}}}

The Template:ReleaseInfo page would have the following content: 

 Version:: @version|unknown@
 {{{#!if defined="description"
 Description:: @description@
 }}}

Alternatively, the default content of the include processor could be made available to the wiki variables present in the template in a special variable, e.g. "INCLUDE_CONTENT". 

{{{#!include page="Template:ReleaseInfo2" version="1.0"
 This version is feature complete, mind you.
  - all existing tickets are implemented
  - there are no known (or unknown) bugs
  - there's even no feature left to be implemented, all is there
}}}

The Template:ReleaseInfo2 page would have the following content: 

 Version:: @version|unknown@
 Description:: @INCLUDE_CONTENT@

Variable expansion could also be done using a dedicated syntax (e.g. @@, like ​MoinMoin or ​plugin:templater in dokuwiki), the {{{...}}} style of MediaWiki conflicts with our inline verbatim style.

Instead of #!param, we could also use !#define to create a variable that could be used in the document itself, or rather in the current scope.

A define would not only work for defining variables but also for defining in-document templates ("macros"), unifying variables and templates.

The example "Template:ReleaseInfo" above could be inlined: 

{{{#!define name="ReleaseInfo"
 Version:: @version|unknown@
 {{{#!if defined="description"
 Description:: @description@
 }}}
}}}

And would be called: 

{{{#!include name=".#ReleaseInfo" version="2.0" description="not there yet"
}}}

or simpler:

  • [[Include(#ReleaseInfo, version=2.0, description=not there yet)]]
  • {{#ReleaseInfo|version=2.0|description=not there yet}} (​MediaWiki:Help:Template)

Note that .#abc and #abc are targeting the same node. XXX Maybe even only use abc here?

"Define" could also be used for much small repetitive text, like repetitive URLs, when one doesn't want to define an InterWiki prefix for it, e.g.

  • [[Define(issue=[http://bugs.python.org/issue@1@ Issue @1@])]] and [[Include(issue, 1234)]]
  • {{issue=[http://bugs.python.org/issue@1@ Issue @1@])]] and {{issue|1234}}
  • @issue=[http://bugs.python.org/issue{{1}} Issue {{1}}]@ and @issue|1234@

In summary, we would have the following constructions:

Define Include

Dedicated Wiki Syntax

@<name>=value@ ? @<name>@ or @<name>|default@
{{<name>=value}} ? {{<name>}} or {{<name>|p1|p=val}}
Macro [[Define(<name>=<content>)]] [[Include(<name>)]]
WikiProcessor 
{{{#!define name="<name>" p="default"
...
}}}

{{{#!include name="<name>" p="value"
...
}}}

Defines should of course be able to contain anything, including other transclusions. Includes can contain defines, as a way to pass complex input parameters which can also contain anything, including other transclusions.

A technical difficulty with the short form for transclusion {{...}} is the need to handle the nesting of {{...}} pairs, to allow for multiple level of expansion, like shown in ​advanced templates in MediaWiki. One level can easily be taken care of by using both the {{...}} and @...@ styles.

The <name> parameter given to includes should itself be subject to expansion , and if this corresponds to an unbound variable, the inclusion will be dynamic.

Recursion should be detected (trying to include <name> when <name> is already in the stack of includes) and prevented (as if <name> was missing, i.e. replaced by nothing or the given default value).

Finally, the transclusion should not be restricted to Wiki pages, but should ultimately be able to include other Trac resources (e.g. milestone or ticket descriptions, (parts of) files from the repository, etc.)

See also #4468.

Note: See TracWiki for help on using the wiki.