NOTE: Click here for open/known bugs.
Overview
This wiki uses ExpressionEngine Wiki syntax plus a syntax called “Smartdown” which is a variant (subset of the union) of Markdown, PHP Markdown Extra, and Smartypants.
This page summarizes on one place the key parts of those four links that actually work here, focusing on the common features that will matter to isocpp.org wiki editors.
Normal text
Ordinary text flows into paragraphs automatically. To start a new paragraph, separate it from preceding text with a blank line.
In regular text (not code blocks), the system automatically changes *text bounded by a single asterisk* into italics, **text bounded by two asterisks** into bold, straight quotes (" and ') into curly quotes, dashes (-- and ---) into en- and em-dashes, and three consecutive dots (...) into an ellipsis. For example, this:
Alexander was called "the Great" because of his conquests -- *not* because of his age.
produces this:
Alexander was called “the Great” because of his conquests – not because of his age.
Headings
Lines starting with # marks are headings. The number of # marks sets the heading level. For example, this:
# Heading 1
## Heading 2
### Heading 3
produces this:
Heading 1
Heading 2
Heading 3
We typically start with Heading 3 because Heading 1 is quite large, and Heading 2 is used for the page-heading. Please using Heading 1 or 2 sparingly, and only when special emphasis is really needed.
Links
You’ll often want to link to another wiki page. To do that, use [[page title]] syntax. For example, [[wg21:bjarne stroustrup]] produces this: [url=”https://isocpp.org/wiki/faq/wg21%3Abjarne-stroustrup” title=”wg21:bjarne-stroustrup”]wg21:bjarne stroustrup[/url]. Note: If the page does not exist, you can create it when you click the link.
Want to link to something else? The simplest way is to do it inline… for example, this:
I love [Boost](http://boost.org).
produces this:
I love Boost.
If you want to reference the same URL multiple times, it can be more convenient to do it out of line using a reference tag (tags are not case sensitive)… for example, this:
I love [Boost][1] and [Poco][poco].
[1]: http://boost.org
[POCO]: http://pocoproject.org
produces this:
You can also links to specific parts of page by adding a standard HTML <a name="target"> tag. For example, this:
<a name="test">This is a test target.</a>
generates this:
And you can link to is using <this-page-url>#test.
Code
To mark a code span within a normal text paragraph, surround it with preceding and trailing backticks. Special characters like &, <, and > will be preserved, as will whitespace including newlines. For example, this:
Don't you just love `std::shared_ptr<widget>`?
Note that `v[ i ]` is not bounds-checked, but `v.at( i )` is.
produces this:
Don’t you just love std::shared_ptr<widget>?
Note that v[ i ] is not bounds-checked, but v.at( i ) is.
To write a code paragraph, write a line of four or more tilde characters (~~~~) before and after the code sample. For example, this:
~~~~
// this is code
int add_42( int& i ) {
return i + 42;
}
~~~~
produces this:
// this is code
int add_42( int& i ) {
return i + 42;
}
One last note about code spans in a normal text paragraph: You’ll rarely need backtick (`) characters, but if you do, you need to escape them as follows:
If the code span contains a backtick (
`) character, delimit the code span with double backticks (e.g.,``print("`");``). If the body contains a run of N consecutive backticks, delimit it with N+1 backticks (e.g.,````transmogrify("```");````).If the code span begins or ends with a backtick, add whitespace between the delimiter and that backtick (e.g.,
`` `starts with backtick``,``ends with a backtick` ``).
Lists
For bulleted lists, use indent and a leading + character. For example, this:
+ some item
+ another item
produces this:
- some item
- another item
For numbered lists, use indent and a leading number followed by a period. For example, this:
1. item one
2. item two
produces this:
- item one
- item two
Images
Need a graphic? It’s similar to link syntax, but with a leading ! character. For example, this:
produces this (check out the hover text if you’re on a hover-capable device):
Block quotes
Blockquotes start with > and a space at the beginning of each line. For example, this:
Mark Twain famously said:
> Action speaks louder than words
> but not nearly as often.
produces this:
Mark Twain famously said:
Action speaks louder than words but not nearly as often.
Tables
You want tables? We’ve got tables. For a simple table, this:
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
produces this:
| First Header | Second Header |
|---|---|
| Content Cell | Content Cell |
| Content Cell | Content Cell |
If you wish, you can add a leading and tailing pipe to each line of the table. Use the form that you like. As an illustration, this will give the same result as above:
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
Note: A table needs at least one pipe on each line for PHP Markdown Extra to parse it correctly. This means that the only way to create a one-column table is to add a leading or a tailing pipe, or both of them, to each line.
You can apply span-level formatting to the content of each cell using regular Markdown syntax. For example, this:
| Function name | Description |
| ------------- | ------------------------------ |
| `help()` | Display the help window. |
| `destroy()` | **Destroy your computer!** |
produces this:
| Function name | Description |
|---|---|
help() |
Display the help window. |
destroy() |
Destroy your computer! |
Footnotes
Footnotes work mostly like reference-style links. A footnote is made of two things: a marker in the text that will become a superscript number; a footnote definition that will be placed in a list of footnotes at the end of the document. A footnote that looks like this:
That's some text with a footnote.[^1]
[^1]: And that's the footnote.
produces this:
That’s some text with a footnote.1
Footnote definitions can be found anywhere in the document, but footnotes will always be listed in the order they are linked to in the text. Note that you cannot make two links to the same footnotes: if you try, the second footnote reference will be left as plain text.
Each footnote must have a distinct name. That name will be used to link footnote references to footnote definitions, but has no effect on the numbering of the footnotes. Names can contain any character valid within an id attribute in HTML.
Footnotes can contain block-level elements, which means that you can put multiple paragraphs, lists, blockquotes and so on in a footnote. It works the same as for list items: just indent the following paragraphs by four spaces in the footnote definition. For example, this:
That's some text with a footnote.[^2]
[^2]: And that's the footnote.
That's the second paragraph.
produces this:
That’s some text with a footnote.2
Markdown Meta-chars
Markdown has a number of meta-chars, some of which are common in C++ code. Be careful.
Most of these meta-chars are automatically quoted inside either code-span
(`…`) or a code-block (~~~~…~~~~),
so that’s the best way to handle meta-chars that represent C++ syntax.
For example, &a[i] → &a[i] (since & is a
meta-char) and f<int>() → f<int> is syntactically
like an HTML element), but both of these can be repaired
via `…` or ~~~~…~~~~.
The table provides the rules for when Markdown interprets a meta-char as a meta-char along with recommended workarounds:
FYI the code-block option (~~~~…~~~~) has the effect of taking the
meta-char out of a normal paragraph / table / bullet-list, which may or may
not be acceptable.
Known Bugs and Workarounds
The following are known wiki bugs/quirks we’re working on, and workarounds to use in the meantime.
{if...}
Bug: Markdown carps badly (page is completely blank) if you use the
character-sequence {if...} or &123;if...&125;
anywhere in your Markdown. (Where ‘anywhere’ means in normal text, ###-headers,
`code-spans`, ~~~~code-blocks~~~~; anywhere.)
Note: the ... part means any chars, for example, {if foo}
or {if-foo} or {iffy} or any other sequence
of characters that start with if.
Examples:
Context If you
use thisOr if you
use thisOr if you
use thisThen this
will happenIn normal text {if}{if blah}{iffy blah}page ‘crashes’
(entire page will be blank)In a header ### {if}### {if blah}### {iffy blah}page ‘crashes’
(entire page will be blank)In a `code-span``{if}``{if blah}``{iffy blah}`page ‘crashes’
(entire page will be blank)In a ~~~~code-block~~~~~~~~{if}~~~~~~~~{if blah}~~~~~~~~{iffy blah}~~~~page ‘crashes’
(entire page will be blank)
Workarounds:
When {if...} appears in normal text (neither `code-span` nor ~~~~code-block~~~~):
Do not use
this MarkdownInstead use
this MarkdownResult seen
by readersComments {if...}(if...)(if…) Use parens rather than braces {if...}{ if...}{ if…} Add a space after the open-brace {if...}{if...}{if…} Encode the iasi
When {if...} appears in a `code-span`:
Do not use
this MarkdownInstead use
this MarkdownResult seen
by readersComments `{if...}``(if...)`(if...)Use parens rather than braces `{if...}``{ if...}`{ if...}Add a space after the open-brace `{if...}`<code>{if...}</code>{if...}Encode the iasi
and use an explicit<code>...</code>
When {if...} appears in a ~~~~code-block~~~~:
~~~~ Alternative 1: (if...) // use parens rather than braces Alternative 2: { if...} // add a space after the open brace ~~~~