Feedback wanted on a ConTeXt tutorial

Mari Voipio

29 Sep 2013 29 Sep '13

9:22 a.m.

Hello! Inspired by some informal discussions at the recent ConTeXt meeting I started to write a *really* basic ConTeXt tutorial. 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. I know already that there are a few things missing in the existing chapters, but I'd like to know if the document is any good and if the style is suitable for such a document. I've planned and written it out of my own experiences with ConTeXt, so maybe this document could become a My Way doc when it is finished (something public domain anyway). Thank you, Mari

Show replies by date

Marco Patzer

29 Sep 29 Sep

11:05 a.m.

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

Mari Voipio

12:26 p.m.

On Sun, Sep 29, 2013 at 8:05 PM, Marco Patzer wrote:

...

Then there is a medium sized manual aimed at beginners, “ConTeXt, an excursion” (which is rather outdated, I agree)

I was actually aiming at one step lower and in doing things in the order a word processor user would approach ConTeXt. My copy of excursion is fairly thumbed at this stage, but I still sometimes need to use find to actually get at the things I need. So I wrote this new one "my way".

...

As I said, I didn't take part in the mentioned discussion, so I might be missing out relevant information.

It wasn't anything major, just some off-hand sentences. I've just written something similar for MetaPost, so this approach felt natural and kept me amused during the travel home (including 4 hrs spent sitting at the airport).

...

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.)

The problem is here: Windows users in general aren't used to command line and even fewer have ever touched a path (or even know such a thing exists). The only almost one-click approach is TeXLive - and unfortunately I can't currently test that on my Windows as it might mess up with my vital ConTeXt installation. Thus there is no real "Windows way" of installing ConTeXt and this may hold some potential users back.

...

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.

True. Not that I follow this advice myself, but probably should (some of my earlier ConTeXt files are - umm - not beautiful because I have some Word baggage).

...

\definehighlight [important] [style=bold]

\important{This} is logical markup.

I'd say this approach is too complicated for somebody who just wants to do documents on ConTeXt (more typing, too, and we people are lazy). However, I was thinking about trashing both \bf and \it and just talking about \em for marking emphasis. I think the big manual includes information on how to adjust \em to one's preferences (I'm sure I saw it *somewhere* while digging stuff up for this).

...

This is arguable, but I personally would drop the (not deprecated and still supported) MkII syntax for floats

Interestingly, this was the only syntax I know of and the only one I can find in the manuals and on the wiki.

...

\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

Nice. I'll try to get around to wikifying this asap.

...

And refrain from using the [here, force] setting, otherwise beginners will never grasp the concept of floats.

True. And otherwise I'm not happy about what I said about floats - I just barely understand them myself and gaining that knowledge was hard work - so I'll rewrite that section and will come up with something else to put there. (Although floats with "here,force" still float, just less so. Been there, done that; now I know it is a feature, not a bug. Useful for a thesis, not so in my work.)

...

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.

Nor the wiki, I'd never seen it before, although I've understood that more and more ConTeXt commands move towards the start ... stop syntax. Again, I'll try to get around to wikify this soonish (first I want to try it out, though). I've found before that I learn best by teaching others, for I will not teach anything I don't properly understand my way. Now I've already learned three new things, not bad. :-) Thanks for the comments! Mari

Lars Huttar

30 Sep 30 Sep

8:06 a.m.

On 9/29/2013 1:05 PM, Marco Patzer wrote:

...

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 ...

For my part ... I recently installed TeXLive 2012 and 2013 on Windows 7, and it was easy. I told it to install only the ConTeXt scheme, instead of installing everything. Also I had to configure the TeXWorks editor options to use ConTeXt (LuaTeX) by default instead of pdfLaTeX. But other than that, unless I'm forgetting something, it worked fine, out-of-the-box. Lars

Mica Semrick

11:15 a.m.

Any chance of getting that tutorial in some sort of version control? Github/SVN/bitbucket or whatever?! On Mon, Sep 30, 2013 at 7:06 AM, Lars Huttar wrote:

...

On 9/29/2013 1:05 PM, Marco Patzer wrote:

...
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 ...

For my part ... I recently installed TeXLive 2012 and 2013 on Windows 7, and it was easy.

I told it to install only the ConTeXt scheme, instead of installing everything. Also I had to configure the TeXWorks editor options to use ConTeXt (LuaTeX) by default instead of pdfLaTeX. But other than that, unless I'm forgetting something, it worked fine, out-of-the-box.

Lars

___________________________________________________________________________________ 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

___________________________________________________________________________________

Thangalin

29 Sep 29 Sep

11:50 a.m.

Hi, Some feedback: - The introduction paragraph can be shortened. For example, tell the reader to "try the subsequent examples using ConTeXt Live web page" (as opposed to 'almost all of the examples in the series can be run online'). On any example that does not work, indicate such at the time. - "abt 40 euros" is missing "ou". - "combo" should be "combination". - "In Windows", "In Mac", etc. can be "Windows", "Mac", etc. - Use the active voice (it shortens text). - Avoid using abbreviations and jargon. As Marco noted, why not apply such wonderful effort to the wiki? On Sun, Sep 29, 2013 at 8:22 AM, Mari Voipio wrote:

...

Hello!

Inspired by some informal discussions at the recent ConTeXt meeting I started to write a *really* basic ConTeXt tutorial. 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.

I know already that there are a few things missing in the existing chapters, but I'd like to know if the document is any good and if the style is suitable for such a document. I've planned and written it out of my own experiences with ConTeXt, so maybe this document could become a My Way doc when it is finished (something public domain anyway).

Thank you,

Mari ___________________________________________________________________________________ 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 ___________________________________________________________________________________

Mari Voipio

12:41 p.m.

Hi! On Sun, Sep 29, 2013 at 8:50 PM, Thangalin wrote:

...

- The introduction paragraph can be shortened. For example, tell the reader to "try the subsequent examples using ConTeXt Live web page" (as opposed to 'almost all of the examples in the series can be run online'). On any example that does not work, indicate such at the time.

Darn, I forgot to change this one - I found that the sample graphics are found by ConTeXt Live, so *all* examples this far work online. I aim at keeping things that way. I'm not that happy with the intro anyway, your sentence is a lot more beautiful than mine. :-)

...

- Avoid using abbreviations and jargon.

I thought I had, but obviously not enough. Will have to do a jargon check all over - I write one chapter at a time so minor discrepancies can be expected at this stage.

...

As Marco noted, why not apply such wonderful effort to the wiki?

Because my idea is to make a document that allows one to start from the beginning and doing the examples in the order given. I used the wiki a lot to check on stuff, but it is not quite the same thing - and wiki's "second document" is already a real jump start to ConTeXt, I want to introduce things slower. I will try to improve the wiki when I stumble on problems. E.g. within last three days I've looked up half a dozen commands that are not on the command reference index (the longer one) even though they have a page of their own, e.g. \externalfigure (not on http://wiki.contextgarden.net/Category:Commands but has a page at http://wiki.contextgarden.net/Command/externalfigure). If the index is generated manually (as it seems), I can edit it and add missing commands on the go when I find them. I must admit that I find it a bit scary to edit the wiki; I'm always worried about messing up with somebody else's work - with this tutorial project I can only mess up with my own text and mostly I can live with that. Editing the wiki I think that everybody else must know better than I do, for my command of ConTeXt is fairly basic, so I can't see my solutions being better than those already existing. Thus I rarely log in to edit, except with failing links and other small issues. How should I phrase this? The wiki is like an encyclopedia, I look up stuff (more often than not with find) that I need for each case. My aim is to make something like a novel or a book used for learning the basics of a foreign language, introducing new things gradually. Thank you for your time and comments! Mari

Keith J. Schultz

30 Sep 30 Sep

1:35 a.m.

Hi Mari, As some already mentioned "In" <OS> is not correct either use <OS> or "On"! In section 1.1.1 the last sentence is: TeXLive comes with a quite nice editor, TeXShop, that works well with ConTEXt 1) Missing period 2) TeXShop is Mac only. You probably meant to to say TeXWorks! TeXWorks is based on TeXShop. I do not know if it runs on Windows. In section 1.1.2 in the last sentence you write: […] and (abt 40 euros; a non-commercial licence is cheaper) […] 1) I do not get this? Where do you buy it? Never new you could buy it! 2) On can install the ConTeXt Standalone and download TeXShop, very little effort is needed to direct TeXShop to the standalone version. Switching between TeXLive and Standalone is then easy. 3) I could write up a tutorial for installing and TeXlive and Standalone if you care for one. Furthermore, Mac OS is a Unix system, though most do not realize this. Also, It might be best to point to the wiki for installing ConTeXt. In section 2.2 you talk about command, yet you forget to mention that commands can have a "setup"-command. I believe it is important to mention this as it is a integral part of ConTeXt and very important when using it as you example commands show. In general I would say your general way of going about things are O.K. Yet, I have one problem. I personally believe you should go into more detail about the relationship between typesetting, layout and ConTeXt. It depends if you are writing a getting started manual or want to write a comprehensive tutorial. I myself started on a tutorial as I find the contextref not comprehensive enough and it really does not go into the caveats and use of all the options of the commands therein. My idea was to divide the section into basics and explanation of the options and advanced usage. Hope this helps. Keep up the good work. reagrds Keith. Am 29.09.2013 um 17:22 schrieb Mari Voipio :

...

Hello!

Inspired by some informal discussions at the recent ConTeXt meeting I started to write a *really* basic ConTeXt tutorial. 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.

I know already that there are a few things missing in the existing chapters, but I'd like to know if the document is any good and if the style is suitable for such a document. I've planned and written it out of my own experiences with ConTeXt, so maybe this document could become a My Way doc when it is finished (something public domain anyway).

Mari Voipio

1 Oct 1 Oct

12:30 a.m.

On Mon, Sep 30, 2013 at 10:35 AM, Keith J. Schultz wrote:

...

3) I could write up a tutorial for installing and TeXlive and Standalone if you care for one.

Maybe that should go on page http://wiki.contextgarden.net/Mac_Installation . While I'm used to the command line, I still picked TextMate because it was an easy way out. I've got MacTeX (=TeXlive) on my computer for occasional dabble with LaTeX and I rather like the editor (and it's free), but I didn't know that it can be configured to use ConTeXt Suite (=standalone) instead of having to make do with whatever version is in the package. So if you have time to edit that wiki page, I'm sure that would be appreciated! Mari

Mari Voipio

3:32 a.m.

Hi, I've now updated the file, trying to take all comments into account. The new file is in the old place, http://www.lucet.fi/pdfs/ctxbasics.pdf. Mari

Keith J. Schultz

2 Oct 2 Oct

4:51 a.m.

Hi Mari, All, I have redone/modified the Mac Installation page for Installing MacTeX, ConTeXt Standalone and TeXShop. Not quite finished, yet and needs polishing. Critic invited. regards Keth Am 01.10.2013 um 08:30 schrieb Mari Voipio :

...

On Mon, Sep 30, 2013 at 10:35 AM, Keith J. Schultz wrote:

...
3) I could write up a tutorial for installing and TeXlive and Standalone if you care for one.

Maybe that should go on page http://wiki.contextgarden.net/Mac_Installation . While I'm used to the command line, I still picked TextMate because it was an easy way out. I've got MacTeX (=TeXlive) on my computer for occasional dabble with LaTeX and I rather like the editor (and it's free), but I didn't know that it can be configured to use ConTeXt Suite (=standalone) instead of having to make do with whatever version is in the package.

So if you have time to edit that wiki page, I'm sure that would be appreciated!

Mari ___________________________________________________________________________________ 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 ___________________________________________________________________________________

Aditya Mahajan

5:28 a.m.

On Wed, 2 Oct 2013, Keith J. Schultz wrote:

...

Hi Mari, All,

I have redone/modified the Mac Installation page for Installing MacTeX, ConTeXt Standalone and TeXShop.

Not quite finished, yet and needs polishing.

Critic invited.

Minor correction. If you running the setup file using "sh first-setup.sh" then the previous step "chmod +x first-setup.sh" is not needed. Aditya

Keith J. Schultz

6:10 a.m.

Thanx for the pointer. Am 02.10.2013 um 13:28 schrieb Aditya Mahajan :

...

On Wed, 2 Oct 2013, Keith J. Schultz wrote:

...
Hi Mari, All,

I have redone/modified the Mac Installation page for Installing MacTeX, ConTeXt Standalone and TeXShop.

Not quite finished, yet and needs polishing.

Critic invited.

Minor correction. If you running the setup file using "sh first-setup.sh" then the previous step "chmod +x first-setup.sh" is not needed.

Aditya ___________________________________________________________________________________ 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 ___________________________________________________________________________________

john Culleton

1:16 p.m.

On Sun, 29 Sep 2013 18:22:02 +0300 Mari Voipio wrote:

...

Hello!

Inspired by some informal discussions at the recent ConTeXt meeting I started to write a *really* basic ConTeXt tutorial. 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.

I know already that there are a few things missing in the existing chapters, but I'd like to know if the document is any good and if the style is suitable for such a document. I've planned and written it out of my own experiences with ConTeXt, so maybe this document could become a My Way doc when it is finished (something public domain anyway).

Thank you,

Mari

Thus far you have a good effort. I would add at an early point the command: \setuppagenumbering[alternative=doublesided,location=] or similar. Most documents like books etc. are printed double sided. And page numbering is generally handled in the header. It is not obvious to newbies that double sided format is set up by a page numbering command. -- John Culleton Wexford Press Free list of books for self-publishers: http://wexfordpress.net/shortlist.html PDF e-book: "Create Book Covers with Scribus" available at http://www.booklocker.com/books/4055.html

3940

Age (days ago)

3943

Last active (days ago)

List overview

Download

13 comments

9 participants

participants (9)

Aditya Mahajan
john Culleton
Keith J. Schultz
Keith J. Schultz
Lars Huttar
Marco Patzer
Mari Voipio
Mica Semrick
Thangalin