On Fri, 25 Oct 2013 08:50:47 -0700 (PDT) "Edward K. Ream" <[email protected]> wrote:
> http://leoeditor.com/tutorial-rst3.html > > This was not easy. All suggestions welcome. > > Edward Hi Ed, My suggestions would depend on your intended audience. In this email, I'll assume your intended audience is any computer literate person, as that's the audience you were talking of evangelizing to in an earlier thread. And, of course, I'm a member of that audience --- I know something about computers, but little of Leo. I bogged down after about 1/10 of the tutorial because I couldn't find the created rST, but here's what I found so far: You wrote: "This creates an rST chapter title. Use only the “#” character, as shown." Given that two lines did, but one line didn't, use # characters, I found that confusing. I'd probably phrase it as "Put a line of several pound signs above the text title (War and Peace), and an identical line of pound signs below." Yeah, that's wordy, but when I write instructional stuff, my priority, by an order of magnitude, is clarity, and if I have to be redundant, or boring, or use bad English, or whatever, in order to be clear, that's just what I do (much to the consternation of the Sams Publishing editors when I wrote Samba Unleashed). You wrote: 1 Create a new outline node, as some descendant of the @rst node. 2 The node’s headline becomes the section’s title. 3 Type the contents of the section in the body text of the node. On #3, don't just call something "the node", because everything's a node. Call it the @rst node. On #1, for later reference, suggest a title for the new, descendant node. This makes things understandable, and also facilitates cut and paste. You wrote: "The rst3 command generates rST underlining automatically." Where does it put it? I couldn't find it, in my home directory or in my .leo/db directory. Also, I had a panic moment when I wondered what I needed to install in order to get a Linux rst3 command. I'd add the clause ", available from Leo's cmds submenu, " right after the word "command". I know these things seem obvious, but they're not at all obvious to someone who knows neither the subject matter nor the context. I stopped at this point, because without seeing the generated rST, I didn't see the point. Ed, as a generality, when I write a tutorial, I start by making no assumptions about the reader's knowledge, except for the fact that he or she is computer literate and smart. I aggressively look for and eliminate anything that is unclear or could be misconstrued. I name things, even to the point of boring repetition, and almost never use words like "it" or "the node". What I'm trying to do is give the reader a path to follow, and make it so the path has absolutely no branches or intersections requiring a choice, so the reader can be free to observe what's going on around him or her and not worry about missing a turn. Of course, the assumption is, later the reader will come back and make some branches, but by that time he knows the path like the back of his hand. By the way, where CAN I find the created rST? Thanks, SteveT Steve Litt * http://www.troubleshooters.com/ Troubleshooting Training * Human Performance -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/groups/opt_out.
