Re: "Ask GDP" sort of question (can 'o' worms)

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Tue, May 09, 2000 at 02:24:51AM -0400 or thereabouts, Aaron Weber wrote:
> Hey all--
> 
> This is probably something that's been gone over a number of times, but
> nonetheless, I'm interested in current opinions:
> 
> In what direction do you see docs moving as we go to 2.0 and start using
> Nautilus as a help browser? What would you most like to see added to Linux 
> and GNOME help systems?
> 
> I'm thinking in terms of indexing, searching, and context-sensitive help
> here: How do we go about doing that for GNOME?  How do those features
> differ from, add to, or detract from the current help implementation? 
> Do you see any changes in the way you will write docs for the upcoming
> 2.0 help system, which is more centralized and which takes greater
> advantage of SGML/XML searching/indexing (if i'm not mistaken, the idea
> is to generate the html on the fly, so that it's searched as SGML/XML)? 
> How do you currently (if at all) implement context-sensitive help?

Well, you were at the same GUADEC meetings as I was, and we both
wrote up lists of what came out of it :) For people who weren't
around on the list in March, there's a link to those on the GDP
page at http://www.gnome.org/gdp/ : the summaries are at:
http://www.gnome.org/mailing-lists/archives/gnome-doc-list/2000-March/0046.shtml
http://www.gnome.org/mailing-lists/archives/gnome-doc-list/2000-March/0051.shtml
and there's some discussion following those.

I haven't got any further than thinking about that, I'm afraid.
I was marking up (well, fiddling with someone else's mark up) for
a non-GNOME document yesterday, as it happens, and that involved
a glossary and copious use of <firstterm> and so on. I am very
tempted to mess around with some of my docs and add indices to them
just to see how it turns out.

I still like the idea I mentioned at GUADEC. Nautilus will have a
lefthand pane which can display different things, and the help browser
will be part of that. When it's displaying docs, I would love to 
see a list of "glossary terms", "index terms", "related pages" showing
up based on the contents of the marked up stuff displayed on the right.
A "see also" thing. Not necessarily by default, but as an option.
Jonathan seemed to think this was entirely possible. (Is he still
on honeymoon, btw?). It would get those from the 
"<firstterm linkend="defns-foo">foo</firstterm>" (glossary-style) or
"Foo<indexterm><primary>Foos</primary></indexterm>" (index-style) stuff.
If we do this. (I don't guarantee that that mark-up is correct: the
first may be, but I guessed at the second from the book! But you get
the idea.)

I think if we do it right, we can create a fairly good set of
cross-links like that, but I am concerned that it will either be
so rich that people get lost, or very intermittent. Can we find
someone at OSWG (http://www.oswg.org) to give us some pointers on
this? It was suggested as a possibility.

As for context-sensitive help, I understood that the idea was that
the hackers put in little markers into the code, so that each situation
you find yourself in has a number, and you write the help for each
one and it gets linked in. By someone. Somehow. (*Handwave*). Um. It 
reminded me a little of the way that strings are marked for translation 
into non-English languages. But I don't know whether that's actually 
what will happen..?

Telsa