7083eb1a1c 2008-11-20 drh: <h1>Wiki In [./index.wiki | Fossil]</h1> 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: Fossil uses [/wiki_rules | wiki markup] for many things: 9d10726d48 2008-07-29 drh: 9d10726d48 2008-07-29 drh: * Stand-alone wiki pages. 7083eb1a1c 2008-11-20 drh: * Description and comments in [./bugtheory.wiki | bug reports]. 9d10726d48 2008-07-29 drh: * Check-in comments. 7083eb1a1c 2008-11-20 drh: * [./embeddeddoc.wiki | Embedded documentation] files whose 9d10726d48 2008-07-29 drh: name ends in "wiki". 9d10726d48 2008-07-29 drh: 7083eb1a1c 2008-11-20 drh: The [/wiki_rules | formatting rules] for fossil wiki 9d10726d48 2008-07-29 drh: are designed to be simple and intuitive. The idea is that wiki provides 9d10726d48 2008-07-29 drh: paragaph breaks, numbered and bulletted lists, and hyperlinking for 9d10726d48 2008-07-29 drh: simple documents together with a safe subset of HTML for more complex 9d10726d48 2008-07-29 drh: formatting tasks. 9d10726d48 2008-07-29 drh: 7083eb1a1c 2008-11-20 drh: Some commentators feel that the use of HTML is a mistake and that 7083eb1a1c 2008-11-20 drh: fossil should use the markup language of the 7083eb1a1c 2008-11-20 drh: <i>fill-in-your-favorite</i> wiki engine instead. That approach 7083eb1a1c 2008-11-20 drh: was considered but was rejected for the following reasons: 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: 1. There is no standard wiki markup language. Every wiki engine does 7083eb1a1c 2008-11-20 drh: it a little differently. 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: 2. The wiki markup used by fossil, though limited, is common to most 7083eb1a1c 2008-11-20 drh: other wiki engines, is intuitive, and is sufficient for 90% of 7083eb1a1c 2008-11-20 drh: all formatting tasks. 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: 3. Where the fossil wiki markup language is insufficient, HTML is 7083eb1a1c 2008-11-20 drh: used. HTML is a standard language familiar to most programmers so 7083eb1a1c 2008-11-20 drh: there is nothing new to learn. And, though cumbersome, the HTML 6ba52ae761 2009-02-21 drh: does not need to be used very often so is not a burden. 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: 9d10726d48 2008-07-29 drh: <h2>Stand-alone Wiki Pages</h2> 9d10726d48 2008-07-29 drh: 9d10726d48 2008-07-29 drh: Each wiki page has its own revision history which is independent of 904ee40b93 2009-01-23 drh: the sequence of check-ins (check-ins). Wiki pages can branch and merge 904ee40b93 2009-01-23 drh: just like check-ins, though as of this writing (2008-07-29) there is 9d10726d48 2008-07-29 drh: no mechanism in the user interface to support branching and merging. c8893c69ac 2008-10-05 drh: The current implementation of the wiki shows the version of the wiki 4ef19b554a 2008-10-11 drh: page that has the most recent timestamp. 9d10726d48 2008-07-29 drh: 9d10726d48 2008-07-29 drh: In other words, if two users make unrelated changes to the same wiki 6ba52ae761 2009-02-21 drh: page on separate repositories and those repositories are synced, 9d10726d48 2008-07-29 drh: the wiki page will fork. The web interface will display whichever edit 9d10726d48 2008-07-29 drh: was checked in last. The other edit can be found in the history. The 9d10726d48 2008-07-29 drh: file format will support merging the branches back together, but there 9d10726d48 2008-07-29 drh: is no mechanism in the user interface (yet) to perform the merge. 9d10726d48 2008-07-29 drh: 9d10726d48 2008-07-29 drh: Every change to a wiki page is a separate 7083eb1a1c 2008-11-20 drh: [./fileformat.wiki | control artifact] 7083eb1a1c 2008-11-20 drh: of type [./fileformat.wiki#wikichng | "Wiki Page"]. 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: <h2>Embedded Documentation</h2> 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: Files in the source tree that use the ".wiki" suffix can be accessed 7083eb1a1c 2008-11-20 drh: and displayed using special URLs to the fossil server. This allows 7083eb1a1c 2008-11-20 drh: project documentation to be stored in the source tree and accessed 7083eb1a1c 2008-11-20 drh: online. (Details are descripted [./embeddeddoc.wiki | separately].) 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: Some project prefer to store their documentation in wiki. There is nothing 7083eb1a1c 2008-11-20 drh: wrong with that. But other projects prefer to keep documentation as part 7083eb1a1c 2008-11-20 drh: of the source tree, so that it is versioned along with the source tree and 7083eb1a1c 2008-11-20 drh: so that only developers with check-in privileges can change it. 7083eb1a1c 2008-11-20 drh: Embedded documentation serves this latter purpose. Both forms of documentation 7083eb1a1c 2008-11-20 drh: use the exact same wiki markup language. Some projects may choose to 6ba52ae761 2009-02-21 drh: use both forms of documentation at the same time. Because the same 6ba52ae761 2009-02-21 drh: format is used, it is trival to move file from wiki to embedded documentation 6ba52ae761 2009-02-21 drh: or back again as the project evolves. 7083eb1a1c 2008-11-20 drh: 7083eb1a1c 2008-11-20 drh: <h2>Bug-reports and check-in comments</h2> 9d10726d48 2008-07-29 drh: 7083eb1a1c 2008-11-20 drh: The comments on check-ins and the text in the descriptions of bug reports 7083eb1a1c 2008-11-20 drh: both use wiki formatting. Exactly the same set of formatting rules apply. 7083eb1a1c 2008-11-20 drh: There is never a need to learn one formatting language for documentation 7083eb1a1c 2008-11-20 drh: and a different markup for bugs or for check-in comments.
File Annotation