Matt <m...@excalamus.com> writes: > Several things in the first paragraph unrelated to your changes stick > out to me. I can't help but make some other remarks. > > "TODO" should probably be "to-do". Every dictionary I looked in has > an entry for "to-do". I think that's the common spelling.
Yet, we consistently use TODO keyword and TODO list across the whole manual. Stackexchange tells that both variants are valid: https://english.stackexchange.com/questions/46217/todo-list-or-to-do-list although "todo" is much less widely used. I do not see much benefit changing "todo list" to "to-do list". Both are clear and both are grammatically correct. > Regarding "markup language," that reads to me like programmer jargon. > What does it mean and why should someone care? Again, who are we > writing to? A markup language is a notation for formatting, > structure, and relationships. I think it would be best to directly > say that. What about "plain text file format"? > I would also soften that Org "relies" on its markup. It doesn't. I > used Org only for lists for a long time. I believe lists to be a > fundamental feature of Org (and hence a great item for the first > sentence). Lists are as simple as dashes. It's hard to say that > dashes before list items is a markup language. Yet, it is. You cannot, for example, use "." as bullets in Org mode. Also, indentation matters in Org lists, while it does not matter in more free-style writing. > Finally, I don't think the file extension is relevant for the first > paragraph. Technically, an extension isn't necessary. A person can > call M-x org-mode or use a file local variable. Worse, I think the > extension contradicts the point that any text editor can view an Org > file. Ever try to open a .org file in Windows? It asks for the > program. Yes, *technically* Windows could open a .org file *if* the > person opening it knew which program to use (or to change the > extension to something like .txt). Again, who are we writing to? If > it's someone who believes file extensions matter, then this would > introduce unnecessary friction. It seems best to avoid it. Better to > do as you've done and say Org is readable (which it is) rather than > specify the extension (which doesn't really matter). I am mostly neutral here, but I can see an argument why mentioning .org extension may be useful - unlike Windows, GitHub does expect .org file extension specifically to render Org mode files. The same goes for non-Emacs editors that support Org markup. For example, Vim/Neovim. -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at <https://orgmode.org/>. Support Org development at <https://liberapay.com/org-mode>, or support my work at <https://liberapay.com/yantar92>