docs: manually created index with images

The generated index of all images is now 'manual gallery'. The graphical index is now manually created list with links to selected parts or, potentially, other manually created indexes.

Images are low res JPGs because the page must load quickly.

Images on page are relative to font size (em), this kind of relative size but not dependent on browser window size. More importantly, the items are in a list rather than a table, so they layout on the wide screens as wide and as one column on narrow displays.


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@66069 15284696-431f-4ddb-bdfa-cd5b030d7da7

doc/README

@@ -0,0 +1,105 @@
+Graphical index images
+======================
+
+General
+-------
+
+Clipped part from grass_structure.png with Locations, Mapsets and data
+types.
+
+Alternative (can be also alternative for display):
+
+g.region n=224940 s=224590 w=638450 e=638840
+
+d.shade shade=elevation_shade color=elevation  # opacity 90%
+d.vect map=firestations color=45:107:168 fill_color=30:144:255 width=2 icon=basic/circle size=15
+d.vect map=schools color=208:208:0 fill_color=yellow width=2 icon=basic/triangle size=15
+d.vect map=hospitals color=136:0:0 fill_color=213:21:21 width=2 icon=basic/box size=15
+
+
+Raster
+------
+
+d.rast.num -a -f map=elevation grid_color=179:179:179 precision=0
+
+
+Vector
+------
+
+g.region n=224940 s=224590 w=638450 e=638840
+
+v.buffer input="streams" layer="-1" output="streams_buffer" distance=20
+
+d.vect map=census color=142:142:0 fill_color=255:255:167 width=2
+d.vect map=streams_buffer color=11:185:11 fill_color=11:185:11 width=1
+d.vect map=streams color=30:144:255 width=4
+
+
+Database
+--------
+
+streams attributes screenshot
+
+DIR="../trunk-commands/doc/"
+for FILE in *.png; do convert $FILE -resize 200x200 $DIR/`basename -s .png $FILE`.jpg; done;
+
+
+Display
+-------
+
+g.region n=226640 s=222860 w=631260 e=637170
+
+d.rast map=elevation_shade
+d.rast map=lakes
+d.vect map=schools color=16:70:123 fill_color=30:144:255 width=1 icon=basic/triangle size=10
+d.vect map=roadsmajor color=255:151:38 width=4
+d.vect map=roadsmajor color=255:172:82 width=2
+
+GUI
+---
+
+* Ubuntu 14.04 with Unity
+* landclass, roadsmajor, elevation
+* query map dialog active
+* Search modules tab active (with open subtrees)
+
+
+Imagery
+-------
+
+# this takes some time, perhaps the region below would be enough
+g.region -p raster=ortho_2001_t792_1m
+i.group group=ortho_group input=ortho_2001_t792_1m
+i.segment group=ortho_group output=ortho_segs_final threshold=0.25 min=10
+
+g.region n=221100 s=219700 w=638616 e=639316 -p
+d.mon start=cairo output=gi_imagery.png width=500 height=500
+d.frame left -c at=0,100,0,50d.rast ortho_2001_t792_1m
+d.rast ortho_2001_t792_1m
+d.frame right -c at=0,100,50,100
+d.rast ortho_segs_final
+d.mon stop=cairo
+
+
+Temporal
+--------
+
+Done in GUI.
+
+g.region raster=landuse
+
+r.mapcalc "a1 = 10"
+r.mapcalc "a2 = 20"
+r.mapcalc "a3 = 30"
+r.mapcalc "a4 = 40"
+
+m.nviz.image elevation_map=a1,a2,a3,a4 mode=fine,fine,fine,fine resolution_fine=1,6,1,1 resolution_coarse=9,9,9,9 shading=gouraud,gouraud,gouraud,gouraud style=surface,surface,surface,surface wire_color=136:136:136,136:136:136,136:136:136,136:136:136 color_map=landuse,landuse,landuse,landuse \
+position=0.03,0.31 height=92 perspective=36 twist=-99 zexag=200.000000 focus=1071,9393,30 \
+light_position=-0.57,0.75,0.80 light_brightness=80 light_ambient=20 light_color=255:255:255 \
+output=nviz_output format=ppm size=872,586  
+
+
+Miscellaneous
+-------------
+
+Taken from d.rhumbline.

man/Makefile

@@ -23,7 +23,7 @@ categories = \
 
 IDXCATS := $(foreach cat,$(categories),$(lastword $(subst :, ,$(cat))))
 
-IDXSRC = full_index index topics keywords graphical_index class_graphical $(IDXCATS)
+IDXSRC = full_index index topics keywords graphical_index manual_gallery class_graphical $(IDXCATS)
 
 INDICES := $(patsubst %,$(HTMLDIR)/%.html,$(IDXSRC))
 
@@ -73,6 +73,12 @@ GISBASE="$(RUN_GISBASE)" ARCH="$(ARCH)" ARCH_DISTDIR="$(ARCH_DISTDIR)" \
 	$(PYTHON) ./build_graphical_index.py $(HTMLDIR)
 endef
 
+define build_manual_gallery
+GISBASE="$(RUN_GISBASE)" ARCH="$(ARCH)" ARCH_DISTDIR="$(ARCH_DISTDIR)" \
+	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) \
+	$(PYTHON) ./build_manual_gallery.py $(HTMLDIR)
+endef
+
 define build_class_graphical
 GISBASE="$(RUN_GISBASE)" ARCH="$(ARCH)" ARCH_DISTDIR="$(ARCH_DISTDIR)" \
 	VERSION_NUMBER=$(GRASS_VERSION_NUMBER) VERSION_DATE=$(GRASS_VERSION_DATE) \
@@ -99,6 +105,10 @@ $(HTMLDIR)/graphical_index.html: $(ALL_HTML)
 	$(call build_graphical_index)
 	touch $@
 
+$(HTMLDIR)/manual_gallery.html: $(ALL_HTML)
+	$(call build_manual_gallery)
+	touch $@
+
 # TODO: this should be done in the same way as category_rule
 $(HTMLDIR)/class_graphical.html: $(ALL_HTML)
 	$(call build_class_graphical)

man/build_graphical_index.py

@@ -5,7 +5,7 @@
 #
 # MODULE:    build_graphical_index
 # AUTHOR(S): Vaclav Petras <wenzeslaus gmail com>
-# PURPOSE:   Build index (gallery) from images from all HTML files
+# PURPOSE:   Build graphical index
 # COPYRIGHT: (C) 2015 by Vaclav Petras and the GRASS Development Team
 #
 #        This program is free software under the GNU General Public
@@ -24,16 +24,6 @@ from build_html import write_html_footer, grass_version, header1_tmpl
 
 output_name = 'graphical_index.html'
 
-img_extensions = ['png', 'jpg', 'gif']
-img_patterns = ['*.' + extension for extension in img_extensions]
-
-# we don't want some images to show up
-# logos
-img_blacklist = ['grass_logo.png', 'grass_icon.png']
-# circles with numbers from helptext.html (unfortunate we have to list it here)
-# perhaps some general name ending would be good, like *_noindex.png
-img_blacklist.extend(['circle_{}.png'.format(num) for num in range(1, 6)])
-
 year = os.getenv("VERSION_DATE")
 
 # other similar strings are in a different file
@@ -51,9 +41,10 @@ header_graphical_index_tmpl = """\
 .img-list li {
     display: inline-block;
     position: relative;
-    width: 7em;
+    width: 8em;
     margin: 0;
     padding: 0.5em;
+    margin-bottom: 1em;
 }
 
 .img-list li:hover {
@@ -79,9 +70,9 @@ header_graphical_index_tmpl = """\
     margin: 0.1em;
     display: block;
     color: #409940;
-    font-weight: normal;
-    font-style: italic;
-    font-size: 80%;
+    font-weight: bold;
+    font-style: normal;
+    font-size: 120%;
 }
 </style>
 </head>
@@ -94,91 +85,46 @@ header_graphical_index_tmpl = """\
 """
 
 
-def img_in_html(filename, imagename):
-    # for some reason, calling search just once is much faster
-    # than calling it on every line (time is spent in _compile)
-    pattern = re.compile('<img .*src=.{}.*>'.format(imagename))
-    with open(filename) as file:
-        if re.search(pattern, file.read()):
-            return True
-    return False
-
-
-def file_matches(filename, patterns):
-    for pattern in patterns:
-        if fnmatch.fnmatch(filename, pattern):
-            return True
-    return False
-
-
-def get_files(directory, patterns, exclude_patterns):
-    files = []
-    for filename in os.listdir(directory):
-        if file_matches(filename, patterns):
-            if not file_matches(filename, exclude_patterns):
-                files.append(filename)
-    return files
+def std_img_name(name):
+    return "gi_{}.jpg".format(name)
 
 
-def remove_module_name(string, module):
-    string = string.replace(module.replace('wxGUI.', 'g.gui.'), '')
-    string = string.replace(module.replace('.', '_'), '')  # using _
-    string = string.replace(module.replace('.', ''), '')  # using nothing
-    string = string.replace(module, '')  # using original dots
-    return string
-
-
-def title_from_names(module_name, img_name):
-    # we ignore the possibility of having extension at the end of image
-    # so possibly r.out.png fails but image name should use _ anyway
-    # strictly speaking, it could be also, e.g., index name
-    for extension in img_extensions:
-        img_name = img_name.replace('.' + extension, '')
-    img_name = remove_module_name(img_name, module_name)
-    img_name = img_name.replace('_', ' ')
-    img_name = img_name.strip()
-    if img_name:
-        return "{name} ({desc})".format(name=module_name, desc=img_name)
-    else:
-        return "{name}".format(name=module_name)
-
-
-def get_module_name(filename):
-    return filename.replace('.html', '')
+index_items = [
+    ('raster_graphical.html', std_img_name('raster'), 'Raster'),
+    ('vector_graphical.html', std_img_name('vector'), 'Vector'),
+    ('database_graphical.html', std_img_name('database'), 'Database'),
+    ('general_graphical.html', std_img_name('general'), 'General'),
+    ('display_graphical.html', std_img_name('display'), 'Display'),
+    ('imagery_graphical.html', std_img_name('imagery'), 'Imagery'),
+    ('raster3d_graphical.html', std_img_name('raster3d'), '3D raster'),
+    ('temporal_graphical.html', std_img_name('temporal'), 'Temporal'),
+    ('misc_graphical.html', std_img_name('misc'), 'Miscellaneous'),
+    ('postscript_graphical.html', std_img_name('cartography'), 'Cartography'),
+    ('wxGUI_graphical.html', std_img_name('gui'), 'GUI'),
+    ('wxGUI.nviz.html', std_img_name('3dview'), '3D view'),
+    ('https://grass.osgeo.org/grass71/manuals/libpython/index.html', std_img_name('python'), 'Python'),
+    ('https://grass.osgeo.org/programming7/', std_img_name('c'), 'C library'),
+    ('manual_gallery.html', std_img_name('gallery'), 'Gallery'),
+]
 
 
 def main():
     html_dir = sys.argv[1]
 
-    html_files = get_files(html_dir, ['*.html'],
-                           exclude_patterns=[output_name, '*_graphical.html'])
-    img_html_files = {}
-
-    for filename in os.listdir(html_dir):
-        if filename in img_blacklist:
-            continue
-        if file_matches(filename, img_patterns):
-            for html_file in html_files:
-                if img_in_html(os.path.join(html_dir, html_file), filename):
-                    img_html_files[filename] = html_file
-                    # for now suppose one image per html
-
     with open(os.path.join(html_dir, output_name), 'w') as output:
         output.write(header1_tmpl.substitute(title="GRASS GIS %s Reference "
                                                "Manual: Graphical index" % grass_version))
         output.write(header_graphical_index_tmpl)
         output.write('<ul class="img-list">\n')
-        for image, html_file in img_html_files.iteritems():
-            name = get_module_name(html_file)
-            title = title_from_names(name, image)
+        for html_file, image, label in index_items:
             output.write(
                 '<li>'
-                '<a href="{html}" title="{title}">'
+                '<a href="{html}">'
                 '<img src="{img}">'
                 '<span class="name">{name}</span>'
                 '</a>'
                 '</li>\n'
-                .format(html=html_file, img=image, title=title, name=name))
+                .format(html=html_file, img=image, name=label))
         output.write('</ul>')
         write_html_footer(output, "index.html", year)
 

man/build_manual_gallery.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+############################################################################
+#
+# MODULE:    build_graphical_index
+# AUTHOR(S): Vaclav Petras <wenzeslaus gmail com>
+# PURPOSE:   Build index gallery from images from all HTML files
+# COPYRIGHT: (C) 2015 by Vaclav Petras and the GRASS Development Team
+#
+#        This program is free software under the GNU General Public
+#        License (>=v2). Read the file COPYING that comes with GRASS
+#        for details.
+#
+#############################################################################
+
+import os
+import sys
+import fnmatch
+import re
+
+from build_html import write_html_footer, grass_version, header1_tmpl
+
+
+output_name = 'manual_gallery.html'
+
+img_extensions = ['png', 'jpg', 'gif']
+img_patterns = ['*.' + extension for extension in img_extensions]
+
+# we don't want some images to show up
+# logos
+img_blacklist = ['grass_logo.png', 'grass_icon.png']
+# circles with numbers from helptext.html (unfortunate we have to list it here)
+# perhaps some general name ending would be good, like *_noindex.png
+img_blacklist.extend(['circle_{}.png'.format(num) for num in range(1, 6)])
+
+year = os.getenv("VERSION_DATE")
+
+# other similar strings are in a different file
+# TODO: all HTML manual building needs refactoring (perhaps grass.tools?)
+header_graphical_index_tmpl = """\
+<link rel="stylesheet" href="grassdocs.css" type="text/css">
+<style>
+.img-list {
+    list-style-type: none;
+    margin: 0;
+    padding: 0;
+    text-align: center;
+}
+
+.img-list li {
+    display: inline-block;
+    position: relative;
+    width: 7em;
+    margin: 0;
+    padding: 0.5em;
+}
+
+.img-list li:hover {
+    background-color: #eee;
+}
+
+.img-list li img {
+    float: left;
+    max-width: 100%;
+    background: white;
+}
+
+.img-list li span {
+    text-align: center;
+}
+
+.img-list li a {
+    color: initial;
+    text-decoration: none;
+}
+
+.img-list li .name {
+    margin: 0.1em;
+    display: block;
+    color: #409940;
+    font-weight: normal;
+    font-style: italic;
+    font-size: 80%;
+}
+</style>
+</head>
+<body style="width: 99%">
+<div id="container">
+
+<a href="index.html"><img src="grass_logo.png" alt="GRASS logo"></a>
+<hr class="header">
+<h2>GRASS GIS manual gallery</h2>
+"""
+
+
+def img_in_html(filename, imagename):
+    # for some reason, calling search just once is much faster
+    # than calling it on every line (time is spent in _compile)
+    pattern = re.compile('<img .*src=.{}.*>'.format(imagename))
+    with open(filename) as file:
+        if re.search(pattern, file.read()):
+            return True
+    return False
+
+
+def file_matches(filename, patterns):
+    for pattern in patterns:
+        if fnmatch.fnmatch(filename, pattern):
+            return True
+    return False
+
+
+def get_files(directory, patterns, exclude_patterns):
+    files = []
+    for filename in os.listdir(directory):
+        if file_matches(filename, patterns):
+            if not file_matches(filename, exclude_patterns):
+                files.append(filename)
+    return files
+
+
+def remove_module_name(string, module):
+    string = string.replace(module.replace('wxGUI.', 'g.gui.'), '')
+    string = string.replace(module.replace('.', '_'), '')  # using _
+    string = string.replace(module.replace('.', ''), '')  # using nothing
+    string = string.replace(module, '')  # using original dots
+    return string
+
+
+def title_from_names(module_name, img_name):
+    # we ignore the possibility of having extension at the end of image
+    # so possibly r.out.png fails but image name should use _ anyway
+    # strictly speaking, it could be also, e.g., index name
+    for extension in img_extensions:
+        img_name = img_name.replace('.' + extension, '')
+    img_name = remove_module_name(img_name, module_name)
+    img_name = img_name.replace('_', ' ')
+    img_name = img_name.strip()
+    if img_name:
+        return "{name} ({desc})".format(name=module_name, desc=img_name)
+    else:
+        return "{name}".format(name=module_name)
+
+
+def get_module_name(filename):
+    return filename.replace('.html', '')
+
+
+def main():
+    html_dir = sys.argv[1]
+
+    html_files = get_files(html_dir, ['*.html'],
+                           exclude_patterns=[output_name, '*_graphical.html', 'graphical_index.html'])
+    img_html_files = {}
+
+    for filename in os.listdir(html_dir):
+        if filename in img_blacklist:
+            continue
+        if file_matches(filename, img_patterns):
+            for html_file in html_files:
+                if img_in_html(os.path.join(html_dir, html_file), filename):
+                    img_html_files[filename] = html_file
+                    # for now suppose one image per html
+
+    with open(os.path.join(html_dir, output_name), 'w') as output:
+        output.write(header1_tmpl.substitute(title="GRASS GIS %s Reference "
+                                               "Manual: Manual gallery" % grass_version))
+        output.write(header_graphical_index_tmpl)
+        output.write('<ul class="img-list">\n')
+        for image, html_file in img_html_files.iteritems():
+            name = get_module_name(html_file)
+            title = title_from_names(name, image)
+            output.write(
+                '<li>'
+                '<a href="{html}" title="{title}">'
+                '<img src="{img}">'
+                '<span class="name">{name}</span>'
+                '</a>'
+                '</li>\n'
+                .format(html=html_file, img=image, title=title, name=name))
+        output.write('</ul>')
+        write_html_footer(output, "index.html", year)
+
+
+if __name__ == '__main__':
+    main()