Re: suggestions for context documentation

Re: suggestions for context documentation

[Victor Eijkhout]

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

> \startitem Even an old manual can quite well describe
> functionality as much didn't change. It's only with \MKIV\ that
> some compatibility is dropped and only for obscure features. Of
> course I could trick users by regenerating a manual with a newer
> date. I often use the excellent book \quote {\TEX\ by Topic} which
> is already quite old and does not cover \ETEX, \PDFTEX, \LUATEX\
> or whatever but what is told in it is still true. I never look at
> it thinking it being old. \stopitem

Hans,

thanks for the compliments.

Let me point out that the source of TeX by Topic is available under  
the Gnu Public Documentation License, so anyone should feel free to  
add modern TeX additions to it. Personally I feel that the eTeX &  
pdTeX additions are mature enough that they could be added, of course  
with suitable markers to indicate their non-standardness. I don't have  
the time for this, but I'd welcome a collaboration with anyone that  
wants to invest the time.

Victor.


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

[-- Attachment #2: Type: text/plain, Size: 486 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: suggestions for context documentation

[Alan BRASLAU]

On Monday 08 March 2010 13:31:28 Hans Hagen wrote:
> 
> As I was on the Dante 2010 meeting and as I could not access my
> mail last week, today I ran into the long thread about
> documentation. I will not reply to each mail but stick to this
> summary. Now, I understand that there is a lack of documentation
> but before one complains too loud about it, consider the
> following:
> 

I was out of town for the last two weeks. I too saw this thread
but did not have the time to read it all.

I agree that the ConTeXt reference manual needs to be updated
and completed, in particular concerning mkIV. Nevertheless, I have
been able to get quite far using the (old) mkII manual and find it
to be pretty good, even if not perfect. For this reason, I had
contacted Hans and Taco to gain access to the source but have to date
made only a few, minor corrections. This is a project that I try to
work on in my "spare time". As none of us have much time to spare
from our other responsibilities, documentation always proceeds too slowly.
(Indeed, while traveling the last two weeks, I had hoped to have some
time available to work more on this. However, I did not do anything!)

Part of the problem with writing documentation is being expert enough
to know all of the in's and out's of ConTeXt. Nevertheless, I believe
that improvements can be done. Also, taking such initiative will motivate
the real experts to eventually complete the holes (or give hints
on what further to include).

Alan

P.S. Concerning LaTeX, whereas the User's Guide and Reference Manual
(what we locally call "the lion") and the Companion (1st edition,
what we call "the dog") are excellent starting points. I find
that the second edition to be confusing and so hardly ever refer to it.
The documentation of the diverse packages is of diverse quality.

___________________________________________________________________________________
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: suggestions for context documentation

[Hans Hagen]

\usemodule
   [abr-01]

\setuplayout
   [width=middle,
    height=middle,
    footer=0cm,
    topspace=1.5cm]

\setupbodyfont
   [palatino]

\setupheader
   [state=high]

\setupwhitespace
   [big]

\starttext

Hi all,

As I was on the Dante 2010 meeting and as I could not access my
mail last week, today I ran into the long thread about
documentation. I will not reply to each mail but stick to this
summary. Now, I understand that there is a lack of documentation
but before one complains too loud about it, consider the
following:

\startitemize

\startitem We started with \CONTEXT\ in the early 90's and it went
public around 1995. So, we're 15 years down the road. Whatever
comment one has on the system, including its documentation, has to
be seen into this light: we're looking back at over 15 years of
development and ahead at quite some more. \stopitem

\startitem In all those years we've been writing a lot of code,
not only for our own use, but also for users. Just to mention a
few areas: specific language and font support is non trivial in
traditional \TEX\ and took quite some time and backends change and
being involved in the development also brings a price (in many
aspects). \stopitem

\startitem What started a system for our own use, is now used by
others as well, and this brings not only the responsibility to fix
bugs fast but also to monitor lists etc.\ Add to that quite some
involvement in \TEX\ user groups, conferences, writing articles
etc.\ In the process we also happen to come up with some manuals.
Just wonder for a while where I find the time to do my regular
work (the work that pays the bills). \stopitem

\startitem Even an old manual can quite well describe
functionality as much didn't change. It's only with \MKIV\ that
some compatibility is dropped and only for obscure features. Of
course I could trick users by regenerating a manual with a newer
date. I often use the excellent book \quote {\TEX\ by Topic} which
is already quite old and does not cover \ETEX, \PDFTEX, \LUATEX\
or whatever but what is told in it is still true. I never look at
it thinking it being old. \stopitem

\startitem As one can visually get all kind of output and as
typographical elements can interfere the ultimate manual would
show $n!$ variants and become quite unreadable. There is no easy
way out of this. For other languages there's a lot of code
googlable but I find myself always writing from scratch as each
case seems to be different. Of course printed manuals can be of
help (the \LUA\ book being a very good example of a manual) but
writing one takes time. \stopitem

\startitem More documentation would not help all users. Some are
better of with a simple manual and some occasional help on the
list. I've been using all kind of programming languages and the
fact that some have huge (auto generated) documentation systems is
no guarantee that they can be used. I find myself quite often just
look in the source to see what is (not) happening and then
probably feel as confused as users looking into \CONTEXT\ sources.
\stopitem

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

\startitem Any comparison with \LATEX\ documentation is useless.
One reason for starting to write \CONTEXT\ is that I didn't
understand the \LATEX\ book that well as well as that for proper
non English usage one had to patch unreadable code. When \CONTEXT\
came around the internet and mail were already replacing articles
and books. Just look at how the content in user group journals
changed from beginners explanations to more expert and niche
topics. Also, the fact that new books about \LATEX\ are still
written means that there is no perfect one yet. If you ever run
into one of the authors of the companions, just ask them how much
time it took \unknown\ close to a lifetime I bet. \stopitem

\startitem There was some comment on me being the only developer.
This might be true to a large extend but Taco, Wolfgang, Aditya,
Mojca, Luigi (I mention just a few currently active developers and
feel sorry for those I forget so feel free to amend me) know their
way around the source quite well and contribute patches too. We
don't have a formal team (as that would introduce the problem of
adding|/|removing active members and I like to be more informal
and users on the list know pretty well who are contributors.
\stopitem

\startitem There is no real cutting|-|out going on, it's just the
way it evolved. On the other hand, as I use the system myself I
would probably quit using it if anyone could push in code. It's
hard to keep \TEX\ doing what you want it to do and breaking it is
too easy due to interference. So, developers need some feeling
about what side effects can occur. Even then we see bugs creep in.
\stopitem

\startitem Believe me: when some folks send me a patch it goes in
without too much thinking. For instance, code that Wolfgang
submits fits perfectly in the \quote {design} of the system and I
trust any correction to math that Aditya sends me. At some point I
want to make it easier for those to work on the code directly but
it should not cripple my own workflows. \stopitem

\startitem At the last Dante meeting there were a some talks about
\LATEX. One was about how to let all those packages work together
(hard and error prone and unsolvable). Others were about what
package to use for what (similar) feature (without running into
conflicts). Arbitrary contributions are fine, but can become a
nightmare. Of course, for \CONTEXT\ one can write modules that
work quite well, as long as one uses the hooks provided and not
messes around with core commands. \stopitem

\startitem Just look at the excellent tutorials by Willi, Thomas,
Aditya and others (at \CONTEXT\ conferences for instance) and you
will notice that there is more info than on our website. \stopitem

\startitem Only the fact that we have a rather tight control over
development makes it possible for us to keep doing this. I work at
a quite small company and 75\% of my time goes into development
and support of \CONTEXT\ (and \LUATEX). To that you can add rather
specialized sub projects like the Oriental \TEX\ project where
we're talking of years of work just for free. It's might be true
that Taco and I are candidates for writing (and updating) manuals,
but we both have single|-|core minds. \stopitem

\startitem The user interface is indeed described in an \XML\
file. That info used to be spread over the source and actually in
the 90's it was used in a help system in an editor that only we
used. Eventually I might redistribute the \XML\ snippets over the
code again, but I'm not sure about it. Anyway, it's manual work to
keep that one up to date as we don't want experimental features to
exposed too soon, and because of inheritance issues. \stopitem

\startitem I don't use revision control in my source tree (after
all, when we started revision control was not that wide spread,
and I also don't have the patience for it) but all \CONTEXT\
releases are checked in eventually. I have been considering using
svn and might eventually use git on my machine but I'll only do it
when I do it for all \CONTEXT\ related code and that would mean
that I have to sort out 15 years of manuals, presentations,
articles, etc.\ I simply don't have time for that now (and it does
not gain me that much in my case). \stopitem

\startitem Concerning embedded documentation: this only makes
sense when \TEX\ is processing it as we need typeset examples.
Also, for me personally, I only work on a manual (or article or
whatever) if it's fun to do. The \METAFUN\ manual took me close to
a year of evenings (excluding the \MKIV update). Interesting is
that with \MKIV\ writing manuals is more convenient as embedded
\METAPOST\ runs are real fast now. \stopitem

\startitem The only generic manual markup I'm willing to use is
either \TEX\ or \XML\ (for multiple output). Of course others can
use whatever they want. When writing manuals the biggest issue is
not a bit of extensive tagging (so minimal markup is a no|-|go for
me personally) but the fact that we need to be able to process
code as examples which means that only \TEX\ (as \PDF) renderer)
can be used. I'm occasionally thinking of an \HTML\ backend but as
I don't need it I cannot spend time on it anyway. I might give
those pads a change when they get some quality, speed and battery
live. \stopitem

\startitem We're in the transition from \MKII\ to \MKIV. Most of
what applies to \MKII\ also applies to \MKIV\ but everything
encoding related is gone. Quite some font related stuff is new but
that's simply a side effect of going \OPENTYPE. Apart from that
most in the manuals is still quite valid. There are two history
documents (\type {mk.pdf} and \type {hybrid.pdf}) and they contain
info useful for developers but they are not advocated as user
manuals: they're test cases, historic overviews, development
notes, explorations or whatever description suits them. \stopitem

\startitem My experience is that \CONTEXT\ users are willing to
move on, and that comes with a price: if you use experimental
features you're mostly ok (as I use them myself interfaces are
unlikely to change anyway), but there is not much documentation
then. The documentation landscape would look less confusing if
we'd kick out \PDFTEX\ and \XETEX\ support (read: \MKII). We
should look forward. \stopitem

\startitem Several attempts have been made to come up with a test
suite (Sanjoy even implemented a test framework) but not that much
ended up in there: why should users do it if what gets posted on
the lists works okay? I am currently building a tree with test
files (based on snippets that get posted on the list) but I need
to sort it out before it gets into the source. So, we might revive
that project. \stopitem

\startitem Also, Luigi does a pretty good (and time consuming) job
on keeping the sources processable into module documentation. The
test suite will probably be part of Luigi's module documentation
system too (but he doesn't know that yet). \stopitem

\startitem Idris is writing a \CONTEXT\ book but even that cannot
cover everything. It's up to him to elaborate on that. \stopitem

\startitem You cannot compare a system with 20 years of history
with one of a few years. I'm not going to rewrite history and for
sure do things differently. Actually, the whole \LUATEX/\MKIV\
effort is sort of unique for the \TEX\ community as normally one
tends to stick to the past. As Taco and I are also part of
mainstream \TEX\ developments the users pay the price. \stopitem

\startitem Off topic: there is an \HTML\ variant of the \type
{cont-*.pdf} files, just run \typ {mtxrun --script server --auto}.
\stopitem

\startitem The \WIKI\ is a nice example of users contributions and
there are some quite good explanations on it. As with all
documentation, the more there is, the more confused users can get.
Users normally respond quite well when asked to wikify a solution.
I'm really grateful for all those user contributions and I hope
that Patrick will keep gardening and harvesting forever. \stopitem

\startitem The minimals are a nice example of an effort that moved
from being our work to users (mostly Mojca but as she's
multi|-|core, she counts for 10 users). I fear the moment when she
will say \quotation {enough is enough}. \stopitem

\startitem It has always been possible to add structured
documentation to the commands in the \WIKI\ interface but somehow
it never worked out well. Maybe a merge in the \WIKI\ will work
out ok. But \unknown\ it's users who have to fill it, as I simply
have no more time left. Also: write articles for the user group
journals. \stopitem

\startitem I have plans to put more manual code online. This
starts making sense now that internet access gets comfortable but
I will only do that with clean and properly coded documents so it
needs checking and therefore time. I only put stuff online that
makes me feel comfortable. Concerning the licences: these are
either the one that covers \CONTEXT\ or some creative common's one
(and then only a reference as I dislike wasting bytes (and time)
on those licences). \stopitem

\startitem Contrary to what users might think, a lot of code in
any \TEX\ macro package is written for the sake of documentation:
verbatim. Without verbatim much would look simpler (less
exceptions due to catcodes for instance). So, writing
documentation is no big deal: one only needs time. \stopitem

\stopitemize

\stoptext



-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
      tel: 038 477 53 69 | fax: 038 477 53 74 | www.pragma-ade.com
                                              | www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: suggestions for context documentation

[Willi Egger]

On 5 Mar 2010, at 13:50, Thomas A. Schmitz wrote:

>
> On Mar 5, 2010, at 11:01 AM, richard.stephens@converteam.com wrote:
>
>>
>> > No, not like those.  I mean like a real manual.  I read the book
>> > about Hasselt---a few examples without explanations.
>>
>> I am absolutely gobsmacked (astounded, astonished) at some of the  
>> comments on this and other threads!
>> "ConTeXt - an Excursion" and "ConTeXt the Manual" together are  
>> wonderful. I still consult them at least once a week
>> after 4 year's use. If you actually tried the examples in the  
>> former, rather than just reading them, you
>> would be an expert user within 2 days!
>
> Hear hear! I couldn't agree more and am happy that a voice of  
> reason appears in this somewhat meandering thread!
Indeed! I would sign this myself!
>
>>
>> It would be nice to think that the community could construct  
>> documentation, but good, coherent documentation
>> is much harder to produce than good code! It works for collections  
>> of small articles (WikiPedia etc), but
>> I've never seen a good book written by a community.
>
> also +1 Wasn't there this wonderful saying that a camel is a horse  
> designed by committee?
+1

Willi
>
> Thomas
> ______________________________________________________________________ 
> _____________
> 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: suggestions for context documentation

[Jörg Hagmann]

I agree, too.  I have praised the "Excursion" before -- an excellent 
one-author work -- and if you also consult the "Manual" you can do a 
lot.  For special questions, there is always Wolfgang ...

On 3/5/10 1:50 PM, Thomas A. Schmitz wrote:
>
> On Mar 5, 2010, at 11:01 AM, richard.stephens@converteam.com wrote:
>
>>
>> > No, not like those.  I mean like a real manual.  I read the book
>> > about Hasselt---a few examples without explanations.
>>
>> I am absolutely gobsmacked (astounded, astonished) at some of the 
>> comments on this and other threads!
>> "ConTeXt - an Excursion" and "ConTeXt the Manual" together are 
>> wonderful. I still consult them at least once a week
>> after 4 year's use. If you actually tried the examples in the former, 
>> rather than just reading them, you
>> would be an expert user within 2 days!
>
> Hear hear! I couldn't agree more and am happy that a voice of reason 
> appears in this somewhat meandering thread!
>
>>
>> It would be nice to think that the community could construct 
>> documentation, but good, coherent documentation
>> is much harder to produce than good code! It works for collections of 
>> small articles (WikiPedia etc), but
>> I've never seen a good book written by a community.
>
> also +1 Wasn't there this wonderful saying that a camel is a horse 
> designed by committee?
>
> Thomas
> ___________________________________________________________________________________ 
>
> 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
> ___________________________________________________________________________________ 
>
>

-- 
Prof. Jörg Hagmann-Zanolari MD
University of Basel
Department of Biomedicine
Institute of Biochemistry and Genetics
Mattenstrasse 28
CH-4058 Basel
Switzerland
Phone +41 (0)61 267 3565

___________________________________________________________________________________
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: suggestions for context documentation

[Marcin Borkowski]

Dnia Thu, Mar 04, 2010 at 08:10:43PM -0600, Michael Saunders napisał(a):
> > You mean like the beginner's manual
> >
> > http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf
> >
> > and the user manual
> >
> > http://www.pragma-ade.com/general/manuals/cont-eni.pdf
> >
> ...
> >
> > amongst 46 others by Pragma
> 
> 
> No, not like those.  I mean like a real manual.  I read the book
> about Hasselt---a few examples without explanations.
> I've looked at most of the fifty or so documents over which
> this virtual manual is supposed to be spread.  They are about
> as informative.  Most of these documents seem to be 5--12
> years old.  The wiki is even more patchy.  The idea that a
> computer manual is something that exists implicitly in the
> discussions of a mailing list is a new idea to me.
> 
> You can't be serious about "mk.pdf" being a manual.  Even it
> admits, "This document is not so much a users manual as a
> history of the development."  Little after that point is intelligible.
> 
> Compared with the clear, abundant documentation of the
> LaTeX world, Context seems like a secret that a small club is
> trying to keep.  It's not even clear from the manuals that
> development is ongoing, much less that there is some advantage
> in using it.
> 
> So, will there ever be a manual to MK IV?  In how many years?

Hi,

this is a strong (but fair, I believe) criticism.  I guess that we all
know that the main problem with ConTeXt is documentation; my feelings
are similar, and although I started using ConTeXt using the "user
manual" and asking on the list - and that helped a lot - having a good
user manual would be great.

I have to disagree, though, with the "clear, abundant documentation of
the LaTeX world".  This is far from true: the docs for LaTeX are spread
over numerous package documentations, not-so-well written books and
terribly written beginners' books (the LaTeX book on wikibooks is
awful, for example).  So the situation is pretty much similar to
ConTeXt.  The difference is that the LaTeX core is rather primitive
(compared to ConTeXt), and even a bad manual can do - and the mainstream
packages are usually well documented.  In case of ConTeXt, most
functionality one needs is in the core, which is documented as badly as
LaTeX's.

Regards

-- 
Marcin Borkowski (http://mbork.pl)

This program is written in Perl.  While stronger people find reading
Perl code character-building, it should not be shown to people in their
formative years.  The author will not accept any responsibility for any
moral grief caused.

	    (The McKornik Jr. Public License)
___________________________________________________________________________________
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: suggestions for context documentation

[Thomas A. Schmitz]

On Mar 5, 2010, at 11:01 AM, richard.stephens@converteam.com wrote:

>
> > No, not like those.  I mean like a real manual.  I read the book
> > about Hasselt---a few examples without explanations.
>
> I am absolutely gobsmacked (astounded, astonished) at some of the  
> comments on this and other threads!
> "ConTeXt - an Excursion" and "ConTeXt the Manual" together are  
> wonderful. I still consult them at least once a week
> after 4 year's use. If you actually tried the examples in the  
> former, rather than just reading them, you
> would be an expert user within 2 days!

Hear hear! I couldn't agree more and am happy that a voice of reason  
appears in this somewhat meandering thread!

>
> It would be nice to think that the community could construct  
> documentation, but good, coherent documentation
> is much harder to produce than good code! It works for collections  
> of small articles (WikiPedia etc), but
> I've never seen a good book written by a community.

also +1 Wasn't there this wonderful saying that a camel is a horse  
designed by committee?

Thomas
___________________________________________________________________________________
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: suggestions for context documentation

[Patrick Gundlach]

> While it would be nice to have an updated "ConTeXt the Manual", in my humble opinion the biggest hole 
> in the documentation is a reference for each command. Texshow-web should fill this gap and this is 
> where the community CAN contribute, and where the mechanism already exists. And because it's made up of 
> small articles it could work. When I learn about a command I try to fill in a few words in 
> texshow-web. If everyone added a few words each time they learn a new command, we would soon have 
> a fantastic reference source. 
> 
> Richard 
> 
> P.S. One request for improvement to texshow-web: the source-file for each command is included 
> in cont-en.xml, could this be displayed on the command web-page? It would make it easier to 
> find the source if you need to.

I have promised to Taco that I will transfer the contents of texshow-web to the wiki this month. Then we can do everything the wiki can do now.

Patrick

___________________________________________________________________________________
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: suggestions for context documentation

[richard.stephens]

[-- Attachment #1: Type: text/html, Size: 1298 bytes --]

[-- Attachment #2: Type: text/plain, Size: 486 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: suggestions for context documentation

[richard.stephens]

[-- Attachment #1: Type: text/html, Size: 2925 bytes --]

[-- Attachment #2: Type: text/plain, Size: 486 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: suggestions for context documentation

[R. Bastian]

On Thu, 4 Mar 2010 20:10:43 -0600
Michael Saunders <odradek5@gmail.com> scribit:

> > You mean like the beginner's manual
> >
> > http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf
> >
> > and the user manual
> >
> > http://www.pragma-ade.com/general/manuals/cont-eni.pdf
> >
> ...
> >
> > amongst 46 others by Pragma
> 
> 
> No, not like those.  I mean like a real manual.  I read the book
> about Hasselt---a few examples without explanations.
> I've looked at most of the fifty or so documents over which
> this virtual manual is supposed to be spread.  They are about
> as informative.  Most of these documents seem to be 5--12
> years old.  The wiki is even more patchy.  The idea that a
> computer manual is something that exists implicitly in the
> discussions of a mailing list is a new idea to me.
> 
> You can't be serious about "mk.pdf" being a manual.  Even it
> admits, "This document is not so much a users manual as a
> history of the development."  Little after that point is intelligible.
> 
> Compared with the clear, abundant documentation of the
> LaTeX world, ...

LoL

I have a good meter of books about Latex. But Latex is 'congenitally'
unable to do what I want to obtain. 

Within 6 months, with the Seroul book & the Context Manual & the help of
this list, I made more and better than in 10 years of Latex.

With Latex you must accept to do what Latex wants to be done. With
Context (and even with the older Tex), you are free (not free in an
denglish sense ('gratuit', 'kostenfrei'), but 'libre' or 'frei').



> Context seems like a secret that a small club is
> trying to keep.  It's not even clear from the manuals that
> development is ongoing, much less that there is some advantage
> in using it.
> 
> So, will there ever be a manual to MK IV?  In how many years?
> 

I think that the usersd need that the '[...,...,...]' should be replaced or referenced by
lists of parameters and we need a wiki-glossary of the params.

So we need a wiki to which users can access. I tried to access t the
contextgarden, but my access was forbidden. 

So it is true that Context is much more better than the way its access
is managed.



-- 
René Bastian
www.pythoneon.org
www.musiques-rb.org
http://www.soundsurvey.org.uk/


___________________________________________________________________________________
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: suggestions for context documentation

[luigi scarso]

On Fri, Mar 5, 2010 at 3:10 AM, Michael Saunders <odradek5@gmail.com> wrote:
>> You mean like the beginner's manual
>>
>> http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf
>>
>> and the user manual
>>
>> http://www.pragma-ade.com/general/manuals/cont-eni.pdf
>>
> ...
>>
>> amongst 46 others by Pragma
>
>
> No, not like those.  I mean like a real manual.  I read the book
> about Hasselt---a few examples without explanations.
> I've looked at most of the fifty or so documents over which
> this virtual manual is supposed to be spread.  They are about
> as informative.  Most of these documents seem to be 5--12
> years old.  The wiki is even more patchy.  The idea that a
> computer manual is something that exists implicitly in the
> discussions of a mailing list is a new idea to me.
cont-en & metafun are real manuals for mkii.
And yes, mkii is almost 10years old , and  maybe some options of
some macros are changed
What do you mean as "real manual" ?

>
> You can't be serious about "mk.pdf" being a manual.  Even it
> admits, "This document is not so much a users manual as a
> history of the development."  Little after that point is intelligible.
mkiv is still in development.
If one knows mkii,
then  mk.pdf and luatexref-x.pdf are important to help in
understanding mkiv, but it's not enough .
One must also knowns   lua, fontforge  , opentype,
unicode utf-8 TeX internal, xml ...
Actually mkiv is not for end user but it will be for sure in the
future , ~2012 estimated.

>
> Compared with the clear, abundant documentation of the
> LaTeX world, Context seems like a secret that a small club is
> trying to keep.  It's not even clear from the manuals that
> development is ongoing, much less that there is some advantage
> in using it.
One important point of mkiv are opentype fonts.
It's really hard in LaTeX to manage opentype fonts (remember the Adobe
produce only opentype fonts), and it's also hard in mkii --- but better.
mkiv actually already manage opentype fonts in a decent way, if one
compares with mkii.

Another point is Lua (a "traditional" programming language)  as a tool
for macro writer,
and I can assure that it' more fun/productive to use Lua than TeX in
some situations (eg parsing)
even if  TeX side of ConTeXt is  still indispensable (and will remain).



Context is not and doesn't seem a secret club:
"normal" programming is hard, programming with TeX is harder than
"normal" programming ,
typographic programming is a kind  of magic -- no books other than TexBook.
But in the end one must sit down and write his own code, and the
codebase is the best source for learning.
ConTeXt is a format for typographic programming --- maybe not user
friendly for and end user;
LaTeX is a format for end user --- not so good for general typographic
programming .


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

Re: suggestions for context documentation

[Vnpenguin]

On Fri, Mar 5, 2010 at 03:10, Michael Saunders <odradek5@gmail.com> wrote:
>
> You can't be serious about "mk.pdf" being a manual.  Even it
> admits, "This document is not so much a users manual as a
> history of the development."  Little after that point is intelligible.
>

Yes, I agree with you on this point !
___________________________________________________________________________________
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: suggestions for context documentation

[Khaled Hosny]

On Fri, Mar 05, 2010 at 05:34:39AM +0100, Wolfgang Schuster wrote:
> Am 05.03.10 03:10, schrieb Michael Saunders:
> 
>     I've looked at most of the fifty or so documents over which
>     this virtual manual is supposed to be spread.  They are about
>     as informative.  Most of these documents seem to be 5--12
>     years old.
> 
> 
> *The LaTeX manual* is 16 years old.
> 
> http://www.pearsonhighered.com/educator/product/
> LaTeX-A-Document-Preparation-System/9780201529838.page
> 

But LaTeX didn't change since then, unlike ConTeXt (even MkII is under
documented).

Regards,
 Khaled


-- 
 Khaled Hosny
 Arabic localiser and member of Arabeyes.org team
 Free font developer
___________________________________________________________________________________
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: suggestions for context documentation

[Wolfgang Schuster]

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

Am 05.03.10 03:10, schrieb Michael Saunders:
> I've looked at most of the fifty or so documents over which
> this virtual manual is supposed to be spread.  They are about
> as informative.  Most of these documents seem to be 5--12
> years old.
>    
*The LaTeX manual* is 16 years old.

http://www.pearsonhighered.com/educator/product/LaTeX-A-Document-Preparation-System/9780201529838.page

\bye

Wolfgang


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

[-- Attachment #2: Type: text/plain, Size: 486 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: suggestions for context documentation

[James Fisher]

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

Just to clarify, I pretty much agree with everything you say.

On Fri, Mar 5, 2010 at 2:22 AM, James Fisher <jameshfisher@gmail.com> wrote:

> "...the book about Hasselt". That actually made me laugh out loud.  What a
> loser I am.
>
> Ok, goodnight now. :)
>
>
> On Fri, Mar 5, 2010 at 2:10 AM, Michael Saunders <odradek5@gmail.com>wrote:
>
>> > You mean like the beginner's manual
>> >
>> > http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf
>> >
>> > and the user manual
>> >
>> > http://www.pragma-ade.com/general/manuals/cont-eni.pdf
>> >
>> ...
>> >
>> > amongst 46 others by Pragma
>>
>>
>> No, not like those.  I mean like a real manual.  I read the book
>> about Hasselt---a few examples without explanations.
>> I've looked at most of the fifty or so documents over which
>> this virtual manual is supposed to be spread.  They are about
>> as informative.  Most of these documents seem to be 5--12
>> years old.  The wiki is even more patchy.  The idea that a
>> computer manual is something that exists implicitly in the
>> discussions of a mailing list is a new idea to me.
>>
>> You can't be serious about "mk.pdf" being a manual.  Even it
>> admits, "This document is not so much a users manual as a
>> history of the development."  Little after that point is intelligible.
>>
>> Compared with the clear, abundant documentation of the
>> LaTeX world, Context seems like a secret that a small club is
>> trying to keep.  It's not even clear from the manuals that
>> development is ongoing, much less that there is some advantage
>> in using it.
>>
>> So, will there ever be a manual to MK IV?  In how many years?
>>
>> ___________________________________________________________________________________
>> 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: 3423 bytes --]

[-- Attachment #2: Type: text/plain, Size: 486 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
___________________________________________________________________________________

suggestions for context documentation

[Michael Saunders]

> You mean like the beginner's manual
>
> http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf
>
> and the user manual
>
> http://www.pragma-ade.com/general/manuals/cont-eni.pdf
>
...
>
> amongst 46 others by Pragma


No, not like those.  I mean like a real manual.  I read the book
about Hasselt---a few examples without explanations.
I've looked at most of the fifty or so documents over which
this virtual manual is supposed to be spread.  They are about
as informative.  Most of these documents seem to be 5--12
years old.  The wiki is even more patchy.  The idea that a
computer manual is something that exists implicitly in the
discussions of a mailing list is a new idea to me.

You can't be serious about "mk.pdf" being a manual.  Even it
admits, "This document is not so much a users manual as a
history of the development."  Little after that point is intelligible.

Compared with the clear, abundant documentation of the
LaTeX world, Context seems like a secret that a small club is
trying to keep.  It's not even clear from the manuals that
development is ongoing, much less that there is some advantage
in using it.

So, will there ever be a manual to MK IV?  In how many years?
___________________________________________________________________________________
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: suggestions for context documentation

[Aditya Mahajan]

On Thu, 4 Mar 2010, James Fisher wrote:

> Good news on both counts, then.  (Is there a reason that the source and
> license of the documents aren't included in the docs themselves?)

All the docs refer to the readme file which states the license
http://wiki.contextgarden.net/Read_Me

Aditya
___________________________________________________________________________________
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: suggestions for context documentation

[James Fisher]

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

Good news on both counts, then.  (Is there a reason that the source and
license of the documents aren't included in the docs themselves?)

On Thu, Mar 4, 2010 at 11:05 PM, Aditya Mahajan <adityam@umich.edu> wrote:

> On Thu, 4 Mar 2010, James Fisher wrote:
>
>  A bit of a diversion here, but two questions about the plethora of PDF
>> docs:
>>
>> * Where are the TeX sources of all these manuals kept?
>>
>
> svn://ctx.pragma-ade.nl/manuals (seems to be down at the moment)
>
> browsable at
>
> http://context.aanhet.net/svn/
>
> This information is also available on the wiki (
> http://wiki.contextgarden.net/Official_ConTeXt_Documentation)
>
>
>  * What are the licenses on all these various things?  In particular the
>> Pragma documents.  Would I be *allowed*, if I so wanted, to embark on a
>> collated version of all of this -- i.e., are derivative works allowed?
>>
>
> The program code (i.e. anything not under the /doc subtree) is distributed
> under the GNU GPL; the documentation is provided under Creative Commons
> Attribution NonCommercial ShareAlike license.
>
> So, derivative work is allowed, provided you do not sell your work.
>
> The new user manaul
> http://foundry.supelec.fr/gf/project/contextman/scmsvn/?action=browse&path=%2Fcontext-reference%2F
> is a attempt to be a collected version of all the documents, and it is
> under GNU Free Documentation License, so if you copy from there, your result
> should have the same license.
>
>
> Aditya
>
> ___________________________________________________________________________________
> 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: 3422 bytes --]

[-- Attachment #2: Type: text/plain, Size: 486 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: suggestions for context documentation

[Aditya Mahajan]

On Thu, 4 Mar 2010, James Fisher wrote:

> A bit of a diversion here, but two questions about the plethora of PDF docs:
>
> * Where are the TeX sources of all these manuals kept?

svn://ctx.pragma-ade.nl/manuals (seems to be down at the moment)

browsable at

http://context.aanhet.net/svn/

This information is also available on the wiki 
(http://wiki.contextgarden.net/Official_ConTeXt_Documentation)

> * What are the licenses on all these various things?  In particular the
> Pragma documents.  Would I be *allowed*, if I so wanted, to embark on a
> collated version of all of this -- i.e., are derivative works allowed?

The program code (i.e. anything not under the /doc subtree) is distributed 
under the GNU GPL; the documentation is provided under Creative Commons 
Attribution NonCommercial ShareAlike license.

So, derivative work is allowed, provided you do not sell your work.

The new user manaul 
http://foundry.supelec.fr/gf/project/contextman/scmsvn/?action=browse&path=%2Fcontext-reference%2F
is a attempt to be a collected version of all the documents, and it is 
under GNU Free Documentation License, so if you copy from there, your 
result should have the same license.

Aditya
___________________________________________________________________________________
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: suggestions for context documentation

[James Fisher]

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

A bit of a diversion here, but two questions about the plethora of PDF docs:

* Where are the TeX sources of all these manuals kept?
* What are the licenses on all these various things?  In particular the
Pragma documents.  Would I be *allowed*, if I so wanted, to embark on a
collated version of all of this -- i.e., are derivative works allowed?

James

On Thu, Mar 4, 2010 at 9:40 PM, Aditya Mahajan <adityam@umich.edu> wrote:

> On Thu, 4 Mar 2010, Michael Saunders wrote:
>
>  The important thing is:  is there _ever_ going to be a manual?   I
>>
>
> You mean like the beginner's manual
>
> http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf
>
> and the user manual
>
> http://www.pragma-ade.com/general/manuals/cont-eni.pdf
>
>
>  want to try Context, but I've been putting it off for years because
>> it's not really practical without documentation.
>>
>
> Things that have changed in MKIV
> http://www.pragma-ade.com/general/manuals/mk.pdf
>
> Integrating metafun graphics
> http://www.pragma-ade.com/general/manuals/metafun-s.pdf
>
> On typography
> http://www.pragma-ade.com/general/manuals/style.pdf
>
> XML
> http://pragma-ade.com/general/manuals/xml-mkiv.pdf
>
> amongst 46 others by Pragma
>
> http://pragma-ade.com/show-man-1.htm
> http://wiki.contextgarden.net/This_Way
>
> and other user written documents
>
> http://wiki.contextgarden.net/MyWay
>
> and then there is the wiki.
>
> I agree that some of these are outdated, some are not complete, but
> documentation does exist. What is missing in the documentation that
> prevented you from even starting using ConTeXt for *years*.
>
> Aditya
>
>
> ___________________________________________________________________________________
> 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: 4032 bytes --]

[-- Attachment #2: Type: text/plain, Size: 486 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: suggestions for context documentation

[Aditya Mahajan]

On Thu, 4 Mar 2010, Michael Saunders wrote:

> The important thing is:  is there _ever_ going to be a manual?   I

You mean like the beginner's manual

http://www.pragma-ade.com/general/manuals/ms-cb-en.pdf

and the user manual

http://www.pragma-ade.com/general/manuals/cont-eni.pdf

> want to try Context, but I've been putting it off for years because
> it's not really practical without documentation.

Things that have changed in MKIV
http://www.pragma-ade.com/general/manuals/mk.pdf

Integrating metafun graphics
http://www.pragma-ade.com/general/manuals/metafun-s.pdf

On typography
http://www.pragma-ade.com/general/manuals/style.pdf

XML
http://pragma-ade.com/general/manuals/xml-mkiv.pdf

amongst 46 others by Pragma

http://pragma-ade.com/show-man-1.htm
http://wiki.contextgarden.net/This_Way

and other user written documents

http://wiki.contextgarden.net/MyWay

and then there is the wiki.

I agree that some of these are outdated, some are not complete, but 
documentation does exist. What is missing in the documentation that 
prevented you from even starting using ConTeXt for *years*.

Aditya
___________________________________________________________________________________
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: suggestions for context documentation

[luigi scarso]

On Thu, Mar 4, 2010 at 10:31 PM, Michael Saunders <odradek5@gmail.com> wrote:
> The important thing is:  is there _ever_ going to be a manual?   I
> want to try Context, but I've been putting it off for years because
> it's not really practical without documentation.  There must be many
> others in the same situation.
For mkii there are cont-en and metafun plus some other articles.
It's a bit outdate, but still valid in general.

For mkiv : are you sure ?
If yes, mk.pdf , luatexref-t.pdf , the code.

For both : wiki and mailing list

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

suggestions for context documentation

[Michael Saunders]

The important thing is:  is there _ever_ going to be a manual?   I
want to try Context, but I've been putting it off for years because
it's not really practical without documentation.  There must be many
others in the same situation.
___________________________________________________________________________________
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: suggestions for context documentation

[James Fisher]

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

Hi Peter,


Thanks for your thoughts.  I have wondered previously (in other projects)
about the legitimacy of a distinction between manuals and command
references.  With a lot of effort, it can work -- but to make it work,
duplication is inevitable.  Manuals simply have to make references to
commands, and I suspect that a 'comprehensive' user-friendly user manual is
nothing but a comprehensive command reference, with the commands organised
in a human way, with interspersed commentary, suggestions for use, and
examples of usage.

I'm in complete agreement, though, that however this is done, a VCS is
necessary.  (I'm plugging git as my favourite, but it's just the principle
I'm arguing for here.)


James


On Thu, Mar 4, 2010 at 2:41 PM, Peter Münster <pmlists@free.fr> wrote:

> Hello,
>
> These suggestions are a bit a reply to the thoughts of James Fisher.
>
> It would be nice, to have once in the future at least 2 up to date context
> documentations:
>
> - a context user manual
> For me, it's the merge of all scattered articles and manuals. Each chapter
> treats a particular subject, such as "columns" or "footnotes".
> It seems, that Taco is working on such a manual.
>
> - a context command reference manual
> This is just the xml-database used by texshow. Each command should be
> described in detail with every possible options.
> On the one hand, texshow uses this database, on the other hand a well
> structured command reference can be generated as pdf-file.
>
> Filling in all the details in both projects is a lot of work, so perhaps it
> would be a good idea, to set up a system, that makes it easy for users to
> contribute to these projects (patches) and easy for Taco and Hans to
> acknowledge or reject those patches.
>
> This "system" would be nothing else as some vcs (git or svn for example)
> with some commit-hooks, that manage the acknowledgement by Hans and Taco
> (and perhaps others).
>
> The tex-files of the user-manual are already under version control, and the
> xml-database is only the cont-en.xml file, that would need to be put under
> version control too.
>
> So, perhaps with not too much effort, users can be easily invited to
> contribute to the documentation projects and the quality can be assured
> through the acknowledgements of the developers.
>
> Cheers, Peter
>
> --
> Contact information: http://pmrb.free.fr/contact/
>
>
>
> ___________________________________________________________________________________
> If your question is of interest to others as well, please add an entry to
> the Wiki!
>
> maillist : ntg-context@ntg.nl /
> http://www.ntg.nl/mailman/listinfo/ntg-context
> webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
> archive  : http://foundry.supelec.fr/projects/contextrev/
> wiki     : http://contextgarden.net
>
> ___________________________________________________________________________________
>

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

[-- Attachment #2: Type: text/plain, Size: 486 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
___________________________________________________________________________________

suggestions for context documentation

[Peter Münster]

Hello,

These suggestions are a bit a reply to the thoughts of James Fisher.

It would be nice, to have once in the future at least 2 up to date context
documentations:

- a context user manual
For me, it's the merge of all scattered articles and manuals. Each chapter
treats a particular subject, such as "columns" or "footnotes".
It seems, that Taco is working on such a manual.

- a context command reference manual
This is just the xml-database used by texshow. Each command should be
described in detail with every possible options.
On the one hand, texshow uses this database, on the other hand a well
structured command reference can be generated as pdf-file.

Filling in all the details in both projects is a lot of work, so perhaps it
would be a good idea, to set up a system, that makes it easy for users to
contribute to these projects (patches) and easy for Taco and Hans to
acknowledge or reject those patches.

This "system" would be nothing else as some vcs (git or svn for example)
with some commit-hooks, that manage the acknowledgement by Hans and Taco
(and perhaps others).

The tex-files of the user-manual are already under version control, and the
xml-database is only the cont-en.xml file, that would need to be put under
version control too.

So, perhaps with not too much effort, users can be easily invited to
contribute to the documentation projects and the quality can be assured
through the acknowledgements of the developers.

Cheers, Peter

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


___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________