[GRASS-dev] [GRASS GIS] #645: link documentation to new GUI developments

GDAL · June 13, 2009, 8:17pm

#645: link documentation to new GUI developments
--------------------+-------------------------------------------------------
Reporter: timmie | Owner: grass-dev@lists.osgeo.org
Type: defect | Status: new
Priority: normal | Milestone: 6.4.0
Component: Docs | Version: svn-develbranch6
Keywords: | Platform: All
Cpu: All |
--------------------+-------------------------------------------------------
The new GUI is a BIG improvement of GRASS
However, most manual pages, tutorials and the book itself refer to the
commands.
It would be nice if manual pages would contain a manu pointer.

Please add a section in the html files:

Menuentry:

Raster => Classify -> Unsupervised -> ...

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645>
GRASS GIS <http://grass.osgeo.org>

GDAL · June 13, 2009, 8:33pm

#645: link documentation to new GUI developments
--------------------------+-------------------------------------------------
  Reporter: timmie | Owner: grass-dev@lists.osgeo.org
      Type: enhancement | Status: new
  Priority: normal | Milestone: 6.4.0
Component: Docs | Version: svn-develbranch6
Resolution: | Keywords:
  Platform: All | Cpu: All
--------------------------+-------------------------------------------------
Changes (by hamish):

* type: defect => enhancement

Comment:

Yeah, I had a start at that, but it needs some more refinement. See
find_menu_hierarchy() in module_synopsis.sh:

source:grass/trunk/tools/module_synopsis.sh@#L59

(download PDF version of synopsis here:
http://grass.osgeo.org/wiki/GRASS_Help#Individual_modules)

Hamish

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/645#comment:1>
GRASS GIS <http://grass.osgeo.org>

GDAL · February 15, 2010, 2:54pm

#645: link documentation to new GUI developments
--------------------------+-------------------------------------------------
  Reporter: timmie | Owner: grass-dev@lists.osgeo.org
      Type: enhancement | Status: new
  Priority: normal | Milestone: 6.4.0
Component: Docs | Version: svn-develbranch6
Resolution: | Keywords:
  Platform: All | Cpu: All
--------------------------+-------------------------------------------------
Comment (by timmie):

I saw that there is now an entry in the help menu for that.
Shall we close this?
Or shall we require that all docs in GRASS 7 contain a pointer to the
respecitive menu / sub-menu?

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:2>
GRASS GIS <http://grass.osgeo.org>

GDAL · February 16, 2010, 6:05am

#645: link documentation to new GUI developments
--------------------------+-------------------------------------------------
  Reporter: timmie | Owner: grass-dev@lists.osgeo.org
      Type: enhancement | Status: new
  Priority: normal | Milestone: 6.4.0
Component: Docs | Version: svn-develbranch6
Resolution: | Keywords:
  Platform: All | Cpu: All
--------------------------+-------------------------------------------------
Comment (by hamish):

Replying to [comment:2 timmie]:
> I saw that there is now an entry in the help menu for that.

right, 6.5+: Help->Show menu tree -> Search: [command]

> Or shall we require that all docs in GRASS 7 contain a pointer
> to the respecitive menu / sub-menu?

there is an outstanding wish to include the a->b->c level text from the
HTML version of the module synopsis (see code linked from comment:1)
below the auto-generated Usage text but before the DESCRIPTION section of
each relevant module's help page.
once synopsis is built see $GISBASE/docs/html/module_synopsis.html
and $GISBASE/etc/module_synopsis.txt

We have all the components in place already
("wxpython/gui_modules/menudata.py commands" from a fake_location), I just
am not enough of a Makefile expert to make it work as part of the build
process.

Hamish

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/645#comment:3>
GRASS GIS <http://grass.osgeo.org>

GDAL · August 21, 2012, 5:41pm

#645: link documentation to new GUI developments
---------------------------+------------------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: normal | Milestone: 7.0.0
Component: wxGUI | Version: svn-trunk
Keywords: documentation | Platform: All
Cpu: All |
---------------------------+------------------------------------------------
Changes (by neteler):

  * keywords: => documentation
  * version: svn-develbranch6 => svn-trunk
  * component: Docs => wxGUI
  * milestone: 6.4.0 => 7.0.0

Comment:

I wonder if we could parse "gui/wxpython/xml/menudata.xml" to auto-add
where to find the entry in the menu.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:4>
GRASS GIS <http://grass.osgeo.org>

GDAL · August 21, 2012, 5:52pm

#645: link documentation to new GUI developments
---------------------------+------------------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: normal | Milestone: 7.0.0
Component: wxGUI | Version: svn-trunk
Keywords: documentation | Platform: All
Cpu: All |
---------------------------+------------------------------------------------

Comment(by cmbarton):

While not in the help pages per se (it would be a very long list),
clicking the "search" tab at the bottom of the layer manager gives an
interactive menu hierarchy tree. It has the advantage that when you get to
the level of a specific command and double click it, it runs that menu
option.

Michael

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:5>
GRASS GIS <http://grass.osgeo.org>

GDAL · February 17, 2014, 4:27am

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------
Changes (by wenzeslaus):

  * keywords: documentation => wxGUI, toolboxes, menu
  * priority: normal => minor
  * component: wxGUI => Docs

Comment:

This ticket probably now depends on #2142.

The other thing is that, as mentioned in comment:5, there is a ''Search
modules'' tab in the wxGUI Layer Manager, so you can search for modules
you found in manual or you can even use ''Command console'' tab. So, there
is a workaround. It is anyway new modern approach to finding things in
operating systems and applications in general (searching as opposed to
remember all the menus leading me to the item).

Moreover, it gets more complicated when there are more ways how to access
the module from tree-based structure, currently from menu bar and from the
module tree in ''Search modules'' tab (but some more, more specialized can
be added in the future).

Finally, this improvement may be actually considered as a bug by use cases
when there is no GRASS GUI. Menu way may be considered as unnecessary
(when using no GUI at all) or as highly confusing (when using some other
GUI, e.g. QGIS or gvSIG).

As a result, downgrading the priority by one degree.

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/645#comment:6>
GRASS GIS <http://grass.osgeo.org>

GDAL · February 19, 2014, 7:14pm

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by wenzeslaus):

See also
"[http://grass.osgeo.org/gdp/grassmanuals/grass64_module_list.html module
list]" for GRASS 6.4 (discussed in #1203) with content similar to this:

{{{
General GIS management commands:

g.access: Controls access to the current mapset for other users on the
system.
Config → GRASS working environment → User access
g.copy: Copies available data files in the user's current mapset search
path...
File → Manage maps and volumes → Copy
}}}

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:7>
GRASS GIS <http://grass.osgeo.org>

GDAL · February 21, 2014, 8:29pm

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by wenzeslaus):

Appearently, there was always a need for documentation like this, see
[http://jrshelby.com/grass/tutorial60/cmd-xref.htm GRASS GIS 6.0 Command
Cross-Reference in Bash order]. Sample of the page:

{{{
#!html
<table border=1 cellpadding=5>
<tr>
<td align=center colspan=4>
Database Commands   <a
href="#top">TOP</a>
</td>
</tr>

<tr>
<td align=center>Bash</td>
<td align=center>Help</td>
<td align=center>Description</td>
<td align=center width=50%>GUI(Display Manager)</td>
</tr>

<tr><td>db.columns</td> <td><a
href="http://grass.baylor.edu/grass60/manuals/html60_user/db.columns.html">doc</a></td>
<td>list all columns for a given table.</td> <td>Databases => Database
information => List columns</td> </tr>

<tr><td>db.connect</td> <td><a
href="http://grass.baylor.edu/grass60/manuals/html60_user/db.connect.html">doc</a></td>
<td>Connect to the database through DBMI.</td> <td>Databases => Manage
database => Connect to database</td> </tr>

<tr><td>db.copy</td> <td><a
href="http://grass.baylor.edu/grass60/manuals/html60_user/db.copy.html">doc</a></td>
<td>Copy a table. Either 'from_table' (optionaly with 'where') can be used
or 'select' option, but not 'from_table' and 'select' at the same
time.</td> <td>Databases => Manage database => Copy table</td> </tr>

<tr><td>db.describe</td> <td><a
href="http://grass.baylor.edu/grass60/manuals/html60_user/db.describe.html">doc</a></td>
<td>Describe a table (in detail).</td> <td>Databases => Database
information => Describe table</td> </tr>

</table>
}}}

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/645#comment:8>
GRASS GIS <http://grass.osgeo.org>

GDAL · February 22, 2014, 11:13am

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by timmie):

I fully agree with having the items of comments 7 & 8 included in the main
docs and linked to via index.

--
Ticket URL: <https://trac.osgeo.org/grass/ticket/645#comment:9>
GRASS GIS <http://grass.osgeo.org>

GDAL · March 25, 2014, 6:35pm

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by wenzeslaus):

There are basically two things which can be done:
* main menu, module tree or any other XML tree converted to HTML (#1203,
#2142, ...)
* main menu and/or module tree position in the module manual page
(header?) (#762, this ticket description (#645))

We cannot (safely) implement this right away (because of #2142) but
discussion can start anytime. For me it is not clear what should go where
(e.g., main menu vs module tree vs specific tree vs all available trees).

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:10>
GRASS GIS <http://grass.osgeo.org>

GDAL · March 25, 2014, 8:49pm

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by neteler):

Would it be possible to parse the modules.xml file via a new flag --menu-
description
which would output the related menu entry in HTML code?

Then it could be put together at compile time as already with header and
main HTML help text.

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:11>
GRASS GIS <http://grass.osgeo.org>

GDAL · March 26, 2014, 12:39am

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by hamish):

Replying to [comment:11 neteler]:
> Would it be possible to parse the modules.xml file via a new
> flag --menu-description which would output the related menu
> entry in HTML code?

fwiw, I'm not excited to make that part of the module parser, the GUI
structure being present shouldn't be a prerequisite of successfully
building a module. So it would have to at least fail gracefully. I guess
it needs that anyway because a number of the helper modules aren't
available from the GUI.

> Then it could be put together at compile time as already with
> header and main HTML help text.

Yes, it would be nice to just inject it after the options description but
before the g.module(description).html text as part of tools/mkhtml.py. I'd
suggest to have it export in plain but parsable text, then the html
writing code could replace ' | ' with ' → ' or whatever as needed on
the fly.

note the tools/module_synopsis.sh code needs some help since the wxgui
layout and menudata.py changed and 'python menudata.py commands' no longer
works:

{{{
#### fixme: no longer exists
MDPY="$GISBASE/etc/wxpython/gui_modules/menudata.py"

# python menudata.py commands
# python menudata.py tree
# python menudata.py strings
python "$MDPY" commands | sed -e 's/ | /|/' -e 's/[ -].*|/|/' \
| sort -u > "$TMP.menu_hierarchy"
}}}

what's the replacement script/functionality?

(here it builds up a table of the menu locations for all modules in a
first step, then instead of re-parsing the entire menu tree for each
module, which would be slow for a full build, it just looks up the module
name in the table.)

Hamish

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:12>
GRASS GIS <http://grass.osgeo.org>

GDAL · March 26, 2014, 5:24am

#645: link documentation to new GUI developments
------------------------------------+---------------------------------------
Reporter: timmie | Owner: grass-dev@…
Type: enhancement | Status: new
Priority: minor | Milestone: 7.0.0
Component: Docs | Version: svn-trunk
Keywords: wxGUI, toolboxes, menu | Platform: All
Cpu: All |
------------------------------------+---------------------------------------

Comment(by wenzeslaus):

My points:
  * we don't want to add anything menu-like to parser, I guess
  * module tree is not only GUI menu thing, look at the tree in `Search
modules` tab, shouldn't be this part of documentation?
  * we can have a XML with module tree separated from GUI
  * we can post-process module HTMLs once they are in `doc/html`, so we
will not change compilation of module (we can find and replace some
special comment in HTML by menu position)
  * `doc/man` should not be influenced

My questions:
  * What exactly was and is `menudata.py` functionality?
  * Can we rewrite `module_synopsis.sh` to Python and what is it doing
anyway and when?
  * Do we want menu entry position in module documentation?
  * Do we want module tree position (from `Search modules` tab) in module
documentation?
  * Do we want multiple tree positions in module documentation?
  * Do we want module tree (from `Search modules` tab) and/or menu tree as
a separate HTML page in HTML documentation?

--
Ticket URL: <http://trac.osgeo.org/grass/ticket/645#comment:13>
GRASS GIS <http://grass.osgeo.org>