#2103: Make SUBMITTING files more accessible
-----------------------------------------+----------------------------------
Reporter: wenzeslaus | Owner: grass-dev@…
Type: task | Status: new
Priority: normal | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: submitting, addons, doxygen | Platform: Unspecified
Cpu: Unspecified |
-----------------------------------------+----------------------------------
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/README
* source:grass/trunk/INSTALL
* source:grass/trunk/TODO (last change 5 year ago)
* source:grass-addons/README
* source:grass-addons/SVN_HOWTO.txt
These might need the same changes too. Maybe also other files might be
part of this category:
* source:grass/trunk/AUTHORS
* source:grass/trunk/COPYING
* source:grass/trunk/GPL.TXT
* source:grass/trunk/CHANGES (last change 8 year ago)
For some files similar changes were already done:
* source:grass/trunk/REQUIREMENTS.html
* source:grass/trunk/translators.csv
* source:grass-addons/contributors.csv
--
Ticket URL: <http://trac.osgeo.org/grass/ticket/2103>
GRASS GIS <http://grass.osgeo.org>