Re: ANNOUCE: gTrouble - New project [summary]

[Tom Gilbert <gilbertt tomgilbert freeserve co uk>]

* Dermot Musgrove (dermot@glade.perl.connectfree.co.uk) wrote:
> Hi all,
> 
> I am not an expert in any of these areas so please excuse me if I am 
> talking rubbish, these are just some personal impressions and not a request
> for flames :-)
> 
> Tom Gilbert wrote:
> > 
> snip
> > reiterate that sgml/xml are not subjects in which  I am knowlegable.
> > I picked sgml, 'cos that's what DocBook uses, and its familiar to me
> I find XML much more intuitive than any other language for docs. My
> simple mind can cope with the nesting/scoping when I have <tag></tag>
> pairs - perhaps HTML has got to me here. I have used the perldoc very
> superficially but I have been scared away from sgml, life is too short
> to struggle with documentation and I can understand why Gtk+ docs are 
> still so sparse (no comment on the lovely toolkit)
> At least XML would not limit you in any way.

Yup. I'm pretty settled on the idea of XML now anyway. If I had
anything to do with the gnome-help-browser2, I'd would probably want
it to read DocBook sgml directly (at least), and if it could do this,
xml would be easy...

> 
> snip
> 
> > The second thing is not to restrict to just troubleshooting, but to
> > encompass any kind of interactivity, such as howtos. This was the
> > original intention, I just didn't explain it well.
> This could be really useful, I reckon that good docs would grow naturally 
> if I had a scalable system that started as a little README but could be
> gradually extended to a complete, network-capable help/info/man/howto and
> trouble-shooting system.
> 
> Which reminds me, I don't really like gTrouble as a name. It sounds like
> it would _cause_ trouble rather than help you to fix things. Perhaps 
> emphasising 'help', 'answer', 'information', 'howto', 'manual', 'solving'
> 'repair' would be more positive. I suppose that ghelp has already been used.
  
I think, rather than a standalone (separate) app, I'm going for a
library (libGuide?) and a feature for next generation help browser,
which will use this lib.

> snip
> 
> > So would it be helpful for us to create an xml syntax/dtd for
> > interactive help, which other programs/environments to use, and create
> > an interface to it in the new help-browser?
> > Is there an existing syntax we can use without restricting
> > flexibility. (Don't forget my previous example was most basic).
> > 
> > Or should we create a library for the rendering of the xml, and the
> > running of built-in tests, and allow other environments to use this?
> > How far do we go? Is this worthwhile?
> > (I really want to supply a library of tests for guide-writers, its much
> > easier to check the existance of a file / query an rpm  automatically
> > than ask user to go looking for it. Others may think this is not a
> > necessary feature.)
> I reckon that, as a developer, I would like as much help as possible here,
> please don't let me make mistakes that I will regret later. I don't want
> loads of empty files with strange (fixed) names but If I could just put 
> some plain text files into a 'Documentation/text' directory I would be 
> much more likely to make a start. I know that this is not a good XML 
> approach but as I am not as interested in formatting text as I am in
> programming, this doesn't worry me :-) 

Everyone hates writing docs. There's no point me writing anything
unless it make the creation of powerful docs _easy_.
XML tags for creating layout / question-answer links etc are fine, and
I can cope with this. The problem for me now, is working out how
simplify the kind of complex/branching structures a good
trouble-shooter needs, and to include (and make use of) extra
information, such as:

o email feedback to program/guide author if certain conditions are
  met.
o Storing answers to questions for later use/comparison/submission
o Providing tests.
  This point is important to me, as it is my edge. I   don't like 
  to work on software that doesn't have an edge. In this   case,
  defining tests which could be refered to in the XML, could  make
  some guides semi-automatic. If you can't get your modem to work,
  the guide could immediately tell you that pppd isn't installed,
  without asking irrelevant questions...

ie. how much should the library do, and how much functionality should
the help-program/library-using app provide?

> > Please send guidance! These are my new goals (possibly over-optimistic)
> > 
> > General:
> > o Available to non-Gnome environments
> Definitely! I don't run Gnome (but I do use gnome-libs). I wouldn't bother
> using a module that forced me to install Gnome just to work.
> 
> > o Easy syntax for guide-writers
> Yes, of course.
> 
> snip 
> 
> > o Self contained files, seperated on a per-app or per-topic basis.
> This is vital I think. I would happily put my docs in a standard place
> but I would hate to update (and probably break) any complicated system
> or, even worse, depend on someone else to do it.
> 
> snip
> 
> > I'm quite surprised noone has suggested the front-end should look like a
> > little paper-clip in a box ;)
> Please don't :-)

No fear.

> Another really useful goal might be to provide tools that would migrate
> docs of all types to the new system. You would get to that critical mass
> very quickly if you could generate standard docs for existing projects.
> 
> I reckon that this project, especially with a good UI for both developers 
> and end users could help the whole community and would make an enormous
> impact on beginners. A pet I hate of mine is the lack of a standard 
> interface to the tonnes of Linux documentation that exists locally and
> online.
> 
> Just my 0.02 Euro
> 
> Good luck and regards, Dermot

Ok. I'm going to get some kind of proof-of-concept hacked together
over the weekend, using libxml to read a guide (qhich I will make
up), and gtk widgets to ask questions/display answers.
Then we'll see how feasible all this stuff is, people'll know what I'm
talking about a little more, and I'll know what questions I need to ask
people. Anyway, I won't know the full scope of this endevour until I
start to hack.

Hi-ho, hi-ho, it's off to parse we go....

Tom.
-- 
            .-------------------------------------------------------.
    .^.     | Tom Gilbert, England | tom@tomgilbert.freeserve.co.uk |
    /V\     |----------------------| www.tomgilbert.freeserve.co.uk |
   // \\    | Sites I recommend:   `--------------------------------|
  /(   )\   | www.freshmeat.net www.enlightenment.org www.gnome.org |
   ^^-^^    `-------------------------------------------------------'