Reference Manual Project

Reference Manual Project

[Taco Hoekwater]

Hi all,

Following the discussion with Gerben over the past week, I have 
initialized a project for the creation of a new Context Reference
Manual.

The goal is to create a complete manual documenting all of context's
user-level commands with the focus on creating a reference manual,
but not so much on providing a learner's manual.

Anybody who is willing and able to help out in any way is very much
invited to join in. The manual is to be distributed under the GNU Free
Document License so that it can borrow text from the wiki, and also so
that it can be included in free TeX distributions (like TeX Live).

I have merged and checked in tex sources of a few base manuals just
to get started. The sources are part of the contextman project at
supelec: http://foundry.supelec.fr/projects/contextman . There are
no released files yet (that would be premature), but you can browse
the repository via the SCM tab at supelec's project page.
Alternatively, if you have a subversion client, check out the source
tree to a local folder.

There is also a mailing list, see
   http://lists.foundry.supelec.fr/mailman/listinfo/contextman-reference
for details

The current source tree in the repository is basically the english
version of the 'Context Manual' plus

   * Fonts                 (mfonts.tex)
   * Columns sets          (columns.tex)
   * Processing modes      (mmodes.tex)
   * Texmfstart            (mtexmfstart.tex)
   * Hyphenation patterns  (mpattern.tex)

but minus the images and using a simplified layout design.

The project needs volunteers for just about everything:
   * merging existing manuals and wiki pages
   * copy-editing
   * writers for new chapters
   * proofreaders
   * it could also do with a nicer design

so if you want to help out in any way, please subscribe to the mailing
list via the link above (I don't want to overburden ntg-context with
messages on this subject).


Best wishes,
Taco

___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[John Devereux]

Taco Hoekwater <taco@elvenkind.com> writes:

> Hi all,
>
> Following the discussion with Gerben over the past week, I have 
> initialized a project for the creation of a new Context Reference
> Manual.
>
> The goal is to create a complete manual documenting all of context's
> user-level commands with the focus on creating a reference manual,
> but not so much on providing a learner's manual.

Hi,

I just wanted to say that I think this is a great idea. I do not think
the situation is as bad as Gerben states. But I too have been
frustrated at the anachronisms and ommissions from the reference
manual.

One thing extra I would ask for is that parameters be actually
*explained*, as well as simply listed, for each command. Perhaps a
hyperlink to a generic explanation page if they are "too trivial".

> Anybody who is willing and able to help out in any way is very much
> invited to join in. The manual is to be distributed under the GNU Free
> Document License so that it can borrow text from the wiki, and also so
> that it can be included in free TeX distributions (like TeX Live).

I hope this means it can be part of Debian - I gather this implies not
having any "invariant sections":
<http://en.wikipedia.org/wiki/GNU_Free_Documentation_License#Invariant_sections>

[...]

> so if you want to help out in any way, please subscribe to the mailing
> list via the link above (I don't want to overburden ntg-context with
> messages on this subject).

-- 

John Devereux
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Taco Hoekwater]

John Devereux wrote:
> 
> One thing extra I would ask for is that parameters be actually
> *explained*, as well as simply listed, for each command. Perhaps a
> hyperlink to a generic explanation page if they are "too trivial".

Yes, that has been bothering more people (indeed even myself,
sometimes).

>> Anybody who is willing and able to help out in any way is very much
>> invited to join in. The manual is to be distributed under the GNU Free
>> Document License so that it can borrow text from the wiki, and also so
>> that it can be included in free TeX distributions (like TeX Live).
> 
> I hope this means it can be part of Debian - I gather this implies not
> having any "invariant sections":

Yes, I hope so too. There are no invariant sections nor cover texts,
and no commercial fonts are used either.

Best wishes,
Taco
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Hans Hagen]

John Devereux wrote:

>> Anybody who is willing and able to help out in any way is very much
>> invited to join in. The manual is to be distributed under the GNU Free
>> Document License so that it can borrow text from the wiki, and also so
>> that it can be included in free TeX distributions (like TeX Live).

the last of my worries since their rules might change anyway (things 
like 'include source' which then might include sources of sources of 
sources where in practice a pdf would be fine too

> I hope this means it can be part of Debian - I gather this implies not
> having any "invariant sections":
> <http://en.wikipedia.org/wiki/GNU_Free_Documentation_License#Invariant_sections>

the usual licencing mess ... personally i think that we should not be 
too strict (i.e. no enless pages with unreadable licence texts when a 
url can do) and no restrictions on using snippets other than a simple 
reference to the original (unless one is part of the authoring team 
since it makes no sense to refer to your own stuff)

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
      tel: 038 477 53 69 | fax: 038 477 53 74 | www.pragma-ade.com
                                              | www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Taco Hoekwater]

Hi all,

Taco Hoekwater wrote:
> Hi all,
> 
> Following the discussion with Gerben over the past week, I have 
> initialized a project for the creation of a new Context Reference
> Manual.

After 10 days of fairly heavy editting, I can now show you the
first useful product of this project: an updated and extended
version of the 'Typography' chapter of the big manual.

To make it easy for you to download and read, there is a checked out
version of that manual (and its source) here:

   http://context.aanhet.net/svn/contextman/context-reference/en/

direct link to the typography chapter's pdf:
 
http://context.aanhet.net/svn/contextman/context-reference/en/co-typography.pdf

As this is a first attempt, corrections and suggestions are very
welcome. The next goal will be the creation of a chapter that deals
with font installation and definitions.

Best wishes,
Taco
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Yue Wang]

Hi, Taco:

> direct link to the typography chapter's pdf:
>
> http://context.aanhet.net/svn/contextman/context-reference/en/co-typography.pdf


Very cool and useful, Thank you!

Yue Wang
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Henning Hraban Ramm]

Am 2008-08-10 um 16:24 schrieb Taco Hoekwater:

> http://context.aanhet.net/svn/contextman/context-reference/en/co-typography.pdf
>
> As this is a first attempt, corrections and suggestions are very
> welcome. The next goal will be the creation of a chapter that deals
> with font installation and definitions.

Thank you! I learned something new.
But I'd also like to suggest a few changes:

Table 1.1 is not clear to me:
- I don't understand what you want to say - that the "same" font face  
may have different names in different font families, like  
Roman=Normal=Regular? Roman=Antiqua isn't true for a lot of fonts,  
"Helvetica Roman" is just the Regular face.
- Shouldn't the middle column use the same size as the other two, but  
sans serif?
- Why do you center the columns?

Perhaps explain that "pt" means "point" and is 1/72 inch.

In 1.2 etc. perhaps use italics instead of slanted as example -  
typographically "slanted" is a monstrosity.

Your (or ConTeXt's) definition of typographical terms is a bit unusual:
usual(?) vs. ConTeXt
clan(?)	family
family	style(s)
face	alternative

i.e.
- Computer Modern is a "font clan" (in German: Schriftsippe), some  
fonts of different styles that are designed to work together
- Computer Modern Sans is a font family (in German: Schriftfamilie or  
just Schrift), a collection of several faces; in old Mac terms a  
"suitcase"
- ... bold is a font face (in German: Schriftschnitt ("cut")), or just  
a font (file)

Perhaps you could *all* font switches in one table, maybe as an  
appendix.

Sorry, I didn't read the whole thing, no time.


Greetlings from Lake Constance!
Hraban
---
http://www.fiee.net/texnique/
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)

___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[John Devereux]

Taco Hoekwater <taco@elvenkind.com> writes:

> Hi all,
>
> Taco Hoekwater wrote:
>> Hi all,
>> 
>> Following the discussion with Gerben over the past week, I have 
>> initialized a project for the creation of a new Context Reference
>> Manual.
>
> After 10 days of fairly heavy editting, I can now show you the
> first useful product of this project: an updated and extended
> version of the 'Typography' chapter of the big manual.
>
> To make it easy for you to download and read, there is a checked out
> version of that manual (and its source) here:
>
>    http://context.aanhet.net/svn/contextman/context-reference/en/
>
> direct link to the typography chapter's pdf:
>  
> http://context.aanhet.net/svn/contextman/context-reference/en/co-typography.pdf
>
> As this is a first attempt, corrections and suggestions are very
> welcome. The next goal will be the creation of a chapter that deals
> with font installation and definitions.

Thanks for this, it is great to see this new (to me) stuff. I have
read the context manual so many times, it is nice to see it evolving
at last.

Possible corrections: 

  - p32, I can't see the difference between the two "protruding"
    examples. (Or the hz ones for that matter!).

  - As a native English speaker the word "handlings" looks strange at
    first (as if it is a mistake). But after reading it a few times I
    am growing to like it.

-- 

John Devereux
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Yue Wang]

Hi:


>
>  - p32, I can't see the difference between the two "protruding"
>    examples. (Or the hz ones for that matter!).

Yes, I reported this problem to Taco 3 or 4 hours ago in a private mail.
I previously thought I was wrong and just one of the ``average
reader'' described in the section.
Your mail makes me sure that I am not alone!

Yue Wang
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Martin Schröder]

2008/8/10 Henning Hraban Ramm <hraban@fiee.net>:
> Perhaps explain that "pt" means "point" and is 1/72 inch.

Is it? In TeX pt is 1/72.27 and 1/72 is bp.

Best
   Martin
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Taco Hoekwater]

Hi all,

Henning Hraban Ramm wrote:
> Am 2008-08-10 um 16:24 schrieb Taco Hoekwater:
> 
>> http://context.aanhet.net/svn/contextman/context-reference/en/co-typography.pdf

There is a new version now, same location. Response to other messages:

* The two identical paragraphs in the "hz" section were an error in the
   source, now they really are different.

* "handlings" is weird, I know. The problem is that I am not a native
   English speaker  and I can't seem to come up with a reasonable
   (short!) wording for "the collection of named computing objects that
   alter the font handling".

>> As this is a first attempt, corrections and suggestions are very
>> welcome. The next goal will be the creation of a chapter that deals
>> with font installation and definitions.
> 
> Thank you! I learned something new.
> But I'd also like to suggest a few changes:

> Table 1.1 is not clear to me:

I tried to make this more clear by altering both text and table a little.

> Perhaps explain that "pt" means "point" and is 1/72 inch.

Ok, did that.

> In 1.2 etc. perhaps use italics instead of slanted as example -  
> typographically "slanted" is a monstrosity.

Did that too.

> Your (or ConTeXt's) definition of typographical terms is a bit unusual:
> usual(?) vs. ConTeXt
> clan(?)	family
> family	style(s)
> face	alternative

Unusual, yes.  But hard to alter, because this is the terminology that
context has used for over a decade now. The current english names are
about what you get if you translate the correct dutch typographical
terms into english literally, btw.

> i.e.
> - Computer Modern is a "font clan" (in German: Schriftsippe), some  
> fonts of different styles that are designed to work together

I've seen "super family" and "collection",  but this is the first time
ever I heard the word "font clan" (I knew about Schriftsippe).

> - ... bold is a font face (in German: Schriftschnitt ("cut")), or just  
> a font (file)

This one is pretty harmless, in my opinion. "alternative" is not
actually confusing, just a little abnormal/

I could use "font class" instead of "typeface" in the manual, that
would help alleviate at least one source of confusion and because
the use of 'typeface' in context is fairly new, it should be ok.
It makes the \definetypeface macro name appear at bit funny, but
that is not a big deal (there are more funny macro names, anyway).

The big problem is family vs. style, and I do not dare to change it:
that would render all already released font documentation useless.

> Perhaps you could *all* font switches in one table, maybe as an  
> appendix.

Commands like \ss, \bf \ssbf etc. you mean? that list is open-ended ...

> Sorry, I didn't read the whole thing, no time.

Thanks for your comments,
Taco
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Henning Hraban Ramm]

Am 2008-08-11 um 13:08 schrieb Taco Hoekwater:
>> Table 1.1 is not clear to me:
>
> I tried to make this more clear by altering both text and table a  
> little.

Thanks, *much* better!

>
>> Perhaps explain that "pt" means "point" and is 1/72 inch.
> Ok, did that.

And I guess Martin is right WRT pt vs. bp

>> In 1.2 etc. perhaps use italics instead of slanted as example -
>> typographically "slanted" is a monstrosity.
> Did that too.

Thank you!

>> Your (or ConTeXt's) definition of typographical terms is a bit  
>> unusual:
>> usual(?) vs. ConTeXt
>> clan(?)	family
>> family	style(s)
>> face	alternative
>
> Unusual, yes.  But hard to alter, because this is the terminology that
> context has used for over a decade now. The current english names are
> about what you get if you translate the correct dutch typographical
> terms into english literally, btw.

ok; of course stay with ConTeXt's terminology, but perhaps explain  
that to those who know other terms.

>
>> i.e.
>> - Computer Modern is a "font clan" (in German: Schriftsippe), some
>> fonts of different styles that are designed to work together
>
> I've seen "super family" and "collection",  but this is the first time
> ever I heard the word "font clan" (I knew about Schriftsippe).

...if you translate the correct german term into englishh  
literally... ;-)
That's why I used quotes.

>> - ... bold is a font face (in German: Schriftschnitt ("cut")), or  
>> just
>> a font (file)
>
> This one is pretty harmless, in my opinion. "alternative" is not
> actually confusing, just a little abnormal/
>
> I could use "font class" instead of "typeface" in the manual, that
> would help alleviate at least one source of confusion and because
> the use of 'typeface' in context is fairly new, it should be ok.
> It makes the \definetypeface macro name appear at bit funny, but
> that is not a big deal (there are more funny macro names, anyway).
>
> The big problem is family vs. style, and I do not dare to change it:
> that would render all already released font documentation useless.

see above: any terminology is good, if it is consistent and well  
defined/explained.

>> Perhaps you could *all* font switches in one table, maybe as an
>> appendix.
>
> Commands like \ss, \bf \ssbf etc. you mean? that list is open- 
> ended ...

You're right. I meant something like in
http://wiki.contextgarden.net/Basic_Text_Formatting
but perhaps that belongs in some other manual.

BTW in LilyPond there's a multilingual glossary, perhaps we should  
start such, too? We often get confusion with technical terms. And at  
least in German there's currently not even a technical dictionary for  
the print/design industries.


Greetlings from Lake Constance!
Hraban
---
http://www.fiee.net/texnique/
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)

___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Hans Hagen]

Henning Hraban Ramm wrote:

> BTW in LilyPond there's a multilingual glossary, perhaps we should  
> start such, too? We often get confusion with technical terms. And at  
> least in German there's currently not even a technical dictionary for  
> the print/design industries.

good idea, perfect for a wiki page

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
      tel: 038 477 53 69 | fax: 038 477 53 74 | www.pragma-ade.com
                                              | www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Reference Manual Project

[Henning Hraban Ramm]

Am 2008-08-11 um 21:44 schrieb Hans Hagen:

> Henning Hraban Ramm wrote:
>
>> BTW in LilyPond there's a multilingual glossary, perhaps we should
>> start such, too? We often get confusion with technical terms. And at
>> least in German there's currently not even a technical dictionary for
>> the print/design industries.
>
> good idea, perfect for a wiki page

Ok, I started it:
http://wiki.contextgarden.net/Dictionary

I was surprised that there's already a "Glossary", but that should  
stay like an index, i.e. to find subjects, not translations.




Greetlings from Lake Constance!
Hraban
---
http://www.fiee.net/texnique/
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)

___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________