From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.comp.tex.context/23823 Path: news.gmane.org!not-for-mail From: David Arnold Newsgroups: gmane.comp.tex.context Subject: Re: beginners manual Date: Sat, 26 Nov 2005 11:46:55 -0800 Message-ID: <48D68F63-D9C9-4205-BA55-BFF1CE875A7C@northcoast.com> References: <4387B20E.9060208@wxs.nl> <43884209.7070106@elvenkind.com> Reply-To: mailing list for ConTeXt users NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 (Apple Message framework v728) Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1133034614 27170 80.91.229.2 (26 Nov 2005 19:50:14 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 26 Nov 2005 19:50:14 +0000 (UTC) Original-X-From: ntg-context-bounces@ntg.nl Sat Nov 26 20:50:04 2005 Return-path: Original-Received: from ronja.vet.uu.nl ([131.211.172.88] helo=ronja.ntg.nl) by ciao.gmane.org with esmtp (Exim 4.43) id 1Eg63f-0006Zc-Mp for gctc-ntg-context-518@m.gmane.org; Sat, 26 Nov 2005 20:50:03 +0100 Original-Received: from localhost (localhost [127.0.0.1]) by ronja.ntg.nl (Postfix) with ESMTP id 09446127D5; Sat, 26 Nov 2005 20:50:03 +0100 (CET) Original-Received: from ronja.ntg.nl ([127.0.0.1]) by localhost (smtp.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 24319-04; Sat, 26 Nov 2005 20:50:02 +0100 (CET) Original-Received: from ronja.vet.uu.nl (localhost [127.0.0.1]) by ronja.ntg.nl (Postfix) with ESMTP id 88814127C5; Sat, 26 Nov 2005 20:48:10 +0100 (CET) Original-Received: from localhost (localhost [127.0.0.1]) by ronja.ntg.nl (Postfix) with ESMTP id B1240127C5 for ; Sat, 26 Nov 2005 20:48:08 +0100 (CET) Original-Received: from ronja.ntg.nl ([127.0.0.1]) by localhost (smtp.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 24248-05-2 for ; Sat, 26 Nov 2005 20:48:07 +0100 (CET) Original-Received: from borg.inreach.com (mail.northcoast.com [209.142.2.71]) by ronja.ntg.nl (Postfix) with SMTP id 014A3127A7 for ; Sat, 26 Nov 2005 20:48:06 +0100 (CET) Original-Received: (qmail 10377 invoked from network); 26 Nov 2005 19:45:40 -0000 Original-Received: from unknown (HELO ?209.209.20.98?) (209.209.20.98) by mail.northcoast.com with SMTP; 26 Nov 2005 19:45:40 -0000 In-Reply-To: <43884209.7070106@elvenkind.com> Original-To: mailing list for ConTeXt users X-Mailer: Apple Mail (2.728) X-Virus-Scanned: amavisd-new at ntg.nl X-BeenThere: ntg-context@ntg.nl X-Mailman-Version: 2.1.5 Precedence: list List-Id: mailing list for ConTeXt users List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: ntg-context-bounces@ntg.nl Errors-To: ntg-context-bounces@ntg.nl X-Virus-Scanned: amavisd-new at ntg.nl Xref: news.gmane.org gmane.comp.tex.context:23823 Archived-At: Hans, Taco, et al, It's time for me to wax philosophic on the beginner's manual. I've read a few posts to this list, and tried to think back to my experience, and looked at my troubles now, but I haven't reread the beginner's manual as yet. That I will do in the upcoming weeks. My first thought is this: In my opinion, the beginner's manual remains one of very best sources for Context. My second thought is the fact that this is a beginner's manual in every sense of the word. That is, you need to be very careful with what goes into the manual. Truly, a guiding principle should be: What does a beginner need to see? Think of a user who is beginning with a blank slate, or alternatively, think of a user who's been gone for a while (I've qualified for this category on several occasions and revisiting the beginner's manual has always been helpful). What does this user need to see? And what does this user need to be protected from? First and foremost, you've got to make sure that users on different platforms have a good install of Context. This could be a set of appendices: Appendix A -- Installation on Windows, Appendix B -- Installation on Linux, Appendix C -- Installation on Mac OS. Again, users could be very helpful in testing these instructions. This is a "beginner's manual," so it would be helpful if these instructions were of the "Quick Start" variety, as involved instructions will only serve to frustrate the beginner. Of course, these instructions should include a "Hello, World!" example in order to test for a valid installation. Whenever I teach a new concept in mathematics, I'm faced with a choice of two directions. I can start with the concept, then give examples. Or I can do some examples, then discuss the abstraction at a higher level. I am constantly forgetting that the second method is usually a better choice for my students. For example, suppose that I want to show that any multiple of an eigenvector is again an eigenvector of a given matrix. I can first prove it in the abstract (A (cx)=c(Ax)=c(lx)=l(cx)), then give examples. Alternatively, I can put a little 2x2 matrix on the board, find the eigenvectors, then demonstrate that multiples of the eigenvectors are again eigenvectors. Once the students have the idea, then I can put up the abstraction of the general proof. A reference manual is an example of the first method, a beginner's manual should follow the second method. It's easier, in my opinion, to learn by example, to learn by doing. Topics should be included or excluded based on a guiding principle: What does a beginner need to know to get started? It will be tempting to include using a different font, or talk about interactive documents, etc, but these are advanced topics, which belong in separate manuals where space and time will do them justice. Indeed, what is truly needed is a separate beginner's manual on interactive documents. Layout really threw me for a loss the first time (and times thereafter) I went through the beginner's manual. I was confronted with terms (cutspace, backspace) that might be familiar to typographers, but I had no clue what they meant. I can remember spending countless hours tweaking layout parameters, printing, then measuring with a ruler, only to scratch my head when I did not get predicted results. To this day, I am still not completely sure what I am doing in this area. I think what is needed in the beginner's manual is an image similar to Patrick's \ShowLayout result from his t- layout module. Secondly, it would be time well spent to build an improved \showframe command. Perhaps this even exists, but I am not aware of it. It needs to provide accurate measurements, even when printed and the rulers come out. Perhaps if a user included the \showframe command, a trigger of some sort could change the size of the paper that the document is typeset on, with an outline of the actual paper size, and the edges, margins, headers, etc, all framed and in view, even if they lie outside the actual paper outline. List users can help to make sure that the manual is free of errors. If something doesn't work, this is much more upsetting to a beginner than a seasoned user. A seasoned user might say "oh, that's just a typo, do this," but a beginner has an entirely different reaction on an entirely different emotional level. Troubleshooting should get some time in the beginner's manual. People coming from a Word environment are not going to understand what is going on when a compilation halts. Seasoned TeX users know about typing h, x, s, e, etc, but people who've never seen TeX before are going to freak out. So, some time should be spent on troubleshooting. Or, a conscious decision has to be made: Will we assume that all beginners in Context have TeX experience? So, I advise, stick to the basics. Get the user started. Ask yourself what a user needs to write a good paper: Title page, abstract, toc, index, bibliography, section headers, headers and footers, footnotes, labels and references, mathematics (somewhat weak in the current manual), tables, figures (including the idea of floats which bothers users coming from Word no end), lists, layout, alignment, quotations, formating text (bold, italic, slant, verbatim, etc), defining new environments for examples, definitions, theorems, etc., and some small macro capability. Finally, you should certainly provide pointers to advanced documents where users can continue their growth. I hope this helps. David