Regarding Markdown: I don't feel like I contribute here enough to have meaningful vote, but:
Readmes in Markdown are present in almost every GitHub, GitLab project. In particular in almost every Python, Node.js, React/Angular/Vue project. Also quiclky looking at some C projects - https://github.com/lvgl/lvgl/blob/master/README.md - https://github.com/ARMmbed/littlefs/blob/master/README.md - https://github.com/warmcat/libwebsockets/blob/master/README.md `.md` extension stands for Markdown. It seems to be the de-facto standard. > Plain text is the best on cmd line environments (ssh/putty) Markdown is still a plain text. > I would second that: (1) plain text with no embedded tags, and (2) no new tools. No new tools are required. The only difference is that some editors and GitHub will display it in more readable way. It is almost like the previous text format that is already in the repo, it is just standardized and widely adopted. Syntax is non intrusive. It clearly separates code fragments with backticks. Renders headers and lists in a more readable way. Allows for a table, image and clickable link from time to time. It also allows separating code fragments and then it enables syntax-highlighting. This improves readability greatly. The format is actually simpler than the current one. Regarding RST format: It is a similar concept. It just seems to be a little bit more complex to help writing documentation of code in larger projects. I am seeing it for the first time, but I am also happy to help with Adam Feuer effort if you would decide to use this one. What I think would be great, is to pick any of this two standards. I was trying to parse existing documentation how it is now and it is problematic. The conventions are not always followed and fragments of code randomly glue to text when I am trying to retrieve paragraphs from it. My parsing issue is not relevant, but standardization is important. And Markdown is more readable, thanks to support from modern tools like VSCode or GitHub/Lab. While still being readable in Vim through SSH. Am Fr., 17. Juli 2020 um 16:49 Uhr schrieb Matias N. <mat...@imap.cc>: > Markdown is designed to be readable in plain-text. > I think the only thing you could consider a special tag is how links are > handled: > [link text](url) > linking to images is the same, with a prefix "!". > Everything else is actually intuitive from looking at the text itself. > Look here: > https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet > > Regarding using READMEs as the backend for the main NuttX documentation, > as I mentioned this is not the best idea because it would indeed require > adding extra tags (like links to images, etc). READMEs should be used for > technical information to be read when entering a subdirectory. > > On the other hand, Markdown or any other more complete format (like > ReStructuredText) is a very good format for maintaining documentation > outside of the main nuttx repo. In this case, a doc-repo with CI could be > maintained, exactly the same as the nuttx website repo (in fact, it could > be the same one). The website already requires ruby (jekyll) to be built. > > So, in summation: > - I would use Markdown (without unnecessary tags) on the READMEs > - I would start a doc repo (or reuse the website repo) and create a nice > looking documentation (accessible as subdirectory or subdomain of nuttx > website) based on Markdown or any other useful format and some website > generator like readthedocs or whatever works best. > > Best, > Matias > > On Fri, Jul 17, 2020, at 11:38, Alin Jerpelea wrote: > > +1 > > > > Plain text is the best on cmd line environments (ssh/putty) > > > > On Fri, Jul 17, 2020, 16:28 Gregory Nutt <spudan...@gmail.com> wrote: > > > > > > > > > Please make sure the readmes are still easily readable in vim and > > > > other plain text editors. > > > > > > > > Plain text is good. > > > > > > > > underlined plain text interpreted by github is still readable > (markdown?) > > > > > > > > anything that requires writing explicit tag in the readme text files > > > > should be avoided imho. > > > > > > > > > > > > also, anything that requires non-trivial tools for reading is to be > > > > excluded. > > > > > > > > asciidoctor requires ruby > > > > > > > > Not sure that throwing more tools in the mix is even useful... > > > > > > > > > > > > Sebastien > > > I would second that: (1) plain text with no embedded tags, and (2) no > > > new tools. > > > > > >
