Opened 10 years ago

Last modified 4 months ago

#645 new enhancement

link documentation to new GUI developments

Reported by: timmie Owned by: grass-dev@…
Priority: minor Milestone: 7.6.2
Component: Docs Version: svn-trunk
Keywords: wxGUI, toolboxes, menu Cc:
CPU: All Platform: All

Description

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

Change History (23)

comment:1 Changed 10 years ago by hamish

Type: defectenhancement

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

comment:2 Changed 9 years ago 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?

comment:3 in reply to:  2 Changed 9 years ago by 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

comment:4 Changed 7 years ago by neteler

Component: DocswxGUI
Keywords: documentation added
Milestone: 6.4.07.0.0
Version: svn-develbranch6svn-trunk

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

comment:5 Changed 7 years ago 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

comment:6 Changed 5 years ago by wenzeslaus

Component: wxGUIDocs
Keywords: wxGUI toolboxes menu added; documentation removed
Priority: normalminor

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.

comment:7 Changed 5 years ago by 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

comment:8 Changed 5 years ago by 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

comment:9 Changed 5 years ago by timmie

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

comment:10 Changed 5 years ago 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).

comment:11 Changed 5 years ago 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.

comment:12 in reply to:  11 ; Changed 5 years ago by 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

comment:13 in reply to:  12 Changed 5 years ago 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?

comment:14 Changed 3 years ago by martinl

Milestone: 7.0.07.0.5

comment:15 Changed 3 years ago by martinl

Ping, what to do which this ticket?

comment:16 in reply to:  15 Changed 3 years ago by wenzeslaus

Implement one or more from:

  • Single page HTML version of the module tree from the Modules tab in GUI
  • 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

comment:17 Changed 3 years ago by wenzeslaus

Milestone: 7.0.57.3.0

comment:18 Changed 3 years ago by martinl

Milestone: 7.3.07.4.0

Milestone renamed

comment:19 Changed 18 months ago by neteler

Milestone: 7.4.07.4.1

Ticket retargeted after milestone closed

comment:20 Changed 13 months ago by neteler

Milestone: 7.4.17.4.2

comment:21 Changed 10 months ago by martinl

Milestone: 7.4.27.6.0

All enhancement tickets should be assigned to 7.6 milestone.

comment:22 Changed 6 months ago by martinl

Milestone: 7.6.07.6.1

Ticket retargeted after milestone closed

comment:23 Changed 4 months ago by martinl

Milestone: 7.6.17.6.2

Ticket retargeted after milestone closed

Note: See TracTickets for help on using tickets.