Re: ConTeXt Manual Errata

From: Marco Patzer <lists@homerow.info>
To: ntg-context@ntg.nl
Subject: Re: ConTeXt Manual Errata
Date: Sat, 21 Sep 2013 19:15:01 +0200	[thread overview]
Message-ID: <20130921171501.GG17308@homerow> (raw)
In-Reply-To: <CAANrE7piiXAXGdQFjKaCpF7a6L6mxvSWeAk6OsC4jecJGWWxJw@mail.gmail.com>

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

On 2013–09–18 Thangalin wrote:

Hi Dave,

> During a recent plane ride, I started to read the ConTeXt manual
> to get a better understanding:
> http://www.ctex.org/documents/context/cont-enp.pdf

A more recent manual can be found at

  http://pmrb.free.fr/contextref.pdf

> If anyone has plans to revise it,

I assume everybody on this list had at some point plans to revise
the manual(s). Due to lack of time this has never happened.

> I have attached a file with corrections, specific comments, and
> general comments.

Thanks a lot for the corrections and suggestions.

> I did not have the ConTeXt manual source code on hand, so I could
> not directly modify it.

  http://wiki.contextgarden.net/Improving_the_manuals

Do not count on someone else to fix it. Create an account and fix
what you think could be improved, especially the grammar and
spelling mistakes. If you're unsure about something, write a mail to
the manual mailing list¹ for questions about the manual (style,
layout, etc.) or this list for everything else.

Note: The manual has not been updated since a while and it's broken
at the moment. I'll prepare a fix soon, so it will compile with a
recent MkIV.

> Take the comments with a grain of salt:

Take the existing manuals with a grain of salt ;)

> ConTeXT Manual Errata & Suggestions
> ===================================
> 
> Section 1.3.
> ------------
> The word "something" needs to be defined before it is used.
> For example, "\setupsomething" <- What does "something" mean?

A placeholder like foobar or whatever. I think it's clear from the
context, otherwise feel free to define it.

> The \defineenumeration[Question] creates a \Question command,
> but \definehead[Procedure][section] does not create \Procedure command?

It does:

\definehead [Procedure] [section]
\starttext
  \Procedure{something}
\stoptext

However, I'd suggest to instead use:

\startProcedure [title=something]
  …
\stopProcedure

> The \startnarrower requires an explanation on how it affects the
> resulting document. Likewise \startitemnize.

Feel free to add some info from the wiki.

  http://wiki.contextgarden.net/Command/startnarrower
  http://wiki.contextgarden.net/Enumerations

> What does the "of" in "\beginofAnswer" mean? Is it required?

It's not required. It's actually wrong.

> Where does it come from? Why is it not simply "\beginAnswer"?

MkII maybe?

> "Figure 1.1 is typeset this way" should include the page number.

That's more difficult than it seems to be. The manual is available
in different paper sizes and formats. This means the page number
can't be coded as \in{figure}[foo] on \at{page}[foo], since the
figure might end up on the same page. As far as I know ConTeXt does
not have a general mechanism for automatically placing the “on
page…” string if the reference is not on the current page. \atpage
comes close, though.

> Document processing is best done by TeXexec -- is this still true?

Well, your manual is from 2000.

> I thought the "context" program supercedes TeXexec?

yes

> Describe the relationship between TeX and ConTeXt. For example, why do the
> subsequent sections discuss TeX examples?

ConTeXt uses TeX and the following sections introduce some TeX
concepts that hold true for ConTeXt as well.

> Section 1.9.
> ------------
> Relatively empty page.

On purpose. The reader is invited to take a break and grab a coffee. ;)

> Section 2.2.
> ------------
> "It is advisable to type the document setups before the \start--command," --
> What start command? \starttext, perhaps?

\starttext, \startdocument, \startcomponent, etc.

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
___________________________________________________________________________________