On 2013–09–29 Mari Voipio wrote:
Inspired by some informal discussions at the recent ConTeXt meeting I started to write a *really* basic ConTeXt tutorial.
I'm happy to see someone willing to invest time and effort to improve the documentation! I did neither attend the meeting, nor take part in this discussion and I don't want to sound discouraging in any way. But I'm not sure if it makes sense to start another manual. ConTeXt already has plenty of manuals, including the very short “Top 10 macro” guide: http://www.tex.ac.uk/tex-archive/info/context-top-ten/cmds.pdf Then there is a medium sized manual aimed at beginners, “ConTeXt, an excursion” (which is rather outdated, I agree) http://www.pragma-ade.com/general/manuals/mp-cb-en.pdf “ConTeXt, an excursion” would probably come closest to what you have started. And then there is the main reference manual http://pmrb.free.fr/contextref.pdf I think the best approach is to focus on one single manual and write it in a beginner-friendly fashion. Everything else leads to duplicated effort and confusion. Furthermore, information scattered in many small places is harder to keep up-to-date. If a short beginner tutorial is required, I would suggest to create short chapter “A jump start for the impatient” or something along those lines and add installation instructions to the manual, detailing the TeXlive and ConTeXt standalone installation process. As I said, I didn't take part in the mentioned discussion, so I might be missing out relevant information.
However, before I get further than the first six chapters, I'd like to get feedback on it, especially on the content, but also on the layout. The file is (at least temporarily) available at http://www.lucet.fi/pdfs/ctxbasics.pdf.
Some thoughts: 1.1.1 Unfortunately there’s no really easy way to install ConTEXt on Windows. I never installed ConTeXt on Windows, but if this is true this should definitely be fixed. According to http://wiki.contextgarden.net/ConTeXt_Standalone#Command_line_method it should be sufficient to run 1) download the installer: http://minimals.contextgarden.net/setup/context-setup-mswin.zip 2) install: first-setup.bat 3) add ConTeXt to path: http://wiki.contextgarden.net/Windows_Installation:_ConTeXt_Suite_with_SciTe... (Maybe adding the exact command or a screenshot for step 3 would be helpful.) If this fails, we should work on that. 5 Formatting text Since you explicitly mention “The basic idea is to separate layout from content” in sections 2.1 and 3.1 I think it's not very educational to tell beginners to use font switches in the code: This is a {\ss test}. % sans serif This is a {\tt test}. % typewriter Rather teach logical markup from the very beginning. \definehighlight [important] [style=bold] \important{This} is logical markup. 6.3 Floats This is arguable, but I personally would drop the (not deprecated and still supported) MkII syntax for floats \placefigure [here,force] % really try to put the float just here {This is a cow} % Caption {\externalfigure[cow][width=2cm]} and replace it with the more intuitive MkIV syntax: \startplacefigure [title=A cow, reference=fig:acow] \externalfigure [cow] \stopplacefigure And refrain from using the [here, force] setting, otherwise beginners will never grasp the concept of floats. 6.4 Combinations Also arguable, but you might consider using the newer \startcombination [nx=3, ny=1] … syntax. It's more contextish and easier to understand, in my opinion. Furthermore, it's not covered in any of the manuals, as far as I know. I hope I phrased my comments in a constructive and helpful manner. Marco