[GRASS-dev] [GRASS GIS] #2103: Make SUBMITTING files more accessible

[GRASS GIS]

#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>