Scrivener b6 Help File

  1. When I scroll the help file the panel on the left also scrolls. It just occurred to me that perhaps it could stay fixed while the text panel moved up and down on scrolling. It is not vital - just a little idea you might consider.

  2. I also wondered if it would help new users to show the vertical split next to or under the horizontal split in The Main Interface entry ie, This is a ‘Horizontal Split’ with Editor pane 1 and Editor pane 2 – and This is a Vertical Split with with Editor pane 1 and Editor pane 2 side by side. It sort of gets new users ‘seeing’ a major function at the outset, so when they meet the fuller explanation further on they will already have seen a visual representation of the two concepts.

  3. I see that you still prefer the alt-cmd form instead of option-cmd (for example in describing meta-data - under Introduction to the Inspector). Maybe you should flag this variation from the convention on other Apple keyboards. I mean just mention the variation.

  4. Related to the Editor panels - is it possible to intensify the grey text label at the top - as a choice - to give a more vivid visual relationship to the document with the same name in the Binder panel.

  5. The link in The Main Interface here

takes you to Views rather than the corkboard view.

  1. Under Views > Editor:Text View. I wondered if this needed a graphic - its a bit lost and the text is moderately complex:

I am aware of the link to Text Editing, but that is a very complex description of the pop up panel to sit alone without a graphic (as in Text Editing).

  1. The Edit Scrivenenings topic is brilliant. So clear. So simply and elegantly written. A vivid, informative picture of the function exactly where it is needed in a very accessible learning sequence of text. This is a model of how to write a help file topic on quite new concept.

  2. I wondered if MultiMarkdown could get the Scrivenings treatment. It really needs diagrams - far too much unrelieved text. First we get a text based summary, then MM according to Gruber, then MM according to Fletcher, and so on. This huge body of text is broken by a single diagram related to MM settings. It is, after all a ‘HELP’ file we are looking at. As a new user I would expect to read this and gain a clear, workable understanding of MM so that I could use it in Scrivener.

This is a truly helpful ‘HELP’ file that gets called on clicking Scrivener Help. I am so impressed. I can see why you have been busy lately, Keith. Wow!
:smiley: :smiley:

One very small thing in the Binder topic, under Document Types, there is a small rectangle above the table. It looks like perhaps an empty table with borders left on?

Don’t forget that Fletcher has written a fairly comprehensive document, located in this thread. I do believe he has another version that is slightly more up to date, but I cannot find reference to it in the forums. Since his document is licensed under Creative Commons, if he is no longer interested in updating it, we could continue the effort. Also, since it is written using MMD, it would be fairly painless to get it into XHTML, and from there into a format suitable for inclusion in the proper help, if Keith wanted to bother with a multi-licence documentation :slight_smile: Just brainstorming. I certainly would not mind helping out in this area either.

Thanks for proof-reading!

AmberV - yes, I had an extra

command in there by mistake - funny thing was, it didn’t show in Camino, which is why I missed it. Thanks for that.

LL:

Already considered and rejected. Mainly because I hate frames.

I don’t think this is really essential. That is really just a brief introduction to the main interface. Users will soon see other ways of doing things. Not to mention the fact that the idea of taking any more screengrabs and editing the Help file could lead to brainbleed. :slight_smile:

I don’t really see any need to flat this, to be honest. Since I have been using Macs (which admittedly has only been three years), all the keyboards of the computers I have owned (iBook, MacMini - standard keyboard, MacBook) have used “alt”. I have never actuall seen “option” on a Mac keyboard. So really, Apple made the change to the convention, not me. As a new Mac user, I had no idea what the option key was. So to me, using “alt” will be natural to recent Mac converts, and stalwarts will know what I mean, too.

Er… no. Wish-list is closed. :slight_smile:

Great - thanks, I’ve fixed it for 1.0 (I wrote that section early on, when I intended to have more about the corkboard in the views section).

No, I maintain that the link to Text Editing should be enough. Otherwise it’s repeating things, given that the Text Editing section covers this in detail.

Thanks!

No, no, no, no, no. :slight_smile: I know very little about MultiMarkdown, for a start. Instead, the section in the help file just points users to where they can find out about it. I don’t want the Help file to encourage users to use MMD. MMD is just an added bonus for those who want to use it. Most users of MMD in Scrivener will already be familiar with it, and just need to know how it interfaces with Scrivener - which is described.

Thanks - and thanks again for taking the time to go through it and proof-read!

All the best,
Keith

Perhaps this is a UK vs. US difference? On all standard Mac keyboards I have seen in the US, certainly including all my PowerBooks, my wife’s MacBook, and the current Apple Wireless Keyboard, “option” is the primary word on the key with “alt” in smaller letters. There is no doubt that Apple’s convention is to refer to this key as the “option” key: see for example the Cocoa developer’s documentation on key bindings, tinyurl.com/ysh28o , or the Keyboard and Mouse preference pane’s “Modifier Keys” sheet:

Please consider following Apple’s convention and including a note for switchers from the PC that this is also labeled the “alt” key.

Andy

Curious. In the UK, Macs just have an Alt key with the symbol beneath it - absolutely no mention of “Option” on the keyboard anywhere.

Anyway, this is hardly a big deal, is it? I really can’t face going through the entire help file and replacing “Alt” for “Option” right now. It still says alt on your keyboard, right?

All the best,
Keith

P.S. Also, notably, Apple use “alt” internally in Cocoa. To check to see if the option/alt key is pressed, for instance, you look for NSAlternateKeyMask…

Well, it does seem to me that the documentation should conform to Apple’s conventions as much as possible, just as the interface very beautifully conforms to Cocoa conventions (while also making creative use of them, of course!). If your Keyboard & Mouse preference pane in the UK says “Option,” I really think the proper thing to do is follow Apple’s convention, and then include a note for users who might be confused, whether because they’re switching from PC or because they’re using an international or third-party keyboard.

This was discussed on the Cocoa developers’ mailing list a couple years ago and the consensus in the end was that while the internal frameworks use “Alternate” (although the Carbon framework uses “Option”), documentation for end users is very consistent: it’s the Option key. If in doubt, search apple.com for “option key” and for “alt key”–I don’t believe you’ll find any Apple documentation that makes reference to the latter. You’ll just find some references to it on developers’ discussion boards.

Andy

I just think this is really pedantic and not a big deal. Maybe I’ll change it, but I really don’t think it’s exactly going to ruin anyone’s user experience (whereas it may well ruin my evening :slight_smile: ). If Apple want consistency, they should deliver it themselves (who knows? Maybe they finally will with Leopard). But sure, whatever, I’ll change it; if I don’t, I’m sure others will only nag, too. :slight_smile:
Best,
Keith

You know, I’m going through the Help file to change “alt” to “option”, but something about it really bugs me. Yeah, it says “Option” in the keyboard system settings; but then, every spelling on my Mac (just as with Windows) is American, despite my having U.K. language settings. And it seems to me that international keyboards use “alt” instead of “option”, and U.S. keyboards have both written on, so changing to “option” seems to me to be very U.S.-centric. I wonder how many non-U.S. Mac users call this the “Option” key… And where exactly would I put a note for switchers or non-U.S. users that the “option” key is the “alt” key? Every place it occurs? Hmm.

Okay, I’ve changed my mind: I’m not changing it. Instead, I have added a note to the introductory page:

N.B. Throughout this Help file, keyboard shortcuts refer to the “Alt” key. On U.S. keyboards this is more commonly referred to as the “Option” key.

Now, if non-U.S. users find that their keyboards are also labelled “Option”, I will surely reconsider. :slight_smile:

All the best,
Keith

I have always called the alt key the option key, and yet I have only ever used Macs (since 1992), and only ever in the UK. I guess it must have been called ‘option’ for us at some point too.

I seem to remember wondering where the option key had gone, and it has taken me a long while to get used to ⌥ meaning alt, and I still don’t like it!

So option has my vote!

Regards, Leigh

Aaaaaaarrrrrrrrrrrrrgggggggggggggggghhhhhhhhhhhhhhh!

is all I can say. I guess on the plus side, if this is the only criticism people can come with, things can’t be all that bad.

All right, all right, this one really just isn’t worth the bother or the hassle - I have changed all references to “alt” to “option”. Happy now?

END OF ALT/OPTION DISCUSSION

Best,
Keith

You should add an option (or should that be “alt” :slight_smile: ) in the purchase process to add £5 to buy you a pint of beer. I’ll pay. :slight_smile:

Andy

:slight_smile:

You guys are a creepy bunch of pedants.

Btw, on my (German) keyboard the key is labelled “alt ⌥”, and I’ve always called it the bathtub key.
Keith, if you use the correct nomenclature for your shortcuts (cmd-bathtub-1), I’ll add 2.50 Euros to the total cost of Scrivener, because that’s the prize for a pint of beer around here. (£5?! If that was the prize for a pint in my neighbourhood, I’d become a pedantic bean counter too.)

In Australia there is an ALTernative to a Pint of beer. It is called a Schooner. I am plumping for a Schooner key. Hell, Why not? I am buying - or as we say over here - my shout!

Would it be an idea to offer the help file not only as a help file, with hyperlinks etc., but also as an old fashioned, printable guide, like many applications do? I’m one of those who prefer to read text on paper rather than on a screen …

Well, when I skin my eyes over the keyboards on my two U.S.-version macs, there’s a key that says Option, and in little letters it also says alt.

How hard can it be for U.S. users to see Keith write Alt in the Help File, and roll their eyes around their keyboards until they see alt written on the same key, and say, Hmmmmm, I bet alt’s, like, Option?

I mean, it’s not like he’s asking us Americans to stuff luggage in our boot, or order chips instead of fries or crisps instead of chips.

Timotheus - I really trust you are joking. Because if you really are suggesting I offer a printable guide as well as the one I spent two months organising and writing… well… Oh, never mind. NO. There will not be a printable guide. :}

As for the rest of you. Look, let’s lay it out straight:

Pavement was a bloody good U.S. indie band. Why? Because they didn’t call themselves Sidewalk, that’s why. Oh, and those cloth things hanging aroudn your windows - they’re curtains, right? I mean, what the hell are drapes? And yes, those fried things making us all fat - done properly, they’re chips. But you never even get chips in America, because chips are much bigger and chunkier and greasier than fries. For that, I pity you. And crisps - they’re the thin sliced, fried potatoes that taste so good. Candy? What the frak is that? You mean chocolate? Right. Because candy to me is “candy floss”, a big fluffy pink sugarry snack. Oh, and it’s tarmac, not macadam, okay? Beer - that is a thick, sickly alcoholic drink with a good froth on it. Budweiser is not beer. That is lager.And not a great one, either.

Jeez. Just because you had the best literature of the 20th century you think you can tell me what to call the “Alt” key. Phew. :slight_smile:

Keith

P.S. Er, in case you hadn’t guessed, my anti-American rant was ironic. Scrivener would not exist without Vonnegut and Salinger. Not by a long shot.