[GRASS-dev] TOC in HTML manual pages

GRASS GIS GRASS GIS developer
1

Hi,

I’m excited about the new TOC in HTML manual pages. There are some styling issues (bullet for every second item), and looking to the HTML code, the generator is creating both

and
    which is not good.
      should be enough.

      http://grass.osgeo.org/grass71/manuals/r.mapcalc.html

      Anyway, I’ve tried different approach and here is my prototype:

      https://googledrive.com/host/0B_7Sygt2HTPDamFPOEZpU0h1ZG8/r.mapcalc.html

      The TOC is generated by JavaScript, so it is available only when JS is available (and thus probably also CSS is available). The header contains empty div into which TOC is generated.

      The other difference is the CSS, we can compare what is better. The not so wide page content as it is currently in trunk actually quite good. However, CSS and HTML is not (yet) optimized for wxHtmlWindow.

      You have to hover over TOC to make the TOC itself visible.

      There is also a warning box with a link to a another versions of documentation (e.g. from trunk to release). And also title of the page. But this is unrelated to TOC.

      Vaclav

2

Hi,

2014-04-19 17:45 GMT+02:00 Vaclav Petras <wenzeslaus@gmail.com>:

Anyway, I've tried different approach and here is my prototype:

https://googledrive.com/host/0B_7Sygt2HTPDamFPOEZpU0h1ZG8/r.mapcalc.html

I like your changes, two small notes:

* GRASS GIS 7 label is too big :wink:
* link to GRASS 6 could point directly to the manual page of given module

Martin

3

On Sat, Apr 19, 2014 at 11:55 AM, Martin Landa <landa.martin@gmail.com>wrote:

Hi,

2014-04-19 17:45 GMT+02:00 Vaclav Petras <wenzeslaus@gmail.com>:

> Anyway, I've tried different approach and here is my prototype:
>
> https://googledrive.com/host/0B_7Sygt2HTPDamFPOEZpU0h1ZG8/r.mapcalc.html

I like your changes, two small notes:

And do you agree to overall idea of solving this in JS (every time page is

loaded) rather then Python (during compilation)? Or do you like just the
CSS which is of course applicable to any HTML regardless how it was
generated?

* GRASS GIS 7 label is too big :wink:

That is true, there is a lot of space, so it can be either big, or small
with white space or with some other info, not sure which, perhaps the name
of the module stolen by JS from the NAME section, not sure what for GUI and
other non-module pages.

* link to GRASS 6 could point directly to the manual page of given module

This is a great idea. Although, it will not work for modules not available
in the other version, I like it and we should do something like this. What
is unresolved about this when to put the box there, you don't want this to
be shown for offline version since it is trying to solve the case when
search engine returns 65 when user uses 64 or 7*.

Another thing which is different from the solution in trunk is that anchors
are derived from headings which might not be 100% safe but it allows to
link specific section nicely with a link which will not change unless you
rename section:

https://googledrive.com/host/0B_7Sygt2HTPDamFPOEZpU0h1ZG8/r.mapcalc.html#NULL_support

While the numbered id changes when you add section (but is independed on
special characters coming from math or localization):

http://grass.osgeo.org/grass71/manuals/r.mapcalc.html#h3_10

Also you can see that I just used every heading including the generated
ones. Not sure what is better, sure is that NAME section looks even more
strange in TOC then just as a heading, but I would ignore it because you
want to go to SYNOPSIS.

Additionally, I would suggest to generate some anchors even for Flags and
Parameters (Options?). This would allow to link a specific
flag/option/parameter. I'm not at all sure about the format:

http://grass.osgeo.org/grass71/manuals/r.mapcalc.html#expression
http://grass.osgeo.org/grass71/manuals/r.mapcalc.html#option-expression
http://grass.osgeo.org/grass71/manuals/r.mapcalc.html#parameter-expression
http://grass.osgeo.org/grass71/manuals/r.mapcalc.html#synopsis-expression
...

Vaclav

4

Vaclav Petras wrote:

I'm excited about the new TOC in HTML manual pages. There are some styling
issues (bullet for every second item), and looking to the HTML code, the
generator is creating both <table> and <ul> which is not good. <ul> should
be enough.

A more significant issue is that it overlooks the fact that the HTML
files are the source files for the Unix (nroff) manual pages, where a
ToC is just pointless junk.

Fixed in r59825.

http://grass.osgeo.org/grass71/manuals/r.mapcalc.html

Anyway, I've tried different approach and here is my prototype:

Please don't end up breaking the Unix manual pages (again) in the
process.

Whatever you do, ensure that the generated HTML is actually conformant
(to HTML 4 transitional); g.html2man isn't fault-tolerant.

--
Glynn Clements <glynn@gclements.plus.com>