Re: general suggestion for ConTeXt documentation

[Pablo Rodriguez <oinos@gmx.es>]

On 08/08/2018 12:40 AM, Robert Zydenbos wrote:
> That is it. I have no idea why – but that is the solution.

Dear Robert,

I will try to explain the reason of this (in my very limited
understanding of how ConTeXt works).

Notes in both MkII and MkII have two setup commands. One is for the
group of notes and the other is for each individual note.

This is why configuring notes might be tricky sometimes. Some options
belong to \setupnote and some to \setupnotedefinition (or \setupnotation
in MkIV).

> (For all readers:)

I hope I’m also included 😉.

Your example is a very special one. I mean, notes have two setup
commands and you are using MkII.

We already know you need support for Indic scripts (is Kannada the
language you need?).

I wonder whether we could do something to improve the situation in MkIV.

> ConTeXt is great. Let me make that clear right way. I think it's the
> future of TeX. I'm already doing things in ConTeXt that I dread
> trying to do in LaTeX or any other system. But (yes, of course there
> was a 'but' coming) the one thing that is missing, the one obstacle
> which I think exists for ConTeXt gaining wider currency, is really
> good documentation.

I moved from LaTeX to ConTeXt a decade ago. Back then, I also thought
that ConTeXt needed better documentation.

In the meanwhile, I realized that there are more things in heaven and
earth, that were dreamt in my philosophy. I mean, ConTeXt involves much
more than I thought.

Hans explained in the list why general documentation is not his task:
https://mailman.ntg.nl/pipermail/ntg-context/2010/047500.html.

As an introduction to that, you can read my own take on the matter:
https://mailman.ntg.nl/pipermail/ntg-context/2017/090111.html.

In short, users have to write the general documentation about ConTeXt.
Or at least, we cannot expect (I’m not saying that you imply this) that
Hans develops both ConTeXt and LuaTeX, replies many questions in too
many mailing lists, writes technical documentation for both softwares
and also writes introductory manuals.

> Take this last question of mine which Pablo solved: I had to put a
> certain parameter in \setupnotedefinition [footnote]. First I did it
> wrongly, putting it in \setupnote [footnote] (why? because the names of
> the values, like 'location', look so much alike). So what goes into
> \setupnotedefinition and what goes into \setupnote? How do I know?

Welcome to the club. I mean, I also had my problems understanding why
notes were so complex to setup.

For MkIV (as Alan mentioned), you have
tex/texmf-context/tex/context/interface/mkiv/i-context.pdf.

For MkII, there seems to be no document for the English interface (at
least, in tex/texmf-context/tex/context/interface/mkii). I might be
wrong here, since I only used MkII for your notes.

> (How does Pablo know this? Maybe he can tell me off-list. :-) )

Who says I knew it? I simply searched in the source.

I know that \setupnotations[alternative=serried] is the command in MkIV.

So I grepped for "serried" in tex/texmf-context/tex/context/base/mkii/.

It took me a while to realize that strc-lnt.mkii had exactly the key I
was looking for (on line 109).

I must confess, if I hand’t find this line, I wouldn’t have been able to
give an answer from what I read in strc-not.mkii.

> Many of the commands are not, or badly, documented in the otherwise useful Wiki.

The wiki is written by users. I don’t know whether it is useful to add
MkII information to the wiki, but updating the wiki

> What are all the parameters that are recognized by the various
> commands, and just what do they mean? What are the default settings?

See above for that list.

> ConTeXt looks like an object oriented programming language with
> inheritances, but it is unclear just what is inherited from where,
> and why.

I don’t code, but I wonder whether this is more complex. ConTeXt MkII is
a macro package programmed in TeX (which is a typographical programming
language). ConTeXt MkIV adds Lua.

For a more complete description,
http://www.pragma-ade.com/general/manuals/what-is-context.pdf.

> I appreciate all the effort made by various people to provide
> documentation and demos. But I think the cause of ConTeXt would be
> greatly served if someone would bring out a hierarchic list of the
> ConTeXt commands with a brief description of what the commands and the
> parameters do and why they exist at all, so that the reader gets an idea
> of the structure of the whole system and the philosophy behind it (i.e.,
> explaining why it is thus structured and why it works).
> 
> Once again: I think ConTeXt is great, and so is this forum, which is
> a huge help. I also realize ConTeXt is complex and that the great
> people behind it also have other things to do in life. But still:
> maybe the kind of documentation I propose would help to make things
> still a bit greater?

The question for such a document would be how many users might benefit
from it.

I mean, ConTeXt is a huge task (support for Kannada is one of the many
features we would like to have implemented in it) and writing such a
document is not a minor task.

And the users? Well, I’m afraid that there are two kinds of them, when
related to this issue. One group of users may be able to understand such
a document, but they won’t need it, because they already have the
knowledge explained on it. The other group of users won’t be able to
understand such a document, because they lack have the required
background. (Not everyone is able to code 🙄.)

Let me finish with a personal experience. One of the most useful
features in ConTeXt is dealing directly with XML sources as input.

There is a document (written by Hans) explaining XML in ConTeXt:
tex/texmf-context/doc/context/documents/general/manuals/xml-mkiv.pdf.

Needless to say that I don’t understand every single feature explained
on it. And it took me a while to understand the very basics.

Does it mean it isn’t well written? The document is perfectly fine,
assuming that it is technical documentation. An introductory document to
xml-mkiv.pdf would be fine, but it should be written by another person
that Hans himself.

Just in case it might help,

Pablo
-- 
http://www.ousia.tk
___________________________________________________________________________________
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://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________