Comment formatting

From LessWrong
Jump to navigation Jump to search

This page describes some of the formatting options while commenting on Less Wrong. For a complete description, see the official Markdown syntax page, but note that Less Wrong comments use a subset of Markdown, with the main difference being that you can't use inline HTML. Here are two sandboxes you can use to experiment.

(For the Wiki formatting rules, see Help:Formatting at MediaWiki and Help:Style_Guide#Formatting.)

Basic

  • *italics* gives italics
  • **bold** gives bold
  • [Less Wrong](http://www.lesswrong.com) gives Less Wrong

To start a new paragraph, use a blank line (that is, two line breaks in a row). A single line break is ignored.

Bulleted lists are like this:

* item 1

* item 2

* item 3

Numbered lists are like this:

1. item 1

2. item 2

3. item 3

Numbered lists are automatically renumbered so their numbers start from one and are consecutive. If you don't want this, precede the dot after the number with a backslash.

Quoted text is prefaced with '>':

> quoted text

Putting two extra spaces at the end of a line allows starting a new line without starting a new paragraph (spaces are represented below by '_' characters):

line 1__
next line is directly below

Escaping special symbols

Special symbols, such as closing brackets or stars, may interfere with Markdown syntax. These symbols need to be escaped, that is, preceded by the escape character backslash '\'.

For example, linking to the wikipedia article Bias (statistics) with the code

[bias](https://en.wikipedia.org/wiki/Bias_(statistics))

will result in incorrect rendering. This can be fixed by placing a backslash '\' before the closing parenthesis in the URL:

[bias](https://en.wikipedia.org/wiki/Bias_(statistics\))

Below is the list of all characters that may need to be escaped:

\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark

Preformatted blocks

To make a paragraph where your indentation is preserved and no characters are treated specially, precede each line with (at least) four spaces. This is commonly used for computer program source code.

Embedding images

The following code embeds the Less Wrong logo:

![](http://lesswrong.com/static/logo_trans.png)

Using LaTeX to render mathematics

LaTeX (pronounced lay-tek) is a popular interface for writing technical documents, in part because of its elegant syntax for recording mathematical equations. It's possible to use LaTeX for rendering formulas in Less Wrong comments.

Let's say, you need to render this formula: Latex example.png

First, you need to construct LaTeX code representing the formula. This can be done either by hand (Wikimedia has a guide), or using an online editor (for example, CodeCogs, mathURL). LaTeX code for the formula is as follows:

\int_a^b\frac{1}{\sqrt{x}}dx

After LaTeX code is prepared, it needs to be converted into Less Wrong comment syntax using this app or by manually escaping special symbols (see below). The resulting code for inserting in your Less Wrong comment is as follows:

![](https://www.codecogs.com/png.latex?\int_a^b\frac{1}{\sqrt{x}}dx)

Links

  • Wikibooks:LaTeX/Mathematics - Online reference for LaTeX syntax. You can also use this nifty webapp that allows you to draw the symbol you're looking for.
  • CodeCogs, mathURL - Online editors for LaTeX
  • LaTeX to HTML for Less Wrong - Converts LaTeX code to code suitable for posts and comments
  • GmailTeX - If you have Chrome and Gmail, you can install this Chrome extension, open a new message in Gmail, compose a Less Wrong post with math, and then copy and paste into Less Wrong's html post editor. You can make top-level posts this way, but it won't help with putting math in comments.

LaTeX by hand

Markdown syntax, as implemented on Less Wrong, interferes with URLs for automatically generated LaTeX images given by online services (e.g. CodeCogs). LaTeX for LW converter automatically takes care of this. This section describes the sources of interference, in case you are interested in the details.

Watch out for the special symbols in the above section while writing LaTeX code. For example, rendering f(x) using the following code is incorrect:

![](https://www.codecogs.com/png.latex?f(x))

The correct version is this one:

![](https://www.codecogs.com/png.latex?f(x\))

Additionally some characters (such as " " and "^") need to be URI encoded. For example, the URI encoding of " " is "%20".

\Delta t

needs

![](https://www.codecogs.com/png.latex?\\Delta%20t)

Polls

Polls may be conducted by adding some specially formatted text to a comment. Multiple polls can be added to a single comment and may be intermixed with comment text. There are several types of polls available:

Poll Types

Multiple Choice

[poll]{Option 1}{Option 2}{Option n}

Multiple Choice Poll

Multiple Choice Poll Results

Presents a list of options, one for each option listed in {}'s. Results are presented as the number of votes for each option along with a bar chart of votes.

Note: You can see the result of the poll only if you have voted in it. Therefore, if you make a poll only for a part of readers (or multiple separate polls for different parts of readers), consider adding an option "I did not vote" to allow other readers see the poll results.

Number Poll

[poll:number]

Number Poll

Number Poll Results

The number poll asks for a numeric response. The response must be a number, positive or negative, integer or decimal. Results are presented as the mean and median (to three decimal places) of all the responses as well as the total number of responses received.

The following aliases also create number polls:

  • [poll:n]
  • [poll:num]
  • [poll:numeric]
  • [poll:float]
  • [poll:double]

Note: These all create the same type of poll (there is no difference in precision if you specify double over float).

Probability Poll

[poll:probability]

Probability Poll

Probability Poll Results

A probability poll is the same as a number poll but the responses must be within 0 and 1.

The following aliases also create probability polls:

  • [poll:p]
  • [poll:prob]
  • [poll:chance]
  • [poll:likelihood]

Scale Poll

[poll:Start....End]

Scale Poll

Scale Poll Results

The scale solicits responses on a scale. The Start and End may by one or more words, E.g. [poll:Agree....Disagree] or [poll:Strongly Agree....Strongly Disagree]. The number of .'s determines how many options will be presented in the scale. Results are presented as a count of each choice along with a bar chart.

Notes

  • Voting requires a certain amount of karma, currently this is set to 2.
  • Once the poll is submitted the poll syntax in the comment will be change to reference the created poll, E.g. [poll:22], thus it isn't possible to edit a poll once created.
  • Multiple polls can be added to a single comment.
  • Poll data is exportable as CSV via the "Raw poll data" link.
  • Choosing the "Vote anonymously" option influences the raw export.

Link tooltips / alt texts / titles

In Markdown, one can set an additional property of a normal hyperlink (using the []()) syntax, the "tooltip" or "title": when a user moves the mouse over a link, the specified text will display. This can be used as a way of summarizing or annotating the link itself. One might link to a PDF and then include a tooltip like "Warning: PDF!" or include citation data like "'Paper title', by Author" as a way of unobtrusively including important metadata.

(The title can be set in the WYISWYG editor as one of the empty default fields when one makes a hyperlink.)

This Markdown:

[paranoid archiving for Internet links](https://www.gwern.net/Archiving%20URLs "'Archiving URLs', gwern 2013")

will compile to this HTML:

<a href="<https://www.gwern.net/Archiving%20URLs>" rel="nofollow" title="'Archiving URLs', gwern 2013">paranoid archiving for Internet links</a>

Common problems

Strikethrough

While some Markdown implementations support the ability to strike through text using the ~~strikethrough~~ tilde syntax, the LessWrong codebase does not support the ability to write strikethrough in comments. (Although <del> tags are supported in posts; see bug #123.)

To work around this, you can strikethrough an entire post by retracting/withdrawing it (the circle with an line through it button in the lower right-hand corner of a comment box); or to strikethrough only a portion of it, one can replace it with a Unicode equivalent using something like the Unicode strikethrough text tool.

Underscores

Both asterisks and underscores can be used for italics (and bold). This applies even to underscores in the middle of a word, so you often need to backslash-escape them.

This

Eliezer_Yudkowsky responded to that comment by Wei_Dai.

will be rendered like

EliezerYudkowsky responded to that comment by WeiDai.

To fix it, use

Eliezer\_Yudkowsky responded to that comment by Wei\_Dai.

Links

Links must start with "http://" (or some other URI scheme).

Wrong:

[an example](example.com/index.html)

Right:

[an example](http://example.com/index.html)

There can be no space between the closing square bracket and the opening parenthesis in a link.

Wrong:

[an example] (http://example.com/index.html)

Right:

[an example](http://example.com/index.html)

A link must start with an opening square bracket, and the clickable text comes before the URL.

Wrong:

(an example)[http://example.com/index.html]
[http://example.com/index.html](an example)
(http://example.com/index.html)[an example]

Right:

[an example](http://example.com/index.html)

If a link has a close parenthesis in it, it needs to be backslash-escaped.

Wrong:

[bias](https://en.wikipedia.org/wiki/Bias_(statistics))

Right:

[bias](https://en.wikipedia.org/wiki/Bias_(statistics\))

Lists

Dashes are sometimes used to show the source of a quote. If you do this and use an ASCII hyphen character to represent the dash, and if it's separated from the source of the quote by a space, it will be interpreted as a list bullet:

He uses statistics as a drunkard uses a lamppost: for support, not for illumination.

  • G.K. Chesterton

To prevent this, use two hyphens (with or without a space):

--G.K. Chesterton
-- G.K. Chesterton

or backslash-escape the single hyphen:

\- G.K. Chesterton

Lists must be separate paragraphs (separated from any preceding or succeeding paragraphs by blank lines). If you forget this and do something like the following:

This paragraph should be separated from the list
below by a blank line.
- List item.
- List item.

then no list formatting will be done and the list will be merged with whatever came before or after it:

This paragraph should be separated from the list below by a blank line. - List item. - List item.

If a list item has multiple paragraphs, the second and subsequent paragraphs of that list item must be indented by four spaces.