Intro

Anuket specifications are written in GFM (GitHub flavored Markdown) what is a pretty weak markdown language (e.g.: It is not possible to scale images). These documents have three "output formats":

1. Readthedocs uses recommonmark to convert the documents to rst in compile time. Recommonmark is not supported anymore and should be changed to something else anyways.
2. GitHub "code view". Here GFM is the default format, but GitHub can render rst also without any problem.
3. Some of the documents are converted to word document and published by GSMA. Conversion fomr rst would be less difficult than form md

For these reasons we would like to convert the documents from markdown to rst. This page contains information and status progress for this work.

Issues

There are some issues what we need to solve on top of converting the documents.

• Things to be corrected in markdowns
  • Markdown issues
    • Removal of manual heading numbers
    • Removal of heading numbers from links (replace "[0-9]+\-" with "")
    • Replace raw html to markdown
      • images
      • br-s
      • Image captions ()
      • other <p>-s
      • remove internal references (html anchors)
  • Markdown best praciices
    • remove the ToC-s
  • Things needed for the conversion
    • Add blank lines before lists (like here)
  • Remove the bogometers from the chapters
• After the rst converison
  • Re-align the table line breaks
  • Move the (n)-s to supertext (if possible)

• Generate heading during the build
• fixing of broken intra-document links to GitHub generated anchors. These references/links only work on GitHub, but are broken in the Rtd builds already today
• consistent use of intra-document linking to auto-generated header anchors without including header numbers

Document responsibles