Make SUBMITTING files more accessible
|Reported by:||wenzeslaus||Owned by:|
|Keywords:||submitting, addons, doxygen||Cc:|
I think that people are not reading any of SUBMITTING files and the reason is that they are not available online as HTML or as a part of documentation. The fact that people don't read the documentation, makes this ticket some kind of critical.
Currently SUBMITTING files are just plain text files in source code. Online availability is only Trac file view which displays them again as plain text file. They are available offline when you download source codes but not everybody is used to look at the traditional files in the source root directory such as SUBMITTING. The same applies to main source code and to addons.
There are two highly connected sub-tickets: syntax and publishing.
Files can become part of the main web site, part of Doxygen documentation (or potentially other programming documentation) or be stand alone (web) pages.
I can see only three possibilities in the syntax. Complete HTML, HTML part (same as manual pages), Markdown, reStructuredText.
Complete HTML is easy for publishing. HTML part can be integrated with Doxygen or processed using GRASS manual tools. Markdown can be integrated with Doxygen or processed using some 3rd party tools. reStructuredText cannot be integrated with anything which is in GRASS but it is a Python (almost) standard and it can by integrated with potential Sphinx documentation or processed using 3rd party tools just as Markdown would be.
If I understand correctly (but somebody might want to check this), HTML, Markdown and reStructuredText can be rendered by Trac into HTML page just by setting the right properties, so this would take care of online publishing.
Markdown and reStructuredText are close to the current plain text syntax (there are some headings and bullet list already) and of course, there is the advantage of these formats that they look nice by themselves.
I was not diving deeply into various possibilities, I think we need to at least partially agree on approximate directions first.
Note that there are also some other files similar in way that they a just plain text files in the source code:
- source:grass/trunk/TODO (last change 5 year ago)
These might need the same changes too. Maybe also other files might be part of this category:
- source:grass/trunk/CHANGES (last change 8 year ago)
For some files similar changes were already done: