[I7] Re: Table of Contents

[Graham Nelson]

Dear Andrew, dear all,

This is really very encouraging. I'm glad to see us
moving forwards on this - I use "us" in the sense of
other people doing all the work, as always, but
still. Better navigation is part of the process of
demonstrating Inform's growing maturity as a tool
which can finally be held up as capable, somehow.
I am spending a lot of time myself at the moment
reviewing and documenting the source code to NI,
combing through it line by line for bugs and
generally inexplicable passages, and trying to
adjust to the idea of it as a piece of production
code rather than a wacky experiment. It's slow,
but surprisingly pleasing, work.

Inform's 15th birthday falls at the end of April
this year, and I think this might be an appropriate
time to remove the "public beta" caveat; to move
to the new licence; to publish all the source,
including all the tools, and so on. I might be
finished before then, but we'll see. It would be
good if the interfaces were also synchronised
then with what we consider our best collective
design - we should knock out any niggling bugs,
tidy up any scrappy-looking corners, and so on.
But it would also be good to have the navigation
system. You're clearly a fair way down the road
for OS X, but it's a lot of work for the others too.
Let's see how we get along.

My main feeling about this navigation feature
is that a nice design and attention to detail
will make all the difference. It has to feel
effortless and immediate, not frustrating and
a little odd, even though the difference between
the two can be quite small in user interface
terms... My suspicion is that this is an especially
delicate point of the interface, because any
feature which causes information to be
hidden is a potential obstacle. We also
want the thing to look elegant, because people
will look at it a lot.

So we must do whatever we can to make it clear.
And, though it may be annoying especially for
you, I think we should try the design out in
practice, come back to you with notes, and
go through a few iterations until we get it
right - I believe myself, Emily, Zarf and Adam
are all OS X users at least some of the time,
and can offer some feedback.

Some immediate responses:

(i) Is it possible to fix things so that some
property list file somewhere includes the settings
for -

(a) point size of heading name text
(b) indentation step per heading level (currently a little narrow?)
(c) the "leading" (vertical skip between baselines of headings)

...and in general other such parameters? I ask,
because I think it would be interesting to let
us experiment and see what settings we find
are the best balance between being pleasing
to the eye and displaying useful content on real
projects - and not having to recompile Inform
to try this would be very good.

I'm not suggesting adding these to the
Preferences for the app (yet, anyway); this
is just for the try-out period.

(ii) I like the heading depth feature, though
I wonder if it's possible to give more indication
which way the thing goes? Possibly we could
write next to it something like this -

[slider at 1] Show only Volume headings

[slider at 3] Show Parts and higher headings

[slider at 5] Show all headings

The text would dynamically change as the
slider moved; the default for a new project
would be 5, I guess.

(iii) The "what am I looking at right now and
where's my damn program?" issue.

We need to visually distinguish, in a subtle
but clear way, when the user is looking at the
TOC and when the source. I have three ideas
about this:

(a) Make the "paper colour", that is, the
background, slightly different. In fact I'd like
to suggest a three-fold scheme: white as now
for source text; a light grey for the TOC paper;
and a light yellow, legal-pad sort of colour
for editing extension text. (Because I do hope
we can accompany this TOC work with the
ability to edit extensions fully within the
interface - something much needed, if a bit
delicate to set up.)

(b) Use a spatial analogy. The conceit here
is that the TOC is on the left, the source on
the right. On the panel bar - where we currently
have two Headings buttons - I'd suggest
exactly two buttons:

....... [Contents]  [Text]

(Remember, this is all within the context of
the Source panel - so we mean the contents
page of the source and the text of the source.)
Contents to the left, text to the right.

(c) When moving between the two, use a
sliding animation: the Contents slides off
screen to the left, the Source slides off to
the right.

(iv) I like the Omni-Outliner style of highlighting,
yes. Again - if the colours and other parameters
could be included in a preference list we can
tinker with?

(v) This is an excellent idea:

On 4 Jan 2008, at 16:46, Andrew Hunter wrote:
> I think clicking in the margin where I'm drawing a line to group  
> related subsections together should select the containing section,  
> to reduce the amount of scrolling required.

(vi) And so is this:

> While restricted, the source code view will show a 'torn page' at  
> the top and bottom to indicate that there is more source code  
> available. Clicking on the tear will expand the source code back to  
> showing the entire file, perhaps with a simple animation if it's  
> practical.

(vii) On these two points -

> Something that would be nice, but maybe not to implement right away,  
> would be to add the ability to drag sections around to re-order  
> them, perhaps with automatic renumbering as well.

I really like the drag-reordering of sections -
such reordering I do a lot of, and besides, it
makes the contents seem much more editable -
but it would have to be implemented _very_
carefully to make it reliable in terms of how
it cuts and pastes; any error would be
irretrievable and since the source is saved
on every build... A bug here would make us
most unpopular.

I've never liked automatic renumbering. It
tends to presuppose that people use headings
in a particular numbered way - which they
don't always do. (I used lettered chapters
in ROTA, for instance.) I want the TOC to
change only at my direct instruction, really.
It needs to feel like my piece of paper, not
the computer's. Perhaps this is just me!

What I _do_ want is the ability to edit the
heading names by dropping the cursor
into the name and typing - rather the way
one edits track names in iTunes, or file
names in the Finder.

That does raise the awkward question of
what to do if the user makes it no longer a
heading, or changes the heading type. The
cleanest solution I can think of is this: in
a heading like

Chapter the First - The Bergenholm Solution

everything from "the..." onwards is editable:
but clicking on the word Chapter instead
pops up a drop-down menu, reading:

  Volume
  Book
  Part
  Chapter
  Section
  (Delete)

That way the interface can't be trapped in
a state where the heading is invalid because
the user is half-done changing things.

Anyway!  It's really good to see this
screenshot: it'll be a major advance when
the whole thing is sorted out.

I still want to come back to the whole question
of handling multiple source files in a project,
and helping with people who want to use
preprocessors, svn repositories, and such.
But let's see to this first.

  Graham

--
Graham Nelson