[I7] Table of Contents

[Andrew Hunter]

Excellent, it sounds like we're on the right track, then.

On 6 Jan 2008, at 20:14, Graham Nelson wrote:

> Dear Andrew,
>
> This is really very good. I like it much, much better
> than the previous navigation gadget. It feels right,
> and indeed looks nice (I rather like the torn paper
> effect, especially).
>
> As always, I do have a few points to make:
>
> (a) I agree with Adam: clicking the title ought to
> go into the whole document.

Yes, it was supposed to do this, but it looks like I've broken  
something so that it doesn't work.

> (b) The buttons at the top of the panel bar need
> tidying: if you like my suggestion about having
> them left and right as
>
> [[Contents]]  [[Text]]
>
> then perhaps it is possible for whichever is now
> showing to be emphasised in some way, to
> make clear that they are a radio-button-like
> either-one-or-the-other choice?
>
> I think "Contents" is a better choice of name
> for the TOC than "Headings", certainly.

I agree; I left the buttons in this slightly untidy state to make sure  
they didn't get forgotten. I was thinking the final implementation  
should look more like the index tab: this would also leave open the  
possibility for putting a file manager here in the future.

> (c) Clicking on the torn paper area currently
> reopens the entire source, thus undoing the
> tearing. There's a certain logic to that, but
> I don't know - it has a rather drastic effect and
> is not easily undone. Can I suggest, instead,
> that clicking on the top tear does another
> cute barrel animation, but vertically this time,
> onto the source in the next heading up which
> does not include the current one as a
> subordinate? And similarly down. That way
> one can easily retrace one's steps, and can
> vertically step through through the whole
> source text.

This sounds like a good idea. I can add arrow icons to make the tears  
appear more clickable, which should solve the issue Adam found where  
it wasn't obvious that you could do something here.

Something that will need to be resolved is what to do if we are  
showing something like the last chapter in the first part and the user  
clicks to go down: do we move to the first chapter in the next part,  
or do we move to show the whole part? The problem with the first case  
is that text at the beginning of the next part will be missed, and  
it's not clear what to do if the next part only has sections instead  
of chapters. The problem with the latter case is that the action isn't  
symmetric, so clicking up after moving on will take you to the whole  
preceding part and not back to the chapter you were on before.

> (d) On the TOC page, the slider isn't currently
> friendly enough. I do strongly feel that the
> five notches ought to agree with the five
> heading levels - not the actual extant heading
> tree in the source... And the explanatory
> text would make a lot of difference. (I found
> it slightly puzzling to use even though I
> already knew what it did, somehow.)

OK, the current implementation was slightly easier to do than this,  
but it won't be too hard to revise it to work this way instead.

> It might perhaps be nice if the slider took
> some more immediate effect - if you click,
> drag, and hold it at some different notch,
> nothing takes effect until you let go. That
> makes it a little harder to get the visual
> sense of what it is one is adjusting.

Ah, this is particularly easy to fix, as it's just a matter of  
changing a checkbox in Interface Builder.

> (e) Those thin lines running vertically to
> group subheadings are an inspired idea.
> But it looks asymmetrical that when there
> is a final heading of size 2 - say - which is
> followed by three subordinate headings
> of size 3, no line is drawn down alongside
> these, because there's no next heading
> of size 2 - so nowhere to draw the line to.
> That means there's no way to grab the
> final bunch of headings, which is a
> shame, but it also visually suggests that
> the final bunch is different somehow,
> and that isn't really true.
>
> Perhaps such a final line could end in a
> little hollow circle rather than a little filled
> one?

Hmm, it might work if I just draw the line a little shorter - I think  
visually they appear to be part of the group they represent, so the  
hollow circle might just look out of place.

> (f) Resizing the project window doesn't resize
> the Source, apparently; it gets left stranded.

Doh, that's just me being careless - very easily fixed.

> (g) A new user will find the contents page of
> a project without headings a bit bewildering:
> it's just a completely empty area, with maybe
> the title in the top corner. We need to display
> a little placeholder text in this case, I think.
> Perhaps:
>
> (i) If there's no title, the TOC should be headed
> "Untitled" in italic?
>
> (ii) If there are no headings, the TOC should
> display the text:
>
> "Larger Inform projects are usually divided up with headings like  
> 'Chapter 2 - Into the Forest'. This page automatically displays  
> those headings as a Table of Contents, but since there are no  
> headings in this project yet, there is nothing to see."


This sounds sensible.

Something else that should probably be done is to hook this into the  
undo system, so that pressing undo after changing the source view will  
change it back again.

Andrew.