Changes between Version 4 and Version 5 of WikiFormatting


Ignore:
Timestamp:
Nov 12, 2021, 11:33:20 AM (3 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiFormatting

    v4 v5  
    33[[TracGuideToc]]
    44
    5 Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and powerful whole.
    6 
    7 Trac has a built in small and powerful wiki rendering engine. This wiki engine implements an ever growing subset of the commands from other popular Wikis, especially [http://moinmo.in/ MoinMoin] and [trac:WikiCreole].
    8 
    9 This page will give you an in-depth explanation of the wiki markup available anywhere WikiFormatting is allowed.
    10 
    11 The sections below provide an overview for the most common syntax, each link in the ''Category'' column will lead you to the more detailed explanation later in this page.
    12 
    13 A few other wiki pages present the advanced features of the Trac wiki markup in more depth:
    14  - TracLinks covers all the possible ways to refer precisely to any Trac resource or parts thereof
    15  - WikiPageNames covers the various names a wiki page can take, CamelCase or not
    16  - WikiMacros lists the macros available for generating dynamic content
    17  - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways
    18  - [trac:wiki:TracDev/Proposals/AdvancedWikiOperations AdvancedWikiOperations] provides some operations in uncommon or administrative scenarios
     5Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and unified whole.
     6
     7Trac has a powerful wiki rendering engine that implements a subset of the commands from other popular Wikis, such as [http://moinmo.in/ MoinMoin] and [trac:WikiCreole].
     8
     9The sections below provide an overview for the most common syntax, each link in the ''Category'' column leads you to the more detailed explanation later in this page.
     10
     11The following wiki pages present the advanced features of the Trac wiki markup in more depth:
     12 - TracLinks covers all the possible ways to refer to any Trac resource or parts thereof.
     13 - WikiPageNames covers the various names a wiki page can take, whether in CamelCase or not.
     14 - WikiMacros lists the macros available for generating dynamic content.
     15 - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways.
     16 - [trac:wiki:TracDev/Proposals/AdvancedWikiOperations AdvancedWikiOperations] provides some operations in uncommon or administrative scenarios.
    1917
    2018== Common wiki markup
    … …  
    2725|| `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \
    2826|| '''bold''', ''italic'', '''''Wikipedia style''''' ||
     27|| `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
     28|| **bold**, //italic//, **//!WikiCreole style//** ||
    2929|| {{{`monospaced (''other markup ignored'')`}}} || \
    3030|| `monospaced (''other markup ignored'')` ||
    31 || `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
    32 || **bold**, //italic//, **//!WikiCreole style//** ||
    3331|-----------------------------------------------------------
    3432||= [#Headings Headings] =||\
    3533{{{#!td
    3634 {{{
    37  == Level 2 ==
     35 == Level 2
    3836 === Level 3 ^([#hn note])^
    3937 }}}
    4038}}}
    4139{{{#!td style="padding-left: 2em"
    42 == Level 2 ==
     40== Level 2
    4341=== Level 3 ^([#hn note])^
    4442}}}
    … …  
    6361{{{#!td
    6462 {{{
    65  * bullets list
     63 * bullet list
    6664   on multiple lines
    6765   1. nested list
    … …  
    7169}}}
    7270{{{#!td
    73 * bullets list
     71* bullet list
    7472  on multiple lines
    7573  1. nested list
    … …  
    9694 {{{
    9795 {{{
    98  multiple lines, ''no wiki''
     96 multiple lines, ''no wiki'',
    9997       white space respected
    10098 }}}
    … …  
    103101{{{#!td
    104102 {{{
    105  multiple lines, ''no wiki''
     103 multiple lines, ''no wiki'',
    106104       white space respected
    107105 }}}
    … …  
    159157|| `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\
    160158|| #1 (ticket), [1] (changeset), {1} (report) ||
    161 || `ticket:1, ticket:1#comment:1` ||\
    162 || ticket:1, ticket:1#comment:1 ||
     159|| `ticket:1, ticket:1#comment:1, comment:1:ticket:1` ||\
     160|| ticket:1, ticket:1#comment:1, comment:1:ticket:1 ||
    163161|| `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\
    164162|| Ticket [ticket:1], [ticket:1 ticket one] ||
    … …  
    195193{{{#!td
    196194 {{{
    197  {{{
    198  #!div style="font-size: 80%"
     195 {{{#!div style="font-size: 80%"
    199196 Code highlighting:
    200197   {{{#!python
    … …  
    205202}}}
    206203{{{#!td style="padding-left: 2em"
    207  {{{
    208  #!div style="font-size: 80%"
     204 {{{#!div style="font-size: 80%"
    209205 Code highlighting:
    210206   {{{#!python
    … …  
    222218 }}}
    223219}}}
    224 {{{#!td style="padding-left: 2em"
    225  {{{#!comment
    226  Note to Editors: ...
    227  }}}
    228 }}}
     220||  ''(comment is shown in edit mode only)''  ||
    229221|-----------------------------------------------------------
    230222||= [#Miscellaneous Miscellaneous] =||\
    … …  
    285277Notes:
    286278 * `{{{...}}}` and {{{`...`}}} commands not only select a monospace font, but also treat their content as verbatim text, meaning that no further wiki processing is done on this text.
    287  * {{{ ! }}} tells wiki parser to not take the following characters as wiki format, so pay attention to put a space after !, e.g. when ending bold.
     279 * {{{ ! }}} tells wiki parser to not take the following characters as wiki format, so pay attention to put a space after `!`, e.g. when ending bold.
    288280 * all the font styles marks have to be used in opening/closing pairs,
    289    and they must nest properly (in particular, an `''` italic can't be paired
    290    with a `//` one, and `'''` can't be paired with `**`)
     281   and they must nest properly; in particular, an `''` italic can't be paired
     282   with a `//` one, and `'''` can't be paired with `**`.
    291283
    292284== Headings
    293285
    294 You can create heading by starting a line with one up to six ''equal'' characters ("=") followed by a single space and the headline text.
     286You can create a heading by starting a line with one up to six ''equal'' characters (`=`) followed by a single space and the headline text.
    295287
    296288[=#hn]
    297 The headline text can be followed by the same number of "=" characters, but this is no longer mandatory.
     289The headline text can be followed by the same number of `=` characters, but this is not mandatory. That is, `=== Section3 ===` is identical to `=== Section3`.
    298290
    299291Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.
    … …  
    352344The wiki supports both ordered/numbered and unordered lists.
    353345
    354 Example:
    355346||= Wiki Markup =||= Display =||
    356347{{{#!td
    … …  
    468459== Discussion Citations
    469460
    470 To delineate a citation in an ongoing discussion thread, such as the ticket comment area, e-mail-like citation marks (">", ">>", etc.) may be used. 
     461To delineate a citation in an ongoing discussion thread, such as the ticket comment area, email-like citation marks (`>`, `>>`, etc.) may be used. 
    471462
    472463||= Wiki Markup =||= Display =||
    … …  
    489480=== Simple Tables
    490481
    491 Simple tables can be created like this:
     482Simple tables can be created:
    492483||= Wiki Markup =||= Display =||
    493484{{{#!td
    … …  
    502493}}}
    503494
    504 Cell headings can be specified by wrapping the content in a pair of '=' characters.
    505 Note that the '=' characters have to stick to the cell separators, like this:
     495Cell headings can be specified by wrapping the content in a pair of `=` characters.
     496Note that the `=` characters have to stick to the cell separators:
    506497||= Wiki Markup =||= Display =||
    507498{{{#!td
    … …  
    518509}}}
    519510
    520 Finally, specifying an empty cell means that the next non empty cell will span the empty cells. For example:
     511Finally, specifying an empty cell means that the next non empty cell will span the empty cells:
    521512||= Wiki Markup =||= Display =||
    522513{{{#!td
    … …  
    535526}}}
    536527
    537 Note that if the content of a cell "sticks" to one side of the cell and only one, then the text will be aligned on that side. Example:
     528Note that if the content of a cell sticks to one side of the cell and only one, then the text will be aligned on that side:
    538529||= Wiki Markup =||= Display =||
    539530{{{#!td
    … …  
    560551}}}
    561552
    562 If contrary to the example above, the cells in your table contain more text, it might be convenient to spread a table row over multiple lines of markup. The `\` character placed at the end of a line after a cell separator tells Trac to not start a new row for the cells on the next line.
     553If contrary to the example above, the cells in your table contain more text, it might be convenient to spread a table row over multiple lines of markup. The `\` character placed at the end of a line after a cell separator tells Trac to not start a new row for the cells on the next line:
    563554
    564555||= Wiki Markup =||
    … …  
    580571=== Complex Tables
    581572
    582 If the possibilities offered by the simple "pipe"-based markup for tables described above are not enough for your needs, you can create more elaborated tables by using [#Processors-example-tables WikiProcessor based tables].
     573If the possibilities offered by the simple pipe-based markup (`||`) for tables described above are not enough for your needs, you can create more elaborate tables by using [#Processors-example-tables WikiProcessor based tables].
    583574
    584575== Links
    585576
    586 Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark "!" character, such as {{{!WikiPageLink}}}.
     577Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark (`!`), such as `!WikiPageLink`.
    587578
    588579||= Wiki Markup =||= Display =||
    … …  
    615606}}}
    616607
    617 Following the [trac:WikiCreole] trend, the descriptive title can also be specified by writing the link followed by a pipe ('|') and a title and all this inside //double// square brackets.
     608Following the [trac:WikiCreole] trend, the descriptive title can also be specified by writing the link followed by a pipe (`|`) and a title and all this inside //double// square brackets.
    618609
    619610{{{#!td
    … …  
    671662== Setting Anchors
    672663
    673 An anchor, or more correctly speaking, an [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.2.1 anchor name] can be added explicitly at any place in the Wiki page, in order to uniquely identify a position in the document:
     664An anchor, or more correctly speaking, an [http://www.w3.org/TR/REC-html40/struct/links.html#h-12.2.1 anchor name] can be added explicitly at any place in the Wiki page, to uniquely identify a position in the document:
    674665
    675666{{{
    … …  
    677668}}}
    678669
    679 This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]. For example:
     670This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]:
    680671{{{
    681672== Long title == #title
    682673}}}
    683674
    684 It's also very close to the syntax for the corresponding link to that anchor:
     675It is also very close to the syntax for the corresponding link to that anchor:
    685676{{{
    686677[#point1]
    … …  
    689680Optionally, a label can be given to the anchor:
    690681{{{
    691 [[=#point1 '''Point 1''']]
     682[=#point1 '''Point 1''']
    692683}}}
    693684
    … …  
    711702}}}
    712703
    713 For more complex anchors (e.g. when a custom title is wanted), one can use the Span macro, e.g. `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`.
     704For more complex anchors (eg when a custom title is wanted), you can use the Span macro: `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`.
    714705
    715706== Escaping Links, WikiPageNames and other Markup == #Escaping
    716707
    717 You may avoid making hyperlinks out of TracLinks by preceding an expression with a single "!" (exclamation mark).
     708You may avoid making hyperlinks out of TracLinks by preceding an expression with a single exclamation mark (`!`).
    718709
    719710||= Wiki Markup =||= Display =||
    … …  
    766757== Macros
    767758
    768 Macros are ''custom functions'' to insert dynamic content in a page.
     759Macros are ''custom functions'' that insert dynamic content in a page.
    769760
    770761||= Wiki Markup =||= Display =||
    … …  
    780771See WikiMacros for more information, and a list of installed macros.
    781772
    782 The detailed help for a specific macro can also be obtained more directly by appending a "?" to the macro name.
     773The detailed help for a specific macro can also be obtained more directly by appending a `?` to the macro name.
    783774
    784775||= Wiki Markup =||= Display =||
    … …  
    807798{{{#!td style="border: 0px"
    808799  {{{
    809   {{{
    810   #!html
     800  {{{#!html
    811801  <h1 style="text-align: right; color: blue">
    812802   HTML Test
    … …  
    817807{{{#!td valign="top"  style="border: 0px"
    818808
    819 {{{
    820 #!html
     809{{{#!html
    821810<h1 style="text-align: right; color: blue">HTML Test</h1>
    822811}}}
    … …  
    832821{{{#!td style="border: 0px"
    833822  {{{
    834   {{{
    835   #!python
     823  {{{#!python
    836824  class Test:
    837825 
    … …  
    843831  }}}
    844832}}}
    845 {{{
    846 #!td valign="top"  style="border: 0px"
    847 
    848 {{{
    849 #!python
     833{{{#!td valign="top"  style="border: 0px"
     834
     835{{{#!python
    850836class Test:
    851837    def __init__(self):
    … …  
    894880  }}}
    895881}}}
    896 {{{
    897 #!td  valign="top"  style="border: 0px"
     882{{{#!td  valign="top"  style="border: 0px"
    898883
    899884  {{{#!th rowspan=4 align=justify
    … …  
    937922  {{{
    938923  Nothing to
    939   {{{
    940   #!comment
     924  {{{#!comment
    941925  Your comment for editors here
    942926  }}}
    943   see ;-)
     927  see.
    944928  }}}
    945929}}}
    946930{{{#!td
    947931  Nothing to
    948   {{{
    949   #!comment
     932  {{{#!comment
    950933  Your comment for editors here
    951934  }}}
    952   see ;-)
     935  see.
    953936}}}
    954937
    955938== Miscellaneous
    956939
    957 An horizontal line can be used to separated different parts of your page:
    958 
    959 ||= Wiki Markup =||= Display =||
    960 {{{#!td
     940||= Wiki Markup =||= Display =||
     941{{{#!td
     942  Horizontal line:
    961943  {{{
    962944  Four or more dashes will be replaced
    963   by an horizontal line (<HR>)
     945  by a horizontal line (<HR>)
    964946  ----
    965947  See?
    … …  
    968950{{{#!td
    969951Four or more dashes will be replaced
    970 by an horizontal line (<HR>)
     952by a horizontal line (<HR>)
    971953----
    972954See?
    … …  
    974956|----------------------------------
    975957{{{#!td
    976   {{{
    977   "macro" style [[br]] line break
    978   }}}
    979 }}}
    980 {{{#!td
    981 "macro" style [[br]] line break
     958  Two examples of line breaks:
     959  {{{
     960  "macro" style [[BR]] line break
     961  }}}
     962  or:
     963  {{{
     964  !WikiCreole style \\ line\\break
     965  }}}
     966}}}
     967{{{#!td
     968"macro" style [[BR]] line break
     969
     970!WikiCreole style \\ line\\break
    982971}}}
    983972|----------------------------------
    984 {{{#!td
    985   {{{
    986   !WikiCreole style \\ line\\break
    987   }}}
    988 }}}
    989 {{{#!td
    990 !WikiCreole style \\ line\\break
    991 }}}