Re: Microtype in ConTeXt

Re: Microtype in ConTeXt

[Michael Saunders]

> On 27-3-2010 1:15, Yan Zhou wrote:
>
>> As I can see now ConTeXt is indeed a far more advanced system than LaTeX. But I have one more query. Where can I find the documents. When following these replies and some other messages in the list, I find some commands not documented in the Manual or Reference Manual. In LaTeX, all commands are detailed documented in source2e.tex, in TeX, The TeXBook explains everything. So in ConTeXt, where can I find such detailed documents. I tried the documented source, but it is more like a PDF version or source with only a little documentation.
>
> as most of the functrionality does not change you can use older docs
> (website, wiki etc) for most cases
>
> newer things i.e. introduced in mkiv using luatex are described in for
> instance mk.pdf and articles
>
> of course the wiki is a good source as well


Notice that Yan Zhou isn't complaining that the docs are old.   Our
problem is that they are sketchy and rambling, bits and pieces of this
and that without any systematic explanations.  Often they are just
some unexplained code samples that communicate nothing (unless you
happen to be the guy who invented the language).   I can't think of
one command that is fully explained along with all its possible
parameters.   The wiki is better written, but even less complete.   It
might not be possible to do better, but this is a huge obstacle to
anyone who actually wants to use ConTeXt.  The docs hint at a lot of
features that sound better than LaTeX, but actually getting them to
work is a different story.
___________________________________________________________________________________
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
___________________________________________________________________________________

docs (was: Re: Microtype in ConTeXt)

[Peter Münster]

On Sat, Mar 27 2010, Michael Saunders wrote:

> Notice that Yan Zhou isn't complaining that the docs are old.   Our
> problem is that they are sketchy and rambling, bits and pieces of this
> and that without any systematic explanations.  Often they are just
> some unexplained code samples that communicate nothing (unless you
> happen to be the guy who invented the language).   I can't think of
> one command that is fully explained along with all its possible
> parameters.   The wiki is better written, but even less complete.   It
> might not be possible to do better, but this is a huge obstacle to
> anyone who actually wants to use ConTeXt.  The docs hint at a lot of
> features that sound better than LaTeX, but actually getting them to
> work is a different story.

Hello Michael,

See also here:
http://archive.contextgarden.net/message/20100308.123128.f65942c8.en.html

Cheers, Peter

-- 
Contact information: http://pmrb.free.fr/contact/


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

Re: docs (was: Re: Microtype in ConTeXt)

[Arthur Reutenauer]

> That may be the problem!

For what it's worth, I agree with you, Michael.  ConTeXt developers seem to be
unable to express their ideas clearly.  It's sad to see such deficient
communication skills, and it's to be expected that if they go on all their
knowledge is going to be lost.
        
You're right, again, and I thank you for pointing this simple fact that, alas,
only a few have noticed until now.  Hopefully we will see better than
unintelligible scribbles being passed out as documentation in the future.

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

docs (was: Re: Microtype in ConTeXt)

[Michael Saunders]

Peter, that post of Hans's mainly argues that the old manual is good
enough and then goes on to talk about development.  For example:

"Even an old manual can quite well describe functionality as much
didn't change."

It can if it ever did.  I don't think cont-eni.pdf etc., describe the
functionality well at all.

"As one can visually get all kind of output and as
typographical elements can interfere the ultimate manual would
show $n!$ variants and become quite unreadable. There is no easy
way out of this. "

There is:  describe each option concisely and abstractly, then you
need only be concerned with $n$ elements.  Almost every LaTeX package
manages to do this successfully, and they are very usable.

"More documentation would not help all users. "

There needn't be more.  It needn't be lengthy, just clear, complete,
and concise.

"There are quite some options that were never meant for
usage beyond our own, but as we ship the full product, they become
visible. No, they are not documented apart from the source. Yes,
if useful they should be documented but why by me? "

Because you are probably the only person on earth who understands
them.  Getting that knowledge out of your head and into others' will
require an act of communication.

"I only work on a manual (or article or whatever) if it's fun to do."

That may be the problem!

Hans, Here are some constructive suggestions.  I hope you take them seriously:

If you ever write another manual, perhaps when MKIV is complete,

1.  Start from scratch.  Throw away the old material.

2.  Forbid yourself the use of code examples.  They are a crutch which
impedes communication.  First, write the whole manual with normal,
abstract, expository prose.  When it's complete and explains
everything fully---when it {\em makes sense}--- {\em then} illustrate
it with as many code samples as you like.

3.  Have a standard format, a sort of checklist, for what must be said
about each argument, parameter, command and group of commands:
---What is its function?
---How is it used?
---What is it used for (what effect is it supposed to achieve)?
---What are the options?
A regular format like this will make it much easier on you.  You'll
have a regular structure that you simply have to fill in.  It might
even make the task more fun.

4.  Get someone to serve as an editor.

These will solve most of your writing problems.  I look forward to a
new manual someday.

Thanks,

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