link documentation to new GUI developments

[timmie]

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

[hamish]

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

[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?

[hamish]

Replying to 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

[neteler]

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

[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

[wenzeslaus]

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.

[wenzeslaus]

See also "​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

[wenzeslaus]

Appearently, there was always a need for documentation like this, see ​GRASS GIS 6.0 Command Cross-Reference in Bash order. Sample of the page:

Database Commands   TOP
Bash	Help	Description	GUI(Display Manager)
db.columns	doc	list all columns for a given table.	Databases => Database information => List columns
db.connect	doc	Connect to the database through DBMI.	Databases => Manage database => Connect to database
db.copy	doc	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.	Databases => Manage database => Copy table
db.describe	doc	Describe a table (in detail).	Databases => Database information => Describe table

[timmie]

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

[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).

[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.

[hamish]

Replying to 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

[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?

[martinl]

Ping, what to do which this ticket?

[wenzeslaus]

Implement one or more from:

• Single page HTML version of the module tree from the Modules tab in GUI
  • for browsing the modules
  • This should be something like source:grass/trunk/gui/wxpython/xml/toolboxes.xml​ in HTMl
  • likely requires #2142
• Multiple pages HTML version of the module tree from the Modules tab in GUI
  • same as above but can be also combined with back-links from individual modules (last item)
  • anchors in the single version may work as well
• Full list of modules with their position in menu/tree
  • for finding a module by description and then finding the module in menu/tree
  • see comment:7 and comment:8
• Add tree position (or positions) to module documentation, e.g.:

NAME
    r.grow - Generates a raster map layer with contiguous areas grown by one cell.
KEYWORDS
    raster, distance, proximity
    Raster → Raster buffers and distance → Grow by one cell
SYNOPSIS
    r.grow

or

    Raster → Raster buffers and distance → Grow by one cell
NAME
    r.grow - Generates a raster map layer with contiguous areas grown by one cell.
KEYWORDS
    raster, distance, proximity
SYNOPSIS
    r.grow

[martinl]

Milestone renamed

[neteler]

Ticket retargeted after milestone closed

[martinl]

All enhancement tickets should be assigned to 7.6 milestone.

[martinl]

Ticket retargeted after milestone closed

[martinl]

Ticket retargeted after milestone closed