Testing Help in the Nautilus Preview Release

[John Fleck <jfleck inkstain net>]

Folks -

The latest Preview Release of Nautilus is out, and with it, thanks to
a lot of hard work from Ali Abdin and others, a functional version of
our new help system.

http://www.eazel.com/download/

It's not done yet, and still has its share of bugs, but the help system is
now stable and functional enough for serious testing.

HOW IT WORKS:

The major new component of the help system is a program called
gnome-db2html2. It renders DocBook on the fly, turning it into html
and passing that to a Mozilla component that displays the
file.

Nautilus has a left window pane that includes a help tab with
all Gnome applications listed. When you click on one, it looks in the
standard location for help files, {PREFIX}/gnome/help/appname/C/, for a
file called appname.sgml. If such a file exists, it parses and
displays it. If no sgml file exists, it falls back on the old-style
static html - a feature that gives us easy backward
compatibility. (This html rendering is busted right now (links don't
work), the victim of an unfortunate accident, so don't bother spending
too much time testing that part.)

Sgml testing also can be done by typing in a file name on the Nautilus
location bar (that little text field across the top like where you
type in url's in a web browser). "help:/path_to_file/appname.sgml" will
pass appname.sgml to gnome-db2html2 and display the result.

WHY WE NEED FOLKS TO TEST IT:

gnome-db2html2 currently supports a subset of the full DocBook,
loosely defined as "stuff we use in Gnome". An attempt was made to
scour all the Gnome documentation and test and add support for all the
tags in current use. Eventually, we'd like the tool to
support all DocBook, but that's a huge task, so this seemed like a
reasonable place to focus our energy for the 1.4 release.

We need people willing to test their docs and see how they render, to
see if there are tags we aren't yet supporting that we need to.

We're maintaining a list of all DocBook tags and their status:
http://www.inkstain.net/fleck/tags.txt

We've also put together a list of changes needed to make docs work
with the new rendering engine. If you don't do these, little things
might be busted:
http://developer.gnome.org/projects/gdp/changes/

If you find a tag that is not yet supported that you'd like to see
added, the best thing to do is to file a bug report:
http://bugzilla.eazel.com/

The "Nautilus Bug Reporting Assistant" on that home page will lead you
through the process. If you're uncertain, Ali Abdin (rak), Greg
Leblanc (gleblanc) or myself (jfleck) are pretty familiar with the
issues, and one of us can often be found on #docs (irc.gnome.org).

Beyond finding unsupported tags, we need to find the unexpected bugs
that are surely out there waiting to bite us. And now is the time for
GDP folks to air their views about how this thing ought to look and
behave.

KNOWN BUGS and SHORTCOMINGS:

There are some known bugs we're working on. In no particular order:

* il8n, both translating the navigational elements (next, home,
  previous) and finding the right doc if a translation to other than
  English exists

* mdash, hellip and the some of the other standard html entities are
  not yet supported (< and > are supported)

* We cannot yet set anchors and link to them within a doc. We can link
  to <sect*>'s, but not to other points within a doc. We also can
  crosslink to <sect*>'s in other docs, but not to anchors within
  another doc. That means lots of xref and linking doesn't work yet.

* glossary support - coming soon to a Nautilus near you, but not yet
  ready. When it's done we'll be able to link directly to definitions
  in Sasha's glossary ("gnome-help:glossary?term" will pop up the
  definition of "term")

* address tag

* Tags within title elements (things like <acronym>) don't display in
  the table of contents (a fix is in hand for this)

Happy testing!

-- 
John Fleck
jfleck inkstain net (h)
jfleck abqjournal com (w)
http://www.inkstain.net/fleck/
http://www.abqjournal.com/scitech/