* '''Launchpad entry:''' https://launchpad.net/launchpad/+spec/description-markup
 * '''Created:''' <<Date(2006-05-25T12:05:06Z)>> 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 ==

 * [[https://launchpad.net/bugs/49747|#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."

 * [[https://launchpad.net/bugs/392123|#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?