[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Online help

To my knowledge, d-i has online help text available in precisely two
places right now:

  1) the help line the newt frontend uses to advise you what keys you
     can press (and similar in other frontends)

  2) the special-purpose partitioning help screen

While obviously we all want to produce something that's as
self-documenting as possible without the aid of help text, we only have
so much screen space to work with, and experience suggests that some
people still get lost or confused. I think we could do better than this.
There are various places where we could probably cut down on confusion
if people were able to get help without having to consult the
installation guide separately. For example:

 * Many error screens could do with a bit of attached help to advise you
   what you might be able to do to get yourself out of the situation.

 * Big select boxes (such as choose-mirror) often have to keep the
   explanatory text fairly short in order to allow a sensible amount of
   space for the choices.

 * Advanced partitioning methods could use separate explanations of how
   they work and what you should be setting up.

 * The partitioner's help screen is only accessible from the main
   choose_partition screen, not from other screens within the
   partitioner. It should be accessible throughout.

 * clock-setup's UTC question could explain what the trade-offs involved
   in keeping your system in local time vs. UTC are.

 * Maybe tasksel could say a bit about what each task actually does.

I might have got some of the details wrong above, but I'm sure we can
all think of others.

I realise there are all sorts of memory implications in offering more
detailed help text, particularly when translations are involved.
Nevertheless, once we get past anna I think those ought to be reasonably
tractable; we can do the same thing that we do right now to throw away
translations for languages you're not using once we get up to loading
installer components. I'm interested in implementing the basic support
for this and would like to discuss the design before I get started.

The design I currently believe to be sensible is to add an optional
'Help' field to debconf questions. This field would contain the name of
another question, probably Type: text, whose Description would contain
the help text to be displayed (translated in the usual way). The reason
to do it like this rather than just having 'Help', 'Help-fr', etc.
fields in the question is that this allows multiple questions to share
the same help text, which I expect would be particularly useful in the

cdebconf frontends could optionally have a facility to access help text
for the current question: for example, the traditional F1 key doesn't
seem to be bound to anything in the newt frontend. (There might even be
room to mention F1 in the help line if we cut down the other text, e.g.
"F1 for help; Tab moves; Space selects; Enter activates buttons" or
similar, though French is probably the test there ... or we could have a
Help button on dialogs with help text. I'm not sure what would work best
here.) If no help text is available, this could do nothing, or perhaps
it could display some generic help text.

po-debconf would work with this as normal.

Help text that requires special substitutions, such as the current
partman help text, would need to have the substitutions done somewhere
near the start of the relevant udeb's postinst or similar so that it's
available whenever the help text might be displayed, rather than in the
way it's currently done in
partman-target/choose_partition/help/do_option. I don't think this
should be difficult.

What do people think? Does this seem sensible or not? This feels like a
relatively simple addition to me - have I missed anything obvious?


Colin Watson                                       [cjwatson@debian.org]

Reply to: