Re: ANNOUCE: gTrouble - New project [summary]

[Dermot Musgrove <dermot glade perl connectfree co uk>]

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.

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.
 
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 :-) 

> 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 :-)

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