State of documentation of ConTeXt?

State of documentation of ConTeXt?

[Gerben Wierda]

Hello guys,

I am restarting a book project I started a several years back. At that time I set up a copy of another project I am working on in ConTeXt, so with the products/environment/chapters structure, added Mac fonts to my setup, using texexec for compilation.

Now that I am restarting, I am returning to ConTeXt. The first thing I did was go to contextgarden and look for updated documentation. What I found was the over 10-year old documentation (contextref.pdf) with green boxes stating things like “TODO: Add some text about recent developments, especially the split between mkii and mkiv”.

Is there up-to-date and reasonably complete ConTeXt documentation these days?

G
___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Rob Heusdens]

Hello G / all

I started using ConText about a year ago. But as a "novice" to Context
(and Tex in general) I can say is that this would be the first thing to
work on, because currently it is a bit of a pain to start using ConText in
any serious way, because there is a lack of up-to-date documentation.

The mailing list here does make a good contribution to explaining things
(I did not use it before, but while the Contextgarden was offline for a
while last week, this was the only place for getting needed info) that the
documentation and contextgarden wiki misses.

But I think a regular user would want to have up-to-date documentation,
and many examples worked out and a whole bunch of ready to use (well
documented) templates/start documents for all kinds of use-cases.

The contextgarden wiki often does not provide well enough information.

There are commands with over 20 different parameters, and the most of them
are not documented at all. So, a novice user can only use the commands in
a trivial sense, but for advanced use the command provides, there is no
documentation on how it is supposed to work.

This is a pitty, because the ConText distribution really offers a lot of
features one want for avanced typesetting jobs, but too often one wants to
understand the behaviour of some command or use the advanced options which
are provided, but can't because the documenation is too poor to make sense
of it.

To look in the source is not a a good replacement for that I guess (only
for advanced users which co-develop ConText).

Well at least the mailing list provides the answers one wants, but it
would be far better I guess if such information would be up-to-date on
contexgarden.

Can we make this a feature request with HIGH priority?

Greetings,

Rob.


> Hello guys,
>
> I am restarting a book project I started a several years back. At that
> time I set up a copy of another project I am working on in ConTeXt, so
> with the products/environment/chapters structure, added Mac fonts to my
> setup, using texexec for compilation.
>
> Now that I am restarting, I am returning to ConTeXt. The first thing I did
> was go to contextgarden and look for updated documentation. What I found
> was the over 10-year old documentation (contextref.pdf) with green boxes
> stating things like “TODO: Add some text about recent developments,
> especially the split between mkii and mkiv”.
>
> Is there up-to-date and reasonably complete ConTeXt documentation these
> days?
>
> G
> ___________________________________________________________________________________
> 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
> ___________________________________________________________________________________
>


___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Hans Hagen]

On 7/14/2014 3:03 PM, Rob Heusdens wrote:
> Hello G / all
>
> I started using ConText about a year ago. But as a "novice" to Context
> (and Tex in general) I can say is that this would be the first thing to
> work on, because currently it is a bit of a pain to start using ConText in
> any serious way, because there is a lack of up-to-date documentation.
>
> The mailing list here does make a good contribution to explaining things
> (I did not use it before, but while the Contextgarden was offline for a
> while last week, this was the only place for getting needed info) that the
> documentation and contextgarden wiki misses.
>
> But I think a regular user would want to have up-to-date documentation,
> and many examples worked out and a whole bunch of ready to use (well
> documented) templates/start documents for all kinds of use-cases.
>
> The contextgarden wiki often does not provide well enough information.
>
> There are commands with over 20 different parameters, and the most of them
> are not documented at all. So, a novice user can only use the commands in
> a trivial sense, but for advanced use the command provides, there is no
> documentation on how it is supposed to work.
>
> This is a pitty, because the ConText distribution really offers a lot of
> features one want for avanced typesetting jobs, but too often one wants to
> understand the behaviour of some command or use the advanced options which
> are provided, but can't because the documenation is too poor to make sense
> of it.
>
> To look in the source is not a a good replacement for that I guess (only
> for advanced users which co-develop ConText).
>
> Well at least the mailing list provides the answers one wants, but it
> would be far better I guess if such information would be up-to-date on
> contexgarden.
>
> Can we make this a feature request with HIGH priority?

quite some sub-systems are described in their own manuals (fonts, 
tables, xml, ...) and these manuals are quite up to date (and easier to 
maintain than one big fat manual

also, additional documentation is something that users need to 
participate in (just pick a topic)

even if it has high priority, that doesn't mean that those involved have 
much free time left to do that next to their regular work (as usual most 
development is done in spare time)

so, patience is needed,

Hans

>> Hello guys,
>>
>> I am restarting a book project I started a several years back. At that
>> time I set up a copy of another project I am working on in ConTeXt, so
>> with the products/environment/chapters structure, added Mac fonts to my
>> setup, using texexec for compilation.
>>
>> Now that I am restarting, I am returning to ConTeXt. The first thing I did
>> was go to contextgarden and look for updated documentation. What I found
>> was the over 10-year old documentation (contextref.pdf) with green boxes
>> stating things like “TODO: Add some text about recent developments,
>> especially the split between mkii and mkiv”.
>>
>> Is there up-to-date and reasonably complete ConTeXt documentation these
>> days?
>>
>> G
>> ___________________________________________________________________________________
>> 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
>> ___________________________________________________________________________________
>>
>
>
> ___________________________________________________________________________________
> 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
> ___________________________________________________________________________________
>


-- 

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
     tel: 038 477 53 69 | voip: 087 875 68 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  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: State of documentation of ConTeXt?

[Gerben Wierda]

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

On 14 Jul 2014, at 19:29, Hans Hagen <pragma@wxs.nl> wrote:

> quite some sub-systems are described in their own manuals (fonts, tables, xml, ...) and these manuals are quite up to date (and easier to maintain than one big fat manual
> 
> also, additional documentation is something that users need to participate in (just pick a topic)
> 
> even if it has high priority, that doesn't mean that those involved have much free time left to do that next to their regular work (as usual most development is done in spare time)
> 
> so, patience is needed,

I like ConTeXt (still do, I liked its approach when I first encountered it). But the project is more the ongoing private tinkering of a small in-crowd (that communicates with some followers).

ConTeXt is managed a bit like a small group of researchers sharing a couple of complex and undocumented models/programs and tinkering with them as they go along. It’s an activity without formal design, but with a lot of trial-and-error/testing.

Given that status (and the fact that it has had that status for over a decennium), I don’t expect it to ever become a serious product that is (semi-)professionally managed. I prefer content over management every day, but something like this needs some minimal management. That requires both time (=money) and capabilities. Besides, the tinkering researchers may not be inclined to do that, they want to tinker.

BTW, you can’t be serious asking the users to provide the documentation, can you?

G


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

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

Re: State of documentation of ConTeXt?

[Mojca Miklavec]

On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda wrote:
>
> I like ConTeXt (still do, I liked its approach when I first encountered it).
> But the project is more the ongoing private tinkering of a small in-crowd
> (that communicates with some followers).
>
> ConTeXt is managed a bit like a small group of researchers sharing a couple
> of complex and undocumented models/programs and tinkering with them as they
> go along. It’s an activity without formal design, but with a lot of
> trial-and-error/testing.
>
> Given that status (and the fact that it has had that status for over a
> decennium), I don’t expect it to ever become a serious product that is
> (semi-)professionally managed. I prefer content over management every day,
> but something like this needs some minimal management. That requires both
> time (=money) and capabilities. Besides, the tinkering researchers may not
> be inclined to do that, they want to tinker.

Basically all the development in ConTeXt is voluntarily. Pro bono.
Besides "tinkering", Hans still needs to earn some money from
somewhere. I find it amazing how much time he already spends doing
good things for the community. But he's not omnipotent.

If there is interest from some commercial company to fund the project
enough to allow some people to work full-time on documentation
(including paying Hans to allow him to spend more time on the
project), I'm sure that it could be done.

> BTW, you can’t be serious asking the users to provide the documentation, can
> you?

There are many excellent books out there written by "writers", not the
authors of software.

(I didn't even get a manual for Windows or OS X where the companies
make big money. Certain things or tricks can only be done when hackers
find a way to do X without anyone documenting feature X. And the last
phone I bought also came without any documentation whatsoever.)

There are more than enough *users* of ConTeXt capable of coming up
with proper documentation (depending on the definition of user of
course, but one could count Taco and Wolfgang as users and they are
certainly not the only ones knowing ConTeXt from inside out). But
there's of course always a question of motivation (combined with time
and money of course).

ConTeXt comes with full source code, so users can easily study the
source code. The project could easily employ two people to work full
time just to keep up with the pace of development (once they would
catch up). Ohloh estimates that it took more than 300 person-years to
write the source code for example ;) Sure, the estimate is problematic
because ConTeXt includes the complete Unicode as well as all
hyphenation patterns which simply count as lines. But it's still an
enormous project.

Oven once you remove the hyphenation patterns and char-def.lua, there
are still 36 MB remaining. The pgf project has a 1200 page manual for
less that 5 MB of source code. LaTeX has a gazillion of manuals and if
you don't know what package you should be looking for, it's not really
helping.

I agree that it would be awesome if there was complete documentation
available + maybe three manuals/tutorials from beginner to master, but
you cannot expect it from Hans to do all the work on his own.

Mojca
___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Rob Heusdens]

> I agree that it would be awesome if there was complete documentation
> available + maybe three manuals/tutorials from beginner to master, but
> you cannot expect it from Hans to do all the work on his own.
>
> Mojca
>

I think that part of the work has to be done by other volunteers (users),
who have enough experience to write in good style user documentation. That
kind of work does not depend on Hans or Taco alone. I think their
important task is to have the technical documentation up-to-date and/or
provide well enough information about the changes in releases, that others
can write good user-documentation.

First priority I guess would be to have the contextgarden Wiki up-to-date:
many commands and/or parameters are not touched there. There are many
outdate pages (with broken links, etc.), and definatately I would guess a
better split is needed between MkII and MkIV wherever applicable.

If time and experience-level allows me, I would like to start working on
that kind of things. Someday I would also like to write a user-manual for
Context novices (and ppl. new to Tex in general). But first I need to sort
out some things myself, esp. about the whole font-mechanism, and how
Context handles it. And as of yet I have no clue on what is what in the
Context/Tex tree and where to find all the sources. Keeps me busy some
time...

Greetings,

Rob
--------
PS. And also material on 'good typography' would come in handy as weblinks
and in Context user-manuals. Yesterday, I read this online typography
manual, which contains some usefull tips about Typography. See:
http://practicaltypography.com/index.html#toc

I see that he also uses protrusion in the left-margin for quotations (when
you start a sentence on a new line with a quotation), something which
Context atm. does not do, only in the right margin, but the result is
good. Definately some feature request.

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


___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Alan BRASLAU]

Ah, the great documentation project!

The problem concerning writing documentation is that it must be done by
someone who knows ConTeXt well enough to know what to say or else know
where to look or ask about subjects that are less well known to him or
her. Many attempts at "improving" the documentation have been started.

Anyone is free to write a book, but is there enough of a market to make
it commercially viable? Yet a good book can also be a key to the
success of any system.

As Hans wrote earlier, one possibility is to fund a documentation
project that would allow someone to devote the necessary time to
achieve this (as well as to allow a few key developers to take the time
necessary to assist in this project, as Mojca suggests). We would need
to identify who could fund such a project as well as who could be
qualified to carry it through.

Right now, the community (and in particular Hans) is doing a pretty
good job of providing resources "in our spare time".

Alan


On Tue, 15 Jul 2014 16:42:25 +0200
Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:

> On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda wrote:
> >
> > I like ConTeXt (still do, I liked its approach when I first
> > encountered it). But the project is more the ongoing private
> > tinkering of a small in-crowd (that communicates with some
> > followers).
> >
> > ConTeXt is managed a bit like a small group of researchers sharing
> > a couple of complex and undocumented models/programs and tinkering
> > with them as they go along. It’s an activity without formal design,
> > but with a lot of trial-and-error/testing.
> >
> > Given that status (and the fact that it has had that status for
> > over a decennium), I don’t expect it to ever become a serious
> > product that is (semi-)professionally managed. I prefer content
> > over management every day, but something like this needs some
> > minimal management. That requires both time (=money) and
> > capabilities. Besides, the tinkering researchers may not be
> > inclined to do that, they want to tinker.
> 
> Basically all the development in ConTeXt is voluntarily. Pro bono.
> Besides "tinkering", Hans still needs to earn some money from
> somewhere. I find it amazing how much time he already spends doing
> good things for the community. But he's not omnipotent.
> 
> If there is interest from some commercial company to fund the project
> enough to allow some people to work full-time on documentation
> (including paying Hans to allow him to spend more time on the
> project), I'm sure that it could be done.
> 
> > BTW, you can’t be serious asking the users to provide the
> > documentation, can you?
> 
> There are many excellent books out there written by "writers", not the
> authors of software.
> 
> (I didn't even get a manual for Windows or OS X where the companies
> make big money. Certain things or tricks can only be done when hackers
> find a way to do X without anyone documenting feature X. And the last
> phone I bought also came without any documentation whatsoever.)
> 
> There are more than enough *users* of ConTeXt capable of coming up
> with proper documentation (depending on the definition of user of
> course, but one could count Taco and Wolfgang as users and they are
> certainly not the only ones knowing ConTeXt from inside out). But
> there's of course always a question of motivation (combined with time
> and money of course).
> 
> ConTeXt comes with full source code, so users can easily study the
> source code. The project could easily employ two people to work full
> time just to keep up with the pace of development (once they would
> catch up). Ohloh estimates that it took more than 300 person-years to
> write the source code for example ;) Sure, the estimate is problematic
> because ConTeXt includes the complete Unicode as well as all
> hyphenation patterns which simply count as lines. But it's still an
> enormous project.
> 
> Oven once you remove the hyphenation patterns and char-def.lua, there
> are still 36 MB remaining. The pgf project has a 1200 page manual for
> less that 5 MB of source code. LaTeX has a gazillion of manuals and if
> you don't know what package you should be looking for, it's not really
> helping.
> 
> I agree that it would be awesome if there was complete documentation
> available + maybe three manuals/tutorials from beginner to master, but
> you cannot expect it from Hans to do all the work on his own.
> 
> Mojca

___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Russ Urquhart]

I have been a tech writer for more than 25 years. I have been using and learning Context for the last few years. I would agree with everyone in thanking Hans and everyone else for this great product and it's support. It's been mentioned that the source is available to view. Is it possible that, given some standard of commenting with the code , a tool like Doxygen could be used to compile a reference guide of sorts?
My dream would be to be able to work on a Context documentation effort. 

Russ

Sent from my iPhone

> On Jul 16, 2014, at 5:14 AM, Alan BRASLAU <alan.braslau@cea.fr> wrote:
> 
> Ah, the great documentation project!
> 
> The problem concerning writing documentation is that it must be done by
> someone who knows ConTeXt well enough to know what to say or else know
> where to look or ask about subjects that are less well known to him or
> her. Many attempts at "improving" the documentation have been started.
> 
> Anyone is free to write a book, but is there enough of a market to make
> it commercially viable? Yet a good book can also be a key to the
> success of any system.
> 
> As Hans wrote earlier, one possibility is to fund a documentation
> project that would allow someone to devote the necessary time to
> achieve this (as well as to allow a few key developers to take the time
> necessary to assist in this project, as Mojca suggests). We would need
> to identify who could fund such a project as well as who could be
> qualified to carry it through.
> 
> Right now, the community (and in particular Hans) is doing a pretty
> good job of providing resources "in our spare time".
> 
> Alan
> 
> 
> On Tue, 15 Jul 2014 16:42:25 +0200
> Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:
> 
>>> On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda wrote:
>>> 
>>> I like ConTeXt (still do, I liked its approach when I first
>>> encountered it). But the project is more the ongoing private
>>> tinkering of a small in-crowd (that communicates with some
>>> followers).
>>> 
>>> ConTeXt is managed a bit like a small group of researchers sharing
>>> a couple of complex and undocumented models/programs and tinkering
>>> with them as they go along. It’s an activity without formal design,
>>> but with a lot of trial-and-error/testing.
>>> 
>>> Given that status (and the fact that it has had that status for
>>> over a decennium), I don’t expect it to ever become a serious
>>> product that is (semi-)professionally managed. I prefer content
>>> over management every day, but something like this needs some
>>> minimal management. That requires both time (=money) and
>>> capabilities. Besides, the tinkering researchers may not be
>>> inclined to do that, they want to tinker.
>> 
>> Basically all the development in ConTeXt is voluntarily. Pro bono.
>> Besides "tinkering", Hans still needs to earn some money from
>> somewhere. I find it amazing how much time he already spends doing
>> good things for
___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Hans Hagen]

On 7/16/2014 5:08 PM, Russ Urquhart wrote:
> I have been a tech writer for more than 25 years. I have been using and learning Context for the last few years. I would agree with everyone in thanking Hans and everyone else for this great product and it's support. It's been mentioned that the source is available to view. Is it possible that, given some standard of commenting with the code , a tool like Doxygen could be used to compile a reference guide of sorts?

the interface is described in cont-en.xml (should be updated, yes)

there's also:

context --ctx=s-mod font-sel.mkvi


> My dream would be to be able to work on a Context documentation effort.
>
> Russ
>
> Sent from my iPhone
>
>> On Jul 16, 2014, at 5:14 AM, Alan BRASLAU <alan.braslau@cea.fr> wrote:
>>
>> Ah, the great documentation project!
>>
>> The problem concerning writing documentation is that it must be done by
>> someone who knows ConTeXt well enough to know what to say or else know
>> where to look or ask about subjects that are less well known to him or
>> her. Many attempts at "improving" the documentation have been started.
>>
>> Anyone is free to write a book, but is there enough of a market to make
>> it commercially viable? Yet a good book can also be a key to the
>> success of any system.
>>
>> As Hans wrote earlier, one possibility is to fund a documentation
>> project that would allow someone to devote the necessary time to
>> achieve this (as well as to allow a few key developers to take the time
>> necessary to assist in this project, as Mojca suggests). We would need
>> to identify who could fund such a project as well as who could be
>> qualified to carry it through.
>>
>> Right now, the community (and in particular Hans) is doing a pretty
>> good job of providing resources "in our spare time".
>>
>> Alan
>>
>>
>> On Tue, 15 Jul 2014 16:42:25 +0200
>> Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:
>>
>>>> On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda wrote:
>>>>
>>>> I like ConTeXt (still do, I liked its approach when I first
>>>> encountered it). But the project is more the ongoing private
>>>> tinkering of a small in-crowd (that communicates with some
>>>> followers).
>>>>
>>>> ConTeXt is managed a bit like a small group of researchers sharing
>>>> a couple of complex and undocumented models/programs and tinkering
>>>> with them as they go along. It’s an activity without formal design,
>>>> but with a lot of trial-and-error/testing.
>>>>
>>>> Given that status (and the fact that it has had that status for
>>>> over a decennium), I don’t expect it to ever become a serious
>>>> product that is (semi-)professionally managed. I prefer content
>>>> over management every day, but something like this needs some
>>>> minimal management. That requires both time (=money) and
>>>> capabilities. Besides, the tinkering researchers may not be
>>>> inclined to do that, they want to tinker.
>>>
>>> Basically all the development in ConTeXt is voluntarily. Pro bono.
>>> Besides "tinkering", Hans still needs to earn some money from
>>> somewhere. I find it amazing how much time he already spends doing
>>> good things for
> ___________________________________________________________________________________
> 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
> ___________________________________________________________________________________
>


-- 

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
     tel: 038 477 53 69 | voip: 087 875 68 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  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: State of documentation of ConTeXt?

[luigi scarso]

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

On Wed, Jul 16, 2014 at 5:20 PM, Hans Hagen <pragma@wxs.nl> wrote:

> On 7/16/2014 5:08 PM, Russ Urquhart wrote:
>
>> I have been a tech writer for more than 25 years. I have been using and
>> learning Context for the last few years. I would agree with everyone in
>> thanking Hans and everyone else for this great product and it's support.
>> It's been mentioned that the source is available to view. Is it possible
>> that, given some standard of commenting with the code , a tool like Doxygen
>> could be used to compile a reference guide of sorts?
>>
>
> the interface is described in cont-en.xml (should be updated, yes)
>
> there's also:
>
> context --ctx=s-mod font-sel.mkvi
>
>
>
see also
http://wiki.contextgarden.net/Modules

( mine http://foundry.supelec.fr/gf/project/modules/
is broken ... )

-- 
luigi

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

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

Re: State of documentation of ConTeXt?

[Mica Semrick]

I am also a technical editor and have been using context for about five years. Maybe my typesetting needs are simple, but the wiki and manuals have served me  well. When they don't, this list is quick to respond. Thanks to everyone for the effort.

If you want a fund for tech doc, have you considered something like bountysource.com?

Best,
Mica
___________________________________________________________________________________
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: State of documentation of ConTeXt?

[luigi scarso]

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

On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda <gerben.wierda@rna.nl>
wrote:

> On 14 Jul 2014, at 19:29, Hans Hagen <pragma@wxs.nl> wrote:
>
> quite some sub-systems are described in their own manuals (fonts, tables,
> xml, ...) and these manuals are quite up to date (and easier to maintain
> than one big fat manual
>
> also, additional documentation is something that users need to participate
> in (just pick a topic)
>
> even if it has high priority, that doesn't mean that those involved have
> much free time left to do that next to their regular work (as usual most
> development is done in spare time)
>
> so, patience is needed,
>
>
> I like ConTeXt (still do, I liked its approach when I first encountered
> it). But the project is more the ongoing private tinkering of a small
> in-crowd (that communicates with some followers).
>
> ConTeXt is managed a bit like a small group of researchers sharing a
> couple of complex and undocumented models/programs and tinkering with them
> as they go along. It’s an activity without formal design, but with a lot of
> trial-and-error/testing.
>
> Given that status (and the fact that it has had that status for over a
> *decennium*), I don’t expect it to ever become a serious product that is
> (semi-)professionally managed. I prefer content over management every day,
> but something like this needs some minimal management. That requires both
> time (=money) and capabilities. Besides, the tinkering researchers may not
> be inclined to do that, they want to tinker.
>
> BTW, you can’t be serious asking the *users* to provide the
> documentation, can you?
>
>
These are still good

Fonts in ConTeXt
Layouts in ConTeXt
MetaFun manual
MKII - MKIV, the history of LuaTeX

http://www.h2o-books.com/catalog/5

-- 
luigi

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

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

Re: State of documentation of ConTeXt?

[Yuri Teixeira]

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

As I wrote in another thread, the state of the docs worries me too. I take
it that the suggestion to study the source was not serious, and perhaps it
is indeed a matter of priorities. As a new user I have a strong opinion
that the documentation should be a higher priority than it seems to be. All
the arguments about how many person-hours it would take and the huge task
it is, in my eyes, only furthers the point that it is not considered as
important as doing "real development". I consider the docs a core part of
the project, and the code another part, hence the disagreement in regards
to the priorities. Pro-bono or not is not an issue, since time is spent on
the project in some form. Writing features that few people know about and
are able to use is only half of the dev work.

But I get it that documenting is a pain, and seemingly frivolous work. The
separate manuals may have been good, but they look fragmented and there is
no unified docs to go to when in doubt. And having one place to go is even
easier to maintain than many. The wiki is a nice idea, but it needs much
more rigour to function as real docs.

Some suggestions. I'm assuming some form of wiki-like website that can be
the contextgarden or (preferably) another official docs/wiki/wiki-like site.
All the content of the manuals should be unified in this site.
If a crowdsourcing/users-can-do-it approach is taken, a clear structure
needs to be previously laid out, so that we know what blanks to fill. And
even with collaboration/feedback, core people should do it.
It is important that reviewing and check marking the new edits be done by
some authoritative group, so that the community knows what to trust, what
should work as documented so that we can report real issues.
It is important to label the information as reviwed and up to date, and to
which version it applies, mkii/mkiv
If this structure is put on top of the context garden, some labeling is
needed to distinguish the extra pages from the structural docs pages.

There are many good examples out there of good docs structure and
presentation. I'm willing to collaborate what I can with my limited
knowledge and time, even if little while writing my master's thesis.

Sorry to annoy with this again,

YT



2014-07-15 11:55 GMT-03:00 luigi scarso <luigi.scarso@gmail.com>:

>
>
>
> On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda <gerben.wierda@rna.nl>
> wrote:
>
>> On 14 Jul 2014, at 19:29, Hans Hagen <pragma@wxs.nl> wrote:
>>
>> quite some sub-systems are described in their own manuals (fonts, tables,
>> xml, ...) and these manuals are quite up to date (and easier to maintain
>> than one big fat manual
>>
>> also, additional documentation is something that users need to
>> participate in (just pick a topic)
>>
>> even if it has high priority, that doesn't mean that those involved have
>> much free time left to do that next to their regular work (as usual most
>> development is done in spare time)
>>
>> so, patience is needed,
>>
>>
>> I like ConTeXt (still do, I liked its approach when I first encountered
>> it). But the project is more the ongoing private tinkering of a small
>> in-crowd (that communicates with some followers).
>>
>> ConTeXt is managed a bit like a small group of researchers sharing a
>> couple of complex and undocumented models/programs and tinkering with them
>> as they go along. It’s an activity without formal design, but with a lot of
>> trial-and-error/testing.
>>
>> Given that status (and the fact that it has had that status for over a
>> *decennium*), I don’t expect it to ever become a serious product that is
>> (semi-)professionally managed. I prefer content over management every day,
>> but something like this needs some minimal management. That requires both
>> time (=money) and capabilities. Besides, the tinkering researchers may not
>> be inclined to do that, they want to tinker.
>>
>> BTW, you can’t be serious asking the *users* to provide the
>> documentation, can you?
>>
>>
> These are still good
>
> Fonts in ConTeXt
> Layouts in ConTeXt
> MetaFun manual
> MKII - MKIV, the history of LuaTeX
>
> http://www.h2o-books.com/catalog/5
>
> --
> luigi
>
>
> ___________________________________________________________________________________
> 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
>
> ___________________________________________________________________________________
>

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

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

Re: State of documentation of ConTeXt?

[Hans Hagen]

On 7/15/2014 5:33 PM, Yuri Teixeira wrote:
> As I wrote in another thread, the state of the docs worries me too. I
> take it that the suggestion to study the source was not serious, and
> perhaps it is indeed a matter of priorities. As a new user I have a
> strong opinion that the documentation should be a higher priority than
> it seems to be. All the arguments about how many person-hours it would
> take and the huge task it is, in my eyes, only furthers the point that
> it is not considered as important as doing "real development". I

Well, without development (like luatex and mp and fonts and so) it would 
be a dead end anyway. Also, without some of the new things I could not 
use context myself in projects (and thereby put time in it).

> consider the docs a core part of the project, and the code another part,
> hence the disagreement in regards to the priorities. Pro-bono or not is
> not an issue, since time is spent on the project in some form. Writing
> features that few people know about and are able to use is only half of
> the dev work.

Most mechanism that are new or renewed also come with pretty recent 
manuals (like xtables and new bibliography support); older code is 
mostly compatible with what old manuals describe (ok we could just bump 
the date to 2014 but why). For me that's the most I can so ...  write in 
sync with development. (I simply run out of time otherwise.)

> But I get it that documenting is a pain, and seemingly frivolous work.
> The separate manuals may have been good, but they look fragmented and
> there is no unified docs to go to when in doubt. And having one place to
> go is even easier to maintain than many. The wiki is a nice idea, but it
> needs much more rigour to function as real docs.

hm, I spend quite some time on writing code but also on documentations; 
did you read the xtable, xml, cld, fonts, metafun, etc manuals as well 
as mk, hybrid, allkind? It's up to others to translate that into 
something better. There are articles published (ok, in that case it 
helps to be a member if a user group, which helps keeping tex alive 
anyway).

There are also examples in the test suite that can probably be turned 
into docu.

> Some suggestions. I'm assuming some form of wiki-like website that can
> be the contextgarden or (preferably) another official
> docs/wiki/wiki-like site.

everyone can write documentation (and it also happens) ... we have the 
wiki etc to publish them .. and everyone can conrtibute to make the wiki 
better (and provide pointers to documentation)

> All the content of the manuals should be unified in this site.
> If a crowdsourcing/users-can-do-it approach is taken, a clear structure
> needs to be previously laid out, so that we know what blanks to fill.
> And even with collaboration/feedback, core people should do it.
> It is important that reviewing and check marking the new edits be done
> by some authoritative group, so that the community knows what to trust,
> what should work as documented so that we can report real issues.
> It is important to label the information as reviwed and up to date, and
> to which version it applies, mkii/mkiv
> If this structure is put on top of the context garden, some labeling is
> needed to distinguish the extra pages from the structural docs pages.

the problem there is that it needs some users who dedicate time and so 
that for many years in order to keep consistency (btw, there are some 
real good sections on the wiki already)

> There are many good examples out there of good docs structure and
> presentation. I'm willing to collaborate what I can with my limited
> knowledge and time, even if little while writing my master's thesis.

In that case, coordinate with Sietse. One of the things we want to (be) 
do(ne) is a split between mkii and mkiv on the wiki.

> Sorry to annoy with this again,

No problem, as you also offer to help,

> YT
>
> 2014-07-15 11:55 GMT-03:00 luigi scarso <luigi.scarso@gmail.com
> <mailto:luigi.scarso@gmail.com>>:
>
>
>
>
>     On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda
>     <gerben.wierda@rna.nl <mailto:gerben.wierda@rna.nl>> wrote:
>
>         On 14 Jul 2014, at 19:29, Hans Hagen <pragma@wxs.nl
>         <mailto:pragma@wxs.nl>> wrote:
>
>>         quite some sub-systems are described in their own manuals
>>         (fonts, tables, xml, ...) and these manuals are quite up to
>>         date (and easier to maintain than one big fat manual
>>
>>         also, additional documentation is something that users need to
>>         participate in (just pick a topic)
>>
>>         even if it has high priority, that doesn't mean that those
>>         involved have much free time left to do that next to their
>>         regular work (as usual most development is done in spare time)
>>
>>         so, patience is needed,
>
>         I like ConTeXt (still do, I liked its approach when I first
>         encountered it). But the project is more the ongoing private
>         tinkering of a small in-crowd (that communicates with some
>         followers).
>
>         ConTeXt is managed a bit like a small group of researchers
>         sharing a couple of complex and undocumented models/programs and
>         tinkering with them as they go along. It’s an activity without
>         formal design, but with a lot of trial-and-error/testing.
>
>         Given that status (and the fact that it has had that status for
>         over a /decennium/), I don’t expect it to ever become a serious
>         product that is (semi-)professionally managed. I prefer content
>         over management every day, but something like this needs some
>         minimal management. That requires both time (=money) and
>         capabilities. Besides, the tinkering researchers may not be
>         inclined to do that, they want to tinker.
>
>         BTW, you can’t be serious asking the /users/ to provide the
>         documentation, can you?
>
>
>     These are still good
>
>     Fonts in ConTeXt
>     Layouts in ConTeXt
>     MetaFun manual
>     MKII - MKIV, the history of LuaTeX
>
>     http://www.h2o-books.com/catalog/5
>
>     --
>     luigi
>
>     ___________________________________________________________________________________
>     If your question is of interest to others as well, please add an
>     entry to the Wiki!
>
>     maillist : ntg-context@ntg.nl <mailto: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
>     ___________________________________________________________________________________
>
>
>
>
> ___________________________________________________________________________________
> 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
> ___________________________________________________________________________________
>


-- 

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
     tel: 038 477 53 69 | voip: 087 875 68 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  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: State of documentation of ConTeXt?

[Hans Hagen]

On 7/15/2014 11:59 AM, Gerben Wierda wrote:
> On 14 Jul 2014, at 19:29, Hans Hagen <pragma@wxs.nl
> <mailto:pragma@wxs.nl>> wrote:
>
>> quite some sub-systems are described in their own manuals (fonts,
>> tables, xml, ...) and these manuals are quite up to date (and easier
>> to maintain than one big fat manual
>>
>> also, additional documentation is something that users need to
>> participate in (just pick a topic)
>>
>> even if it has high priority, that doesn't mean that those involved
>> have much free time left to do that next to their regular work (as
>> usual most development is done in spare time)
>>
>> so, patience is needed,
>
> I like ConTeXt (still do, I liked its approach when I first encountered
> it). But the project is more the ongoing private tinkering of a small
> in-crowd (that communicates with some followers).
>
> ConTeXt is managed a bit like a small group of researchers sharing a
> couple of complex and undocumented models/programs and tinkering with
> them as they go along. It’s an activity without formal design, but with
> a lot of trial-and-error/testing.
>
> Given that status (and the fact that it has had that status for over a
> /decennium/), I don’t expect it to ever become a serious product that is
> (semi-)professionally managed. I prefer content over management every
> day, but something like this needs some minimal management. That
> requires both time (=money) and capabilities. Besides, the tinkering
> researchers may not be inclined to do that, they want to tinker.
>
> BTW, you can’t be serious asking the /users/ to provide the
> documentation, can you?

Well, you need to keep this in mind:

- we are using it ourselves (already for a long time) so we depend on it 
and so we keep it going

- we spend most of our company time on development and support .. and we 
live with that

- our roadmap does *not* include getting big (with open source as 
stepping stone), *not* messing with users by selling ourselves after a 
while, and *not* splitting between 'context for users' and 'context 
professional or enterprise', so everyone gets what we have (which also 
means that documentation will always be behind!)

- we have no big projects that pay for development (from which we can 
then work on documentation) .. in fact, our projects are rather niche 
and special

- we're quite satisfied with the users (they are demanding and creative) 
... context never aimed at one-time-users

Now, we don't ask users to provide documentation, but on the other hand, 
if you look at latex, lost of documentation starts at users.

Maybe some day I find more time ...

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
     tel: 038 477 53 69 | voip: 087 875 68 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  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: State of documentation of ConTeXt?

[David Wooten]

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

On Jul 15, 2014, at 2:59 AM, Gerben Wierda <Gerben.Wierda@rna.nl> wrote:

> I like ConTeXt (still do, I liked its approach when I first encountered it). But the project is more the ongoing private tinkering of a small in-crowd (that communicates with some followers).
> 
> ConTeXt is managed a bit like a small group of researchers sharing a couple of complex and undocumented models/programs and tinkering with them as they go along. It’s an activity without formal design, but with a lot of trial-and-error/testing.
> 
> Given that status (and the fact that it has had that status for over a decennium), I don’t expect it to ever become a serious product that is (semi-)professionally managed. I prefer content over management every day, but something like this needs some minimal management. That requires both time (=money) and capabilities. Besides, the tinkering researchers may not be inclined to do that, they want to tinker.


Agreed, though for my part with the opposite emphasis. I do not think ConTeXt is meant to be a “serious product”, as in being developed to be a product in the “marketplace” of  typesetting software — even open/free software. My impression is exactly yours, it is being developed primarily for the purposes of Pragma—a small in-crowd no doubt—but with extraordinarily generous support for a small community of non-Pragma people interested in using it. I’m grateful to have access to ConTeXt, as for me it’s the only sane method of typesetting the kind of documents I wish to typeset — not LaTeX, not InDesign, not Plain TeX, … I can tell you that every question or suggestion I’ve had has been responded to in the most generous form in this community, which I cannot say about any other platform I’ve used, typesetting or otherwise.

It’s suspect to take umbrage on another’s behalf, but “tinkering researchers may not be inclined to do that, they want to tinker” — It’s absurd to suggest that Hans &co. are “tinkering” for the sake of tinkering.

David 

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

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

Re: State of documentation of ConTeXt?

[Hans Hagen]

On 7/16/2014 12:26 AM, David Wooten wrote:
> On Jul 15, 2014, at 2:59 AM, Gerben Wierda <Gerben.Wierda@rna.nl
> <mailto:Gerben.Wierda@rna.nl>> wrote:
>
>> I like ConTeXt (still do, I liked its approach when I first
>> encountered it). But the project is more the ongoing private tinkering
>> of a small in-crowd (that communicates with some followers).
>>
>> ConTeXt is managed a bit like a small group of researchers sharing a
>> couple of complex and undocumented models/programs and tinkering with
>> them as they go along. It’s an activity without formal design, but
>> with a lot of trial-and-error/testing.
>>
>> Given that status (and the fact that it has had that status for over a
>> /decennium/), I don’t expect it to ever become a serious product that
>> is (semi-)professionally managed. I prefer content over management
>> every day, but something like this needs some minimal management. That
>> requires both time (=money) and capabilities. Besides, the tinkering
>> researchers may not be inclined to do that, they want to tinker.
>
> Agreed, though for my part with the opposite emphasis. I do not think
> ConTeXt is meant to be a “serious product”, as in /being developed to be
> a product in the “marketplace” of  typesetting software — even open/free
> software. /My impression is exactly yours, it is being developed
> primarily for the purposes of Pragma—a small in-crowd no doubt—but with

don't get me wrong: the development is to a large extend possible 
because we can use it at pragma (it make sit possible to do things that 
often cannot be done otherwise) but most of the features that have been 
added the last years as well as numerous additional options are purely 
user driven: most styles we write are rather simple .. the complexity 
comes from the often messy or complex or to-be-manipulated content and 
range of products; so, it being mostly user driven (but within the 
constraints that we keep a relative stable core) also means that users 
have a responsibility for helping with documentation

> extraordinarily generous support for a small community of non-Pragma
> people interested in using it. I’m /grateful/ to have access to ConTeXt,
> as for me it’s the only sane method of typesetting the kind of documents
> I wish to typeset — /not /LaTeX, /not /InDesign, /not /Plain TeX, … I
> can tell you that every question or suggestion I’ve had has been
> responded to in the most generous form in this community, which I cannot
> say about /any other/ platform I’ve used, typesetting or otherwise.

keep in mind that context has been part of the tex distributions for 
quite a while now (nearly 20 years), that there are others than me who 
know the source code pretty well (which means that it doesn't depend on 
pragma), that the context crowd has been actively involved in 
development of (and even triggered) general tex developments (..., 
luatex, mplib, fonts, ...) so it's not as isolated as you suggest.

once the move from mkii to mkiv is finishes and luatex is kind of done, 
there might be time for writing more documentation; we're far from retiring

of the other macro packages, plain tex is frozen, and latex dev is quite 
controlled too (anyone can write additional code for any macro package)

(and the context mailing list is one of the more active tex related 
lists and not the smallest either)

> It’s suspect to take umbrage on another’s behalf, but “tinkering
> researchers may not be inclined to do that, they want to tinker” — It’s
> absurd to suggest that Hans &co. are “tinkering” for the sake of tinkering.

sometimes we do, when we explore new posibilities,

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
     tel: 038 477 53 69 | voip: 087 875 68 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  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: State of documentation of ConTeXt?

[David Wooten]

As is said most often here in California, that’s just your opinion Hans! ;)

On Jul 15, 2014, at 3:54 PM, Hans Hagen <pragma@wxs.nl> wrote:

> On 7/16/2014 12:26 AM, David Wooten wrote:
>> On Jul 15, 2014, at 2:59 AM, Gerben Wierda <Gerben.Wierda@rna.nl
>> <mailto:Gerben.Wierda@rna.nl>> wrote:
>> 
>>> I like ConTeXt (still do, I liked its approach when I first
>>> encountered it). But the project is more the ongoing private tinkering
>>> of a small in-crowd (that communicates with some followers).
>>> 
>>> ConTeXt is managed a bit like a small group of researchers sharing a
>>> couple of complex and undocumented models/programs and tinkering with
>>> them as they go along. It’s an activity without formal design, but
>>> with a lot of trial-and-error/testing.
>>> 
>>> Given that status (and the fact that it has had that status for over a
>>> /decennium/), I don’t expect it to ever become a serious product that
>>> is (semi-)professionally managed. I prefer content over management
>>> every day, but something like this needs some minimal management. That
>>> requires both time (=money) and capabilities. Besides, the tinkering
>>> researchers may not be inclined to do that, they want to tinker.
>> 
>> Agreed, though for my part with the opposite emphasis. I do not think
>> ConTeXt is meant to be a “serious product”, as in /being developed to be
>> a product in the “marketplace” of  typesetting software — even open/free
>> software. /My impression is exactly yours, it is being developed
>> primarily for the purposes of Pragma—a small in-crowd no doubt—but with
> 
> don't get me wrong: the development is to a large extend possible because we can use it at pragma (it make sit possible to do things that often cannot be done otherwise) but most of the features that have been added the last years as well as numerous additional options are purely user driven: most styles we write are rather simple .. the complexity comes from the often messy or complex or to-be-manipulated content and range of products; so, it being mostly user driven (but within the constraints that we keep a relative stable core) also means that users have a responsibility for helping with documentation
> 
>> extraordinarily generous support for a small community of non-Pragma
>> people interested in using it. I’m /grateful/ to have access to ConTeXt,
>> as for me it’s the only sane method of typesetting the kind of documents
>> I wish to typeset — /not /LaTeX, /not /InDesign, /not /Plain TeX, … I
>> can tell you that every question or suggestion I’ve had has been
>> responded to in the most generous form in this community, which I cannot
>> say about /any other/ platform I’ve used, typesetting or otherwise.
> 
> keep in mind that context has been part of the tex distributions for quite a while now (nearly 20 years), that there are others than me who know the source code pretty well (which means that it doesn't depend on pragma), that the context crowd has been actively involved in development of (and even triggered) general tex developments (..., luatex, mplib, fonts, ...) so it's not as isolated as you suggest.
> 
> once the move from mkii to mkiv is finishes and luatex is kind of done, there might be time for writing more documentation; we're far from retiring
> 
> of the other macro packages, plain tex is frozen, and latex dev is quite controlled too (anyone can write additional code for any macro package)
> 
> (and the context mailing list is one of the more active tex related lists and not the smallest either)
> 
>> It’s suspect to take umbrage on another’s behalf, but “tinkering
>> researchers may not be inclined to do that, they want to tinker” — It’s
>> absurd to suggest that Hans &co. are “tinkering” for the sake of tinkering.
> 
> sometimes we do, when we explore new posibilities,
> 
> Hans
> 
> -----------------------------------------------------------------
>                                          Hans Hagen | PRAGMA ADE
>              Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
>    tel: 038 477 53 69 | voip: 087 875 68 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  : http://foundry.supelec.fr/projects/contextrev/
> wiki     : http://contextgarden.net
> ___________________________________________________________________________________

___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Gour]

Hans Hagen <pragma@wxs.nl> writes:

> (and the context mailing list is one of the more active tex related
> lists and not the smallest either)

I believe this is part of the problem as well of the solution - there is
so much knowledge scattered in different posts here and if it could be
put into manual form, there will be plenty of docs available.


Otoh, there is nothing even remotely close to ConteXt when it comes to
quality typesetting. ConTeXt is simply what LaTeX2e was supposed to be
and the state of LaTeX3 is not very promising i nthe sense of having
some release soon.

<dreaming>
If I'd be asked, my proposal would be for all LaTeX users to simply
invest some time in learning to migrate to ConTeXt and similar advice
for the developers as well which could skyrocket development of ConTeXt
as well having ability to 'program' using Lua via LuaTeX.
</dremaing>


Sincerely,
Gour

-- 
One must deliver himself with the help of his mind, and not 
degrade himself. The mind is the friend of the conditioned soul, 
and his enemy as well.

___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Gerben Wierda]

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

On 15 Jul 2014, at 16:42, Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:

> ConTeXt comes with full source code, so users can easily study the
> source code.

This is crazy. Sorry, you can’t expect users to be able to do that. Lamport created LaTeX *and* wrote the “LaTeX User’s Guide and Reference manual”.  The authors mentioned below were all developers too. You need that level of understanding to write a manual.

> The project could easily employ two people to work full
> time just to keep up with the pace of development (once they would
> catch up). 


I would expect it to be far less than that once you have the documentation. What a project needs is discipline. If the ConTeXt stays a tinkered-tool-in-flux (because that is how Hans needs it for his own work), a decent manual will never arrive unless there is the discipline that any new functionality is documented (“user manual & reference”) in full before proceeding to the next development.

On 16 Jul 2014, at 00:26, David Wooten <dw@trichotomic.net> wrote:

> It’s suspect to take umbrage on another’s behalf, but “tinkering researchers may not be inclined to do that, they want to tinker” — It’s absurd to suggest that Hans &co. are “tinkering” for the sake of tinkering.

I never suggested that. Hans & Co tinker because they want to make progress and develop functionality they need. But because the project is in constant flux, even if you would have time (money) to fund documentation, the documentation would be out-of-date soon.

I would immediately buy any book that explains ConTeXt such as the books that are there for LaTeX. But then, LaTeX is moribund and doesn’t change at all. An easier target.

Hans & Taco: how much money would need to be raised to produce something of the quality of Kopka & Daly’s “Guide to LaTeX”?  or Goossens, Mittelbach & Samarin’s “The LaTeX Companion”? Because, I don’t think this will happen unless some money is raised to pay for it.

I would gladly donate in a crowdfunding initiative for a good book. But how much is needed to make it happen?

G

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

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

Re: State of documentation of ConTeXt?

[Gerben Wierda]

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

On 20 Jul 2014, at 14:14, Gerben Wierda <gerben.wierda@rna.nl> wrote:

> I would gladly donate in a crowdfunding initiative for a good book. But how much is needed to make it happen?

BTW, as I have become a publisher in recent years I know now what to do, I can maybe help by acting as the publisher for the book. If an author of a group of authors can write a manuscript, I would be happy to fund the production of the book and host the sales of a PDF version (see http://bit.ly/1iNacG8 for how selling both print and PDF would work).

If money is needed in advance for authors so they can live while writing, we could crowdsource that and repay the investors form the proceeds of the book. When the investment has been paid back, we could distribute the PDF for free or use the proceeds to fund updates and such.

G


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

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

Re: State of documentation of ConTeXt?

[Mojca Miklavec]

On Sun, Jul 20, 2014 at 2:14 PM, Gerben Wierda wrote:
>
> Sorry, you can’t expect users to be able to do that. Lamport
> created LaTeX *and* wrote the “LaTeX User’s Guide and Reference manual”.

<teasing>
Indeed. Sorry, you can't do that to users. Christian Schenk also
created MikTeX (I still have MikTeX files from 23 years ago) *and* is
still developing it actively and answering emails from users.
</teasing>

> The authors mentioned below were all developers too. You need that level of
> understanding to write a manual.

What kind of developers? Did they contribute to the LaTeX core? (Many
ConTeXt users are developers, but it highly depends what you count as
a developer.)

>> The project could easily employ two people to work full
>> time just to keep up with the pace of development (once they would
>> catch up).
>
> I would expect it to be far less than that once you have the documentation.

(a) You probably never tried to follow how fast ConTeXt is being developed.
(b) There's a tricky "once" in the sentence.

Ad (a): I've heard a rumour (that might just as well be false
information) that authors of the LaTeX companion or maybe LaTeX
Graphics companion had a serious problem. They hardly managed writing
as fast as the packages described in the book kept developing.

Also, if I see correctly, the book "Guide to LaTeX" has been published
in 2003. Even for LaTeX that's "a totally outdated book" and doesn't
even scratch the surface of LuaTeX, XeTeX and OpenType fonts - the
most useful things that most users should switch to nowadays. The
LaTeX Companion is probably even more outdated and "useless" as it
doesn't even scratch the surface of many useful packages that surfaced
since the last release. I have the LaTeX Graphics Companion on my
bookshelf for example, but even if I was still using LaTeX, the book
would be almost useless to me nowadays. Almost none of the things I
would want to use are covered there (starting with TikZ for example).

The beginner's tutorial for ConTeXt is no more outdated than these
books are (but of course these books were more complete at the time of
writing and probably went under many more proofreading than the
ConTeXt tutorial, with "professional writers" involved).

I'm exaggerating a bit on purpose. But not much.

> Hans & Taco: how much money would need to be raised to produce something of
> the quality of Kopka & Daly’s “Guide to LaTeX”?  or Goossens, Mittelbach &
> Samarin’s “The LaTeX Companion”?

What do you mean with "of the quality of these books"? Having a
similar number of pages written in comparable quality (something like
a revised beginner's manual) or so complete in description of the
functionality as the mentioned manuals?

My estimate would be that a complete context reference with
well-described options and including trivial examples would require
cca. 10.000-50.000 pages. Maybe others have different estimates, but
now do the math. (Existing manuals like MetaFun or the old cont-en.pdf
are roughly 400 pages. But that's nowhere near 10 % of the ConTeXt
functionality. One would need to document the whole TeX part, the
whole metapost part, the whole lua part, the whole xml, all perl, ruby
and lua scripts, write better man pages, probably list the whole
Unicode to show the ConTeXt names in one appendix ...)

> Because, I don’t think this will happen
> unless some money is raised to pay for it.

> I would gladly donate in a crowdfunding initiative for a good book. But how
> much is needed to make it happen?

I would gladly donate as well. But probably not anywhere near the
amount that would suffice even if a nontrivial number of users
contributed the same.

Mojca

PS: the example you linked to asks for 30 EUR for a 220 page book. If
the same calculation is applied to my estimate of the number of
required pages, 22.000 pages would translate to 3000 EUR per copy.
___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Gerben Wierda]

On 20 Jul 2014, at 22:24, Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:

> On Sun, Jul 20, 2014 at 2:14 PM, Gerben Wierda wrote:
>> 
>> Sorry, you can’t expect users to be able to do that. Lamport
>> created LaTeX *and* wrote the “LaTeX User’s Guide and Reference manual”.
> 
> <teasing>
> Indeed. Sorry, you can't do that to users. Christian Schenk also
> created MikTeX (I still have MikTeX files from 23 years ago) *and* is
> still developing it actively and answering emails from users.
> </teasing>
> 
>> The authors mentioned below were all developers too. You need that level of
>> understanding to write a manual.
> 
> What kind of developers? Did they contribute to the LaTeX core? (Many
> ConTeXt users are developers, but it highly depends what you count as
> a developer.)

Some contributed packages, some other stuff (even printer drivers). They all were deeply involved with the inside of TeX and LaTeX at a level that they would have to understand TeX and LaTeX to the core as they were developers in that environment

>> Hans & Taco: how much money would need to be raised to produce something of
>> the quality of Kopka & Daly’s “Guide to LaTeX”?  or Goossens, Mittelbach &
>> Samarin’s “The LaTeX Companion”?
> 
> What do you mean with "of the quality of these books"? Having a
> similar number of pages written in comparable quality (something like
> a revised beginner's manual) or so complete in description of the
> functionality as the mentioned manuals?

I agree these are now outdated in several areas and less useful as they were half a decade ago. But something that is complete enough for a user (not a TeXnician), doesn’t contain too many white spots and certainly does not contain stuff that isn’t true anymore.

> My estimate would be that a complete context reference with
> well-described options and including trivial examples would require
> cca. 10.000-50.000 pages. Maybe others have different estimates, but
> now do the math. (Existing manuals like MetaFun or the old cont-en.pdf
> are roughly 400 pages. But that's nowhere near 10 % of the ConTeXt
> functionality. One would need to document the whole TeX part, the
> whole metapost part, the whole lua part, the whole xml, all perl, ruby
> and lua scripts, write better man pages, probably list the whole
> Unicode to show the ConTeXt names in one appendix …)

If a tool needs 50.000 pages to document its use, you are in trouble (in more ways than one). 

I think in reality a set of manuals, with core functionality and all kinds of extras a manual of 500 pages and maybe a reference manual of the same size would be something useful and thus meaningful. Stuff like MetaFun can have its own manual and doesn’t need to be in a core ConTeXt manual.

A user manual is enough. You don’t need a developer manual. So, documenting all the development you can do with ConTeXt (programming in lua and whatnot) would for me not be what is needed for a user manual. What a user manual does is what cont-en.pdf does, but then up to date and complete.

G
___________________________________________________________________________________
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: State of documentation of ConTeXt?

[Henning Hraban Ramm]

Am 2014-07-21 um 03:07 schrieb Gerben Wierda <gerben.wierda@rna.nl>:

>> My estimate would be that a complete context reference with
>> well-described options and including trivial examples would require
>> cca. 10.000-50.000 pages. Maybe others have different estimates, but
>> now do the math. (Existing manuals like MetaFun or the old cont-en.pdf
>> are roughly 400 pages. But that's nowhere near 10 % of the ConTeXt
>> functionality. One would need to document the whole TeX part, the
>> whole metapost part, the whole lua part, the whole xml, all perl, ruby
>> and lua scripts, write better man pages, probably list the whole
>> Unicode to show the ConTeXt names in one appendix …)
> 
> If a tool needs 50.000 pages to document its use, you are in trouble (in more ways than one). 
> 
> I think in reality a set of manuals, with core functionality and all kinds of extras a manual of 500 pages and maybe a reference manual of the same size would be something useful and thus meaningful. Stuff like MetaFun can have its own manual and doesn’t need to be in a core ConTeXt manual.
> 
> A user manual is enough. You don’t need a developer manual. So, documenting all the development you can do with ConTeXt (programming in lua and whatnot) would for me not be what is needed for a user manual. What a user manual does is what cont-en.pdf does, but then up to date and complete.

If I might chime in …

What we really need (and what „simple“ users like me cannot write, even if I sometimes look into the sources) is a usable command reference, covering all „usable“ commands and all their „usable“ options (i.e. omit too experimental stuff).
What we have on the wiki now is much too incomplete in all regards. I don’t know if there’s something (more?) that can be automated.

I don’t know if Hans, Taco or Wolfgang (any other candidates?) would be able and willing to do that work, if e.g. DANTE would fund it. Would you, and what do you think how much funding would be required to at least document the current state of MkIV?

I would not try to write a (printed/printable) reference manual for ConTeXt, that really makes not much sense.
We don’t need to argue about page estimates, that depends too much on layout anyway …

I thought the previous ConTeXt meeting was about documentation? Didn’t you agree on a better wiki structure?


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

Re: State of documentation of ConTeXt?

[Ulrike Fischer]

Am Sun, 20 Jul 2014 23:07:32 +0200 schrieb Gerben Wierda:

>> My estimate would be that a complete context reference with
>> well-described options and including trivial examples would require
>> cca. 10.000-50.000 pages. 

> If a tool needs 50.000 pages to document its use, you are in
> trouble (in more ways than one).

Well imho the LaTeX-documentations could add up easily to this
number, probably more: e.g. source3 has more then 700 pages, tikz
more than 1000, etc.

So imho Mojca's estimate is probably quite sound. But naturally such
a reference is not the same as an introductionary book like the
latex guide or the latex companion. Such books have to select and
layout their informations -- and if it weren't possible to write
such a book about context then you are in trouble.  


> I would immediately buy any book that explains ConTeXt such as the
> books that are there for LaTeX. But then, LaTeX is moribund and
> doesn’t change at all. An easier target.

As you wrote in a later posting: many books about latex are in parts
outdated as they couldn't keep up with the development e.g. of tikz,
biblatex, expl3 etc. So I don't see how you can claim that "latex
doesn't change at all". 

Beside this I don't believe that context is changing so much that it
would be impossible to write a book about it: I doubt that all the
people who uses context in their daily work would like it if they
had to adapt their document regularly to some new syntax.

-- 
Ulrike Fischer 
http://www.troubleshooting-tex.de/

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