Re: [NTG-context] suggestions for context documentation
\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.
___
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: [NTG-context] suggestions for context documentation
\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
Re: [NTG-context] suggestions for context documentation
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: [NTG-context] suggestions for context documentation
On Fri, Mar 5, 2010 at 3:10 AM, Michael Saunders odrad...@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: [NTG-context] suggestions for context documentation
On Thu, 4 Mar 2010 20:10:43 -0600
Michael Saunders odrad...@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: [NTG-context] suggestions for context documentation
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! 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. 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. Converteam UK Ltd. Registration Number: 5571739 and Converteam Ltd. Registration Number: 2416188 Registered in England and Wales. Registered office: Boughton Road, Rugby, Warwickshire, CV21 1BU. CONFIDENTIALITY : This e-mail and any attachments are confidential and may be privileged. If you are not a named recipient, please notify the sender immediately and do not disclose the contents to another person, use it for any purpose or store or copy the information in any medium. Please consider the environment before printing this e-mail ___ 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: [NTG-context] suggestions for context documentation
There's another feature that would be REALLY useful in texshow-web: the ability to show the output from code, in the same way that the Wiki shows the output from code between context and /context. Is this a possibility? Richard P.S. There is an error in cont-en.xml for the command lohi: the keyword is shown as low when it should be left. Converteam UK Ltd. Registration Number: 5571739 and Converteam Ltd. Registration Number: 2416188 Registered in England and Wales. Registered office: Boughton Road, Rugby, Warwickshire, CV21 1BU. CONFIDENTIALITY : This e-mail and any attachments are confidential and may be privileged. If you are not a named recipient, please notify the sender immediately and do not disclose the contents to another person, use it for any purpose or store or copy the information in any medium. Please consider the environment before printing this e-mail ___ 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: [NTG-context] suggestions for context documentation
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: [NTG-context] suggestions for context documentation
On Mar 5, 2010, at 11:01 AM, richard.steph...@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: [NTG-context] suggestions for context documentation
Dnia Thu, Mar 04, 2010 at 08:10:43PM -0600, Michael Saunders napisa#322;(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: [NTG-context] suggestions for context documentation
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.steph...@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: [NTG-context] suggestions for context documentation
On 5 Mar 2010, at 13:50, Thomas A. Schmitz wrote: On Mar 5, 2010, at 11:01 AM, richard.steph...@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 ___
[NTG-context] suggestions for context documentation
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 ___
Re: [NTG-context] suggestions for context documentation
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 pmli...@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 ___ ___ 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 ___
[NTG-context] suggestions for context documentation
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: [NTG-context] suggestions for context documentation
On Thu, Mar 4, 2010 at 10:31 PM, Michael Saunders odrad...@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 ___
Re: [NTG-context] suggestions for context documentation
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: [NTG-context] suggestions for context documentation
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 adit...@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 ___ ___ 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: [NTG-context] suggestions for context documentation
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=browsepath=%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: [NTG-context] suggestions for context documentation
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 adit...@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=browsepath=%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 ___ ___ 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: [NTG-context] suggestions for context documentation
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 ___
[NTG-context] suggestions for context documentation
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: [NTG-context] suggestions for context documentation
...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 odrad...@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 ___ ___ 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: [NTG-context] suggestions for context documentation
Just to clarify, I pretty much agree with everything you say. On Fri, Mar 5, 2010 at 2:22 AM, James Fisher jameshfis...@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 odrad...@gmail.comwrote: 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 ___ ___ 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: [NTG-context] suggestions for context documentation
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 ___ 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: [NTG-context] suggestions for context documentation
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: [NTG-context] suggestions for context documentation
On Fri, Mar 5, 2010 at 03:10, Michael Saunders odrad...@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 ___
