[TSC] conform with markdown rules (GSMA compatibility)

[collivier]

GSMA leverages pandoc to convert all CNTT chapters to docx.
Even if the results seem globally ok, a couple of rules would avoid a few manual processing steps.
It's worth mentioning that it obscures any git diff and then makes GSMA updates very difficult

A first set of rules we do apply as soon as possible:

• not to mix html and markdown which could be considered as fine just in GitHub but it's incorrect from a markdown pov (see anchors and images).
• to remove all manual title numberings (in markdown we do only leverage #, ## or ###)
• to remove all our TOCs (it should be rather part of pandoc processing)
• to avoid complex tables as much as possible (MD only accepts basic tabs)
• to modify images rather than applying CSS on it

[CsatariGergely]

• Images are embedded with html as markdown does not support image scaling. To overcome this we would need to manually scale all images. Are we ready to do that?
• Anchors are used to mask the difference between the auto anchor generation of GitHub and ReadTheDocs. We use these in a very inconsistent way anyways, so I would be happy to see a generic solution.
• If we remove the ToC-s we will need to generate them during the ReadTheDocs build.
• On complex tabs you mean complex tables?

[CsatariGergely]

Pulling in @bfcohen and @scottsteinbrueck as acting doc ptl-s.

[collivier]

Yes my point is to scale the src image rather than leveraging html (somehow we don't have any other choice)
I could have a look if Sphinx is able to generate TOC (I would bet yet without any doubt :))

Yes complex tables :) fixing the issue messages...

[collivier]

I think we would have to remove all br, li, etc. used in cells too (see RA2) => to compact in a single line?.

[gkunz]

Pulling in @bfcohen and @scottsteinbrueck as acting doc ptl-s.

Adding @ss8171 Scot Steele

[tomkivlin]

I could have a look if Sphinx is able to generate TOC (I would bet yet without any doubt :))

Yes, it can but how it looks depends on the theme - we use Sphinx with a Material for Sphinx theme in VF and the ToC appears in a pane on the right rather than at the top of each page.

[collivier]

I would consider the theme issue as minor compared to the current numbering which is manual and even false in RC1.
And pandoc adds its own for each title.

[collivier]

+ funny thread before weekend.
markdown format seems more what we need (alt vs figcaption).

cedric@dev:~$ echo \![img]\(img1.jpg\) | pandoc -f markdown
<figure>
<img src="img1.jpg" alt="" /><figcaption>img</figcaption>
</figure>
cedric@dev:~$ echo \![img]\(img1.jpg\) | pandoc -f gfm
<p><img src="img1.jpg" alt="img" /></p>
cedric@dev:~$ 

[CsatariGergely]

Notes about the topic from the Weekly Technical Meeting are here.