Re: beginners manual

[Mari Voipio <mari.voipio@iki.fi>]

Hans Hagen wrote:
> I'm going to clean up the beginners manual

Yippee! :-)
Having read one printout to shreds I really appreciate this...


> - what should go in

As has been suggested here to an extent, there should be attachments (or 
separate smaller manuals) on how to install and update ConTeXt in 
different operating systems (Mac OS 10.4 was a breeze even for a new Mac 
user, Windows is a great pain in the butt every time; still running 
TeXLive 2004 ConTeXt on this machine because I can't afford to break 
anything). As I probably should do it for work anyway, I'm willing to 
write the part for MsWinConTeXt (for Win 2000/XP) as long as I get at 
least until the end of the year.

I also suggest writing a separate set of instructions for those people 
who migrate from LaTeX (like my brother did) and for those who migrate 
from MSWord (like I did) or Apple's Pages (or similar word processing 
software). I strongly feel that the beginners' manual per se should be 
for ALL beginners and shouldn't refer to either Word or LaTeX.
Again, as I probably have to write it at some point anyway, I'm willing 
to chip in for the MS Word part and I might even be able to write a 
draft for others to fill in with.


> - what should be updated

Tables is what would be really useful. This far I've only used tabulate 
and \table, but I have a faint idea that "natural tables" would be the 
real solution to my problems - but finding info on them has been so 
challenging that I've given up this far.

I also personally feel that a totally different approach to the fonts 
chapter would make my life a lot easier. I'm sure this partly relates to 
my Windows background, but for example the term "font family" was 
totally alien to me when I started using ConTeXt.
And of course, much of the first weeks with ConTeXt (in Windows) were 
overshadowed by the important question of "how to make the fonts and 
font switches work at all". I still don't understand the system at all, 
so even though I've successfully gotten a few of the TeXLive fonts to 
work, I always have to refer to my older ConTeXt documents to copy the 
code that has worked at least at some stage.
[In Word, you switch the font of the Normal style from Times New Roman 
to Century Schoolbook with about three clicks of the mouse - in ConTeXt 
the same may be a three-hour or three-day operation, at least with my 
not-even-intermediate skills... I love ConTeXt, I hate fonts.]

The order of things in the beginners' manual has often frustrated me as 
I feel that "same stuff" is split in different places all over manual. I 
have not dealt with math, but when I taught word processing with Word, 
these would be things that come up in the very, very beginning:

- how to change the font (family, size, emphasis)
- how to change the paragraph (line spacing, paragraph spacing, indents, 
alignment)
- how to print preview i.e. see the document as laid out on paper (in 
ConTeXt this would be "how to compile and view; maybe put more detailed 
instructions into the ConTeXt in Unix/Linux/Mac/Windows 
attachment/manual and just refer to these)
- how to change the margins [I had REAL problems with this in ConTeXt, 
the whole context is so different; but this should probably go into the 
"ConTeXt for word processor users" chapter]
[- how to save and retrieve a document; not really an issue with 
ConTeXt, I suspect all users are this much computer literate]


Next step is often additional text features:
- headings (in Word, "header" is only top part of page, the 
section/chapter titles are called headings)
- lists (i.e. itemize in ConTeXt)
- page numbers (many Word users never use their header/footer for 
anything else!)
- page breaking
- hyphenation

And, as many people migrate to ConTeXt when having to deal with large 
documents and/or math, the next step for many would probably be:
- figures (i.e. graphics)
- tables
- footnotes
- header & footer
- formulae, units, math otherwise
- special characters!
- registers, references
- interactivity?


If ConTeXt comes nowadays with modules, those should probably get a more 
prominent position in the manual and obviously a lot more detailed 
explanation than the current one. If I've understood the concept 
correctly, the modules are comparable to Word templates, but this far 
the information has been so split that I haven't bothered to piece it 
together to actually even try to use a module, not to talk about making 
one (although that bit probably belongs to the big manual).


> - who will participate (in translation)

I can do Finnish, it shouldn't take that long once the English original 
is ready. A bunch of LaTeX stuff exists in Finnish and that should help 
with the terminology (should probably try to stick to existing stuff) 
and I can possibly enlist brother to review what I've done, if there're 
no other Finnish speakers on this list.
I'll also be quite happy to proof the Swedish manual but as there are 
native speakers of Swedish on this list, I'd rather leave the actual 
translation work to them (especially when I use Swedish as spoken in 
Finland, which sometimes makes a difference).


> - how to deal with localization (maybe dedicated language related chapters)

Yes, definitely. Having now worked with translations of originally 
English ConTeXt document to German and Spanish I've had to look for 
answers for the following problems:
- hyphenation (how to turn it on and how to prevent it)
- labels in captions and references
   (how to switch language, how to adjust)
- regiments
- character sets (especially non-Latin stuff)
- punctuation rules (for example one vs. two spaces after period)

Sometimes I'd really, really love to have a list of what characters and 
languages ConTeXt is/is not capable of coping with, just a quick 
reference would help...


A few thoughts from the Windows front,

Mari