On Fri, Oct 25, 2013 at 12:33 PM, Phil <[email protected]> wrote: > Ok, I use Leo quite a bit, but only for a small subset of its > capabilities. I've never used rst before, nor even tried to understand what > its good for. So maybe I'm a good test case. ;) >
You are the perfect test case. 1) I did not know I needed docutils. The tutorial should mention something > about this. > I agree. > 2) @bool rst3_call_docutils = False suggests to me that I don't need > docutils, but that doesn't seem to be the case. What then does it actually > do? > This switch determines whether sphinx or docutils actually makes the output file. I'll have to make this clearer. > 3) You might talk about settings first, especially if they affect whether > the examples will work. > Early drafts did. Now that I know that I must discuss docutils and sphinx first, mentioning related settings early on seems like a good idea once again. > 4) You mention sphinx without explaining it. I don't know why that should > be important to me. > It's an alternative to just using docutils. You're right, I have to explain it, especially since I use sphinx to create all of Leo's docs. What is the presumed knowledge level of the reader? Admittedly, I know > nothing about rst, so maybe if I did, I would understand the tutorial > better. But it might help to preface the tutorial to let the reader know > what they might need to know before reading the tutorial, and direct them > to other materials that would help them acquire the prerequisite knowledge. > The rst3 tutorial assumes that the reader has read only the general-purpose tutorials. Fixing the oversights you mention should be enough to make the tutorial comprehensible for those people. No programming is involved. Thanks for your detailed comments. Very helpful. Edward -- 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.
