| 1 |
>>>>> On Mon, 04 Jan 2021, Tim Harder wrote: |
| 2 |
|
| 3 |
> In terms of choice, I'd personally choose reStructuredText since that |
| 4 |
> generally plugs into python easier via docutils/sphinx (currently used |
| 5 |
> for pkgcore's man/html conversion), but am open to discussion of |
| 6 |
> alternatives such as markdown. |
| 7 |
|
| 8 |
About reStructuredText vs Markdown: |
| 9 |
- ReST syntax is more complete and better standardised. |
| 10 |
- Markdown uses HTML as extension language, which is fine when |
| 11 |
converting to HTML but makes conversion to other formats more |
| 12 |
difficult. |
| 13 |
- Trailing whitespace as part of Markdown's syntax is problematic |
| 14 |
(and the current version of app-emacs/ebuild-mode removes it). |
| 15 |
- We already use ReST for some of our documentation, like GLEPs. |
| 16 |
|
| 17 |
Ulrich |
Archives