ANNOUCE: gTrouble - New project

[Tom Gilbert <gilbertt tomgilbert freeserve co uk>]

Hi folks,

Screen-shooter's going v1.0 after another day of testing, so I thought
I'd start something new.

gTrouble will be a flexible extensible trouble-shooting application,
reading guides from sgml files, and walking users through the
contents. An example sgml file is included at the bottom of this mail
to show the kind of thing I hope to achieve.

I wanted to check noone was doing anything similar, and to get some
feedback/suggestions _before_ I started, to save me re-doing stuff
later.

I'm going for sgml as its easy to create a nice structure, and structure
is going to be important in these things. Also, I figured i18n wouldn't be
too hard, as sed is our friend ;)

However, I am by no means an sgml guru, and so would like some help
nailing this side of things down.

The plan is that gTrouble will be called with the name of the guide to
be loaded. If it is not, it will present a list of all guides
installed.

Guides would be self contained sgml files, installed into
/usr/share/gnome/help/guides or something like that. Although they
would be self contained, they would be able to reference external
files, such as html help.

gTrouble would provide a library of test routines for use in guides,
so (as in the example below) tests such as file existence /
permissions / program versions etc could be implemented in addition
to asking the user questions.

So, an application writer could write a single guide file for his app,
install it with his Makefile, and gTrouble would do the rest.
Non-programmers would be able to contribute by writing guides, etc.

Guides will be able to link to other guides, will be multi-level
capable, going back and forwards as necessary. The sgml syntax must be
able to cope with this...

I want the sgml syntax to be _crystal_ clear, so the example below is
not set in stone. I'm not even sure its any good at all.
I want suggestions for additions/changes/removals before I start any
parsing code. (I'll get going on the ui in the meantime). The idea is
to minimise work for people _writing_ guides, I don't care if it means
extra work for me...

So, once you've read the example below, let me know what you think,
and most of all, tell me if you think there's any point. I'd hate to
waste my time on this...

btw. If you think the gTrouble name sucks, you know the routine. Send
me a better one, and I'll use it ;)

Tom.

<!-- 
- This is a short example of the sgml syntax I propose
- Purely to inspire feedback/contribution
- This is a "I can't connect using gnome-ppp" guide 
-->

<guide app="gnome-ppp" name="Trouble connecting using gnome-ppp"
ref="gnome-ppp-connect">

<intro>
<para>This guide will talk you through problems connecting using gnome-ppp</para>
</intro>

<page ref="modem">
   <question ref="is_modem_connected">
   <qtext>
       <para>Is your modem correctly connected?</para>
   </qtext>
   <choice label="Yes" action="Q_next"></choice>
   <choice label="No" action="goto_page" target="connect_modem"></choice>
   <tellmehow>
       <para>Test this by examining the connections at the back of your
       modem (if it is external). This is a simple example, so that's
       as far as I go</para>
   </tellmehow>
   </question>
</page>

<page ref="modem_type2">
    <question ref="modem_type">
        <qtext>
            <para>What kind of modem is installed in your machine?</para>
        </qtext>
        <choice label="Internal ISA" action="Q_next"></choice>
        <choice label="Internal PCI" action="goto_page" target="UhOh-Winmodem"></choice>
        <choice label="External Serial" action="Q_next"></choice>
        <choice label="Internal PCMIA" action="goto_page" target="PCMIA_modem"></choice>
       <choice label="Other" action="Q_next"></choice>
        <tellmehow>
            <para>How to tell what type of modem you have .....</para>
        </tellmehow>
    </question>
</page>


<page ref="pppd">
    <question ref="is_pppd_installed">
        <qtext>
            <para>Is pppd installed on your machine?</para>
        </qtext>
        <choice label="Yes" action="Q_next"></choice>
        <choice label="No" action="goto_page" target="install_pppd"></choice>
        <tellmehow>
           <para>Type pppd --version, and see if you get any output. If you
           have a redhat system, you can query the ppp rpm using rpm -V ppp</para>
        </tellmehow>
        <test type="executable" target="pppd" ifposchoice="Yes" ifnegchoice="No">
          <testtext>
             <para>This can be automatically tested for you if you wish</para>
          </testtext>
        </test>
    </question>
</page>


<page ref="PCMIA_modem">
    <question ref="pcmia_probs">
        <para>Do you have any problems with other PCMIA devices? </para>
    </question>
    <!-- Continues -->
</page>

<!-- Lots more pages, lots more questions -->
<!-- Now some answers -->

<page ref="connect_modem">
    <answer terminal="true">
       <para>So plug it in!</para>
    </answer>
</page>

<page ref="install_pppd">
    <answer terminal="true">
        <para>pppd can be downloaded from {link to html}, instructions for
        installing it can be found here {link to another guide}</para>
    </answer>
</page>

</guide>

-- 
            .-------------------------------------------------------.
    .^.     | 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 |
   ^^-^^    `-------------------------------------------------------'