• Launchpad entry: https://launchpad.net/launchpad/+spec/description-markup

• Created: 2006-05-25 by MatthewPaulThomas

• Contributors: MatthewPaulThomas

Summary

Launchpad should support two subsets of MoinMoin markup: a simple subset for use in descriptions of things, and a larger subset for use in specifications.

Rationale

• #49747: Translator groups: allow minimal formatting of summary. "Not being able to add links, newlines or anything is quite limiting, and makes some of our descriptions look quite bad."

• #392123: Allow Markup in PPA Descriptions. "This might make it easier for maintainers to explain things to users."

Use cases

• Descriptions of people, teams, products, projects, distributions, and distribution releases.
• Specifications.

Design

Compare: HelpOnEditing

There should be two markup modes: one for specifications ("advanced"), and one for everything else ("simple"). This is because specifications can expect to have most of a page to themselves, and often need to explain complex ideas using tables and images; these are needed much less by anything else (except maybe bug reports).

Formatting

Compare: HelpOnFormatting

For simple mode:

• ''two consecutive single quotes'' for italics

• `backticks` or {{{three consecutive parentheses}}} on a single line, for inline monospace text

A new line also ends any of these.

For advanced mode, all that plus:

• '''three consecutive single quotes''' for bold

• __two consecutive underscores__ for underlining (e.g. simulating links or form fields)

• `

  three consecutive parentheses,`<<BR>>
   `opening and closing on separate lines

  `, for

   preformatted text

Not supported:

• superscript, subscript
• colorized code displays

Links

Compare: HelpOnLinking

For simple mode:

• auto-linked URLs with protocols apt:, http:, https:, ftp:, nntp:, news:, mailto:, telnet:, and file:, ended by a space, a quote character, or a square bracket

• a "[" character, followed by an URL, any non-newline whitespace, some text, and a "]" or a new line, to link that text to that URL

For advanced mode, all that plus:

• attachment:

Not supported:

• WikiName links

• arbitrary page names
• inline images by suffix

• InterWiki links

• inline: or drawing:

Headings

Compare: HelpOnHeadlines

For advanced mode only:

• From one to six adjacent = characters, the same number at both ends of a single line, for <h2> to <h4> elements

Horizontal rules

Compare: HelpOnRules

Not supported.

Lists and indenting

Compare: HelpOnLists

For advanced mode only:

• Any number of spaces at the start of a line, to indent the line by that level.

• " *" or " -" at the start of a line, for an <li> in a <ul>.

• " 1." (with any number) at the start of a line, for an <li> in an <ol>.

• " a." (with any number) at the start of a line, for an <li> in an <ol type="a">.

• A list item with greater indentation than the previous line starts a new list.
• A line with less indentation than the previous one, where the previous one is a list item, ends the list.

Not supported:

• Definition lists.

Tables

Compare: HelpOnTables

Should be supported for specifications only: All the features described in HelpOnTables.

Variables

Compare: HelpOnPageCreation#variablesubstitution''

Not supported.

Icons

Compare: HelpOnSmileys

Not supported.

Macros

Compare: HelpOnMacros

Not supported.

Processors

Compare: HelpOnProcessors

Not supported.

Processing instructions

Compare: HelpOnProcessingInstructions

Not supported.

Advertising formatting ability

Fields that accept simple-mode formatting should have text underneath describing what formatting you can use:

• Formatting allowed: ''italics'', '''bold''', `monospace`, [URL followed by linked text]

Implementation

Code changes

Schema changes

Each thing with a description may need a flag to indicate whether the description is using the markup or not.

Data migration

The "I am using markup" flag should default to off.

Unresolved issues

• Should we allow lists in simple mode too?