Opened 6 years ago

Closed 6 years ago

#14015 closed enhancement (fixed)

Convert develop/packages docs to reStructuredText

Reported by: leorize Owned by: waddlesplash
Priority: normal Milestone: Unscheduled
Component: Documentation Version: R1/Development
Keywords: Cc:
Blocked By: Blocking:
Platform: All

Description

The MediaWiki syntax used by the docs have several problems:

  • Unable to have more than one paragraph per list items. This is relied upon by Bootstrapping, and BuildingPackages
  • Hard wrapping can't be done globally as lists end on new line
  • Heavy reliance on HTML tags, a side effect of this is that all HTML symbols has to be escaped

Markdown was considered as an alternative, but:

  • Still rely on HTML tags for tables and ToC (Table of Contents). Github Flavoured Markdown solve tables, but not ToC
  • ToC has to be written by hand
  • -, _ has to be escaped, which renders Markdown unsuitable for the docs, namely Bootstrapping, Migration, HybridBuilds, ...
  • Definition lists can't be converted without losing schematic, used by FileFormat

reStructuredText however, provides:

  • Markdown-like syntax, easy to read and edit
  • No reliance on HTML tags, nor could you use them within the docs
  • ToC generator

The rendered rST version could be found here. It should be comparable to PackageManagement

Change: https://review.haiku-os.org/#/c/98/

Change History (2)

comment:1 by waddlesplash, 6 years ago

Owner: changed from nielx to waddlesplash
Status: newin-progress

comment:2 by waddlesplash, 6 years ago

Resolution: fixed
Status: in-progressclosed

Merged in hrev51832. Thanks!

Note: See TracTickets for help on using tickets.