[I7] Table of Contents

[Andrew Hunter]

I'm reposting this to the Inform 7 porter's mailing list. I've  
uploaded the original email and screenshots to <http://www.logicalshift.co.uk/etc/TOC.zip 
 >, for anyone who missed it.

On 5 Jan 2008, at 00:46, Graham Nelson wrote:

> Dear Andrew, dear all,
>
> (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.

Yes, I can fairly easily add defaults that can be altered using the  
terminal: we can work out later whether or not they should go in the  
main application preferences.

> (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.

Yes, that's not a huge problem. The current meaning of the slider is  
just the depth of the tree rather than the kind of heading - so at  
level 3, it will show a tree 3 levels deep rather than just down to  
parts. I can change this if necessary: I'm not sure which style would  
be more useful or intuitive.

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

OK, I think I might be able to add this as one of the preferences. We  
could also use a texture for the background if it were more appropriate.

> (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.

I'm ahead of you there, as this is already done (but hard to show in a  
screenshot). I was thinking on Leopard we could use the dashboard/ 
iPhone style flip over effect so the headings would appear to be on  
the back of the source code.

Something else that probably needs to be added is to hook this into  
the back/forward system.

> (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?

I was going to use the system selection colour here, but yes, this can  
also go into a preferences list.

> (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.

Yes, I think it would be an idea to perform a rescan of the source in  
order to achieve this rather than relying on the syntax intelligence  
data to be up to date. Technically, errors wouldn't be irretrievable  
as the undo system should be able to sort them out.

> 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!

I think it's a matter of personal preference: I use it all the time.  
It's switched off by default anyhow.

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

OK, this should be doable: I'd probably make it work the same way the  
editors work in the transcript view.

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

That seems sensible: we could probably indicate that this is possible  
by showing the 'dotted combo box' that Mail uses for data detectors.  
I'm not sure how you'd show this on other platforms, though.

Emily Short wrote:
>
>> (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.)
>
> Er? I write all my extensions within the interface. But maybe I am  
> not understanding what you have in mind.

I think possibly the ability to edit them in the single window  
interface rather than in separate document windows. I think that, on  
the Mac at least, it makes more sense to leave the extension editor as  
a separate window, but perhaps add the ability to easily open the  
extensions that a particular project is using.

>
>> 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 would certainly be nice also.
>
> A few general notes: I suspect the ideal indentation step width will  
> itself depend a bit on how many layers of hierarchy the author is  
> using; I'd indent more if I just have chapters and sections, but  
> less if I'm using the full possible range. We may want to leave that  
> in the hands of the author. If we don't, I'm guessing that we won't  
> be able to settle on a single ideal depth.
>
> The other thing I occasionally run into is starting a project with  
> just chapters and sections, and then realizing that the project is  
> growing so complex that I need to promote everything a level -- make  
> my chapters into parts, my sections into chapters, in order to allow  
> new sub-chapters. I wonder whether it would be worth providing a way  
> to do such a thing automatically.

This sounds like something that belongs on the format menu: perhaps if  
you have the cursor in a section title there could be an option here  
that said 'promote sections to chapters', which would also move  
chapters into parts if needed to make room. It could also go on a  
context menu for the source and the TOC page.

Andrew.