Opened 11 years ago

Closed 10 years ago

#2103 closed task (fixed)

Make SUBMITTING files more accessible

Reported by: wenzeslaus Owned by: grass-dev@…
Priority: normal Milestone: 7.0.0
Component: Docs Version: svn-trunk
Keywords: submitting, addons, doxygen Cc:
CPU: Unspecified Platform: Unspecified

Description

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:

These might need the same changes too. Maybe also other files might be part of this category:

For some files similar changes were already done:

Change History (3)

comment:1 by wenzeslaus, 11 years ago

To make the list and currently used possibilities complete, here is a link to rfc diretcory which contains all the RFC/PSC documentes:

The documents are in half-Doxygen half-Markdown syntax which is processed by Doxygen and the result is here:

And to make decision about syntax even harder: we are using also Media wiki and Trac wiki/tracker with their specific syntaxes. This was also discuss at grass-dev ​Using "trac" is difficult (​nabble, ​gmane).

comment:2 by wenzeslaus, 11 years ago

When looking at similar files, I completely over looked the whole doc directory:

I would like to have a look at this but I don't know when I will be able to do it, so I encourage others to think about it, too. Moreover, I want to avoid situation when I will explore, for example reStructuredText + Sphinx solution and than will realize that public opinion is to have everything in HTML only.

comment:3 by wenzeslaus, 10 years ago

Resolution: → fixed
Status: new → closed
Note: See TracTickets for help on using tickets.