Re: Feedback wanted on a ConTeXt tutorial

[Marco Patzer <lists@homerow.info>]

[-- Attachment #1.1: Type: text/plain, Size: 3901 bytes --]

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#Step_3:_Add_ConTeXt_to_Windows_search_path
   (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

[-- Attachment #1.2: Digital signature --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

[-- Attachment #2: Type: text/plain, Size: 485 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________