ConTeXt Manual Errata

* ConTeXt Manual Errata
@ 2013-09-18 19:53 Thangalin
  2013-09-21 17:15 ` Marco Patzer
  0 siblings, 1 reply; 25+ messages in thread
From: Thangalin @ 2013-09-18 19:53 UTC (permalink / raw)
  To: mailing list for ConTeXt users

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

Hi,

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

If anyone has plans to revise it, I have attached a file with corrections,
specific comments, and general comments. I did not have the ConTeXt manual
source code on hand, so I could not directly modify it.

Take the comments with a grain of salt: I have little ConTeXt experience. I
hope it proves useful.

Kindest regards.

[-- Attachment #1.2: Type: text/html, Size: 664 bytes --]

[-- Attachment #2: context-errata.txt --]
[-- Type: text/plain, Size: 9801 bytes --]

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?

The \defineenumeration[Question] creates a \Question command,
but \definehead[Procedure][section] does not create \Procedure command?
(Should the capital P not carry forward?)

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

What does the "of" in "\beginofAnswer" mean? Is it required? Where
does it come from? Why is it not simply "\beginAnswer"?

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

"The last example" -- does this refer to the previous example, or the
final example?

"The command \setupfootertexts, which we will discuss in detail in a later
chapter, has three arguments of which the first is optional. The first
argument defaults to [text]. Optional arguments are displayed as slanted
text." Can be: "The command \setupfootertexts, discussed in detail
chapter X, has three arguments. The first argument is optional as denoted
by slanted text, and has a default value of text."

"ConTeXt is able to keep track of the status of information on the
page, ..." is tersely written, "ConTeXt tracks status information per page,
such as the current chapter name."

Provide an immediate example of  arrow marks in a frame.

Section 1.4.
------------
"TeX does a lot" is "TeX performs many".

Document processing is best done by TeXexec -- is this still true? I thought
the "context" program supercedes TeXexec?

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

Section 1.5.
------------
TeX uses ASCII, but ConTeXt can use UTF-8. Is the information about ASCII a
bit misleading?

"ConTeXt fully supports PDFTeX, which means that you can generate PDF output
directly" can be written, "ConTeXt can produce PDF documents, because it fully
supports PDFTeX."

Section 1.6.1.
--------------
Still relevant with UTF-8?

Section 1.6.2.
--------------
Does \par hold true for ConTeXt? How would you use it? Show an example.

Section 1.6.3.
--------------
Avoid demonstrations that significantly reduce legibility.

Section 1.6.3.
--------------
"TeX is one of the few typesetting systems that does math typesetting right."
Can be: "TeX typesets mathmatical expressions correctly and beautifully."

"It does not hurt to know a bit about the basics of TeX, because that way one
can far more easilly write his or her own alternatives to, for instance,
chapter headers." Can be: "Knowing TeX basics allows developers and authors
to provide alternatives to default commands, such as chapter headers."

Section 1.6.4.
--------------
"Complete fontfamilies are" should be "Complete fontfamilies include".

Section 1.6.5.
--------------
"Characters have dimensions. Spacing between words and lines have dimensions.
These dimensions are related to one of the units of table 1.1. For example
the linespacing in this document is 14.83998pt." Can be: "Characters, spacing
between words (known as kerning), and spacing between lines have dimensions.
The line spacing in this document, for example, is 14.83998pt. Table 1.1
lists how dimensions relate."

Table 1.1 should split the "equivalent" column into two columns: "base" and
"equivalent", or be renamed to "equivalency". The millimeter might not be
necessary information (it is metric).

"Next to the mentioned dimension TeX also uses em and ex. Both are font
dependant." Better as: "In addition to the measures in Table 1.1, TeX uses
the font-dependent units of em and ex." (Note spelling mistake: dependant.)

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

Unknown list of commands -- why are they there? What do they do? Should
they be moved elsewhere?

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

Section 2.3.
------------
The \environment command should be introduced before it is used.

The bullet list should start with the word and then define it. For example,
"A *project* is a group of texts that belong together..."

The term "component" should be italicized like the other defined terms.

"Before a \start--\stop--pair commands can be added." Can be: "Commands
can be defined before a \start command."

The resolution process of searching for files in parent directories
is not clear. Use the 'tree' command (available for DOS/Unix) to show
an actual file and directory hierarchy. Make reference to section 2.4,
or eliminate the somewhat duplicate discussion about searching for
files altogether.

What would "componentonderdeel" translate to in English?

Introduce Table 2.1 (including the meaning of the stars and parenthetical
stars) prior to the table itself. Otherwise people will see the table and
need to read the subsequent page, then flip back to understand the table
again.

"The product teacher.tex (a teacher manual) can be defined as shown on the
opposite site." What does "opposite site" mean?

"In most cases working with only \starttext and \stoptext in combination
with \input or \enviroment is sufficient." Sufficient for what?

"A project structure has advantages when you have to manage a
great number of texts." Any project structure, or *this* project structure
in particular?

"it also enables you to process components independently" rewrite as:
"it also enables components to be processed independently."

"In principal" is a mistake; use: "In principle".

Figures 2.1, 2.2, and 2.3: enlarge the rectangles to avoid hyphenated words.

Provide an example of "localenvironment" -- it is unclear how the command
is meant to be used.

Section 2.4.
------------
Slightly confusing. The manual indicates that only parent directories are
scanned for referenced files to include. The example should discuss the
relationship between files in subdirectories (e.g., sheets.tex) and how
ConTeXt knows to include layout.tex. For example, would you compile 
sheets.tex inside the otherdoc directory? If so, how does sheets reference
layout.tex? What makes the "magic" happen? Is it the "project" command?

Show a small example of the relevant content for layout.tex and sheets.tex
that links the two files together.

Section 2.6.
------------
Is the texexc command deprecated? That is, is the preferred way to compile
a document now the "context" command?

"comma’s" is "commas".

"low level" is "low-level".

"dependant" is "dependent".

"the more flexible we are" should be rewritten, unless this is a subtle
reference to yoga. (That is, describe functionality in terms of the
ConTeXt processor, rather than in terms of people.)

A number of commands are on a page by themselves. They seem quite out
of place.

Section 3.1.
------------
"makes use of the actual" can be: "makes use of".

"This rather complex process makes it obvious that the output routine
actually makes use of more dimensions than" can be "This process of
typsetting an entire page, however, uses more than"

Section 3.2.
------------
"With the command \setuppapersize the dimensions of the paper being used
are defined" can be: "The \setuppapersize command specifies the paper's
dimensions."

Regarding "..,.1.,..", the meaning of ".." has not been defined before
use. Define what is meant by ".." prior to using it.

The word "DIN" is used before its definition. Add a definition for DIN
before use.

The words "envelop" and "envelope" are different in English and could
possibly use a note (or footnote) to indicate the actual size. The sizes
of DL and CD might not be familiar to all readers.

Section 3.3.
------------
Introduce "figure 3.1" with a full sentence. For example: Figure 3.1
shows the position of the header and footer as determined by...

Rename "picture 3.1" to "Figure 3.1" as per the previous suggestion.

Introduce the \setuplayout command prior to including the swath of
ConTeXt code for its definition.

"see chapter ??" is missing its cross-reference.

"and thereby visually separating those areas" becomes "thereby
visually separate those areas".

"In case of a two columned text the \textwidth is somewhat less
than half the makeupwidth" needs an explanation (likely because of a space
between the two columns, but that should be made clear). Also, makeupwidth
should have a backslash.

What are \dimen registers? How do you use them? Do you need to use
\dimen\textwidth? If not, then that should be clarified.

"In principal" is "In principle".

In figures 3.2 to 3.8 the right and left should be swapped? (That is, put the
left page to the left of the right page, and the right page to the right of
the left page...)

"The first three alternatives result in an undesired output." Alternatives
to what? Also, why is the output undesired? Why do we want to make the white
space stretch? (Probably for aesthetics, but that should be explicitly
stated.)

Section 3.7.
------------
A lot of new concepts are introduced at one time (fonts, figures, frames,
logo definition). Perhaps simplify the logo to simply an image, or framed
text, or only one of those items. Then use a couple of examples to build
on these concepts. Alternatively, introduce all the items used in the logo
a little earlier (e.g., setupframed).

General Suggestions
===================

Indent the ConTeXt code fragments

Give ConTeXt code fragments numbers and refer to them by number.

Having two different page numbers is confusing.

[-- Attachment #3: 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
___________________________________________________________________________________

^ permalink raw reply	[flat|nested] 25+ messages in thread