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.