Hi, Why not submit cont-enp.pdf (ConTeXt the manual) to lulu? I do appreciate the hard work that's going into the documentation, but at some places the english doesn't flow that well. Out of curiosity how many people proof read the documentation before they're released? -- Thanks Mohamed Bana
On Monday 21 July 2008 07:58:55 pm abbg770@city.ac.uk wrote:
Hi,
Why not submit cont-enp.pdf (ConTeXt the manual) to lulu? I do appreciate the hard work that's going into the documentation, but at some places the english doesn't flow that well. Out of curiosity how many people proof read the documentation before they're released?
The cont-en manual, which I use reguarly, dates back to 2001 or so. No attempt is ever made to update it. New manuals each covering a feature or set of features abound. And of course there is Contextgarden. There are days when I feel like collecting all the bits and pieces and writing somthing myself. But then I lie down until the fit passes. -- John Culleton Resources for every author and publisher: http://wexfordpress.com/tex/shortlist.pdf http://wexfordpress.com/tex/packagers.pdf http://www.creativemindspress.com/newbiefaq.htm http://www.gropenassoc.com/TopLevelPages/reference%20desk.htm
On Jul 22, 2008, at 2:37 AM, John Culleton wrote:
There are days when I feel like collecting all the bits and pieces and writing somthing myself. But then I lie down until the fit passes.
The lack of proper end user documentation is one of the main problems with ConTeXt. There was talk of a book about ConTeXt but I haven't heard about that one for a while. Probably impossible given the lack of stability (aka ongoing development) of ConTeXt. ConTeXt could become very popular in teh TeX world if it had: - A decent versioning support (where you can get documentation and code that match and not code from 2008 with documentation from 2001) - Side-by-side development of manuals and code As it is now, the developing community is restricted to the few gurus who can hack the ConTeXt source code. No other sane person will try to release and support something on such a volatile foundation. What ConTeXt looks to me currently, is a personal swiss army knife of a few people who have no need for end user documentation (so it never arrives). I moved to ConTeXt years ago for a project expecting ConTeXt to stabilize and come with better documentation. It never happened. G
These are all my opinions, of course.
The lack of proper end user documentation is one of the main problems with ConTeXt.
Eventually, actually one of the main problems is the lack of people like Wolfgang Schuster . For sure the things can be better if everyone uses the wiki to search and update documentations or write solutions. There was talk of a book about ConTeXt but I haven't
heard about that one for a while. Probably impossible given the lack of stability (aka ongoing development) of ConTeXt.
mkii is not so instable. mkiv is under active development, but I'm using it for a catalog from october of last year.
ConTeXt could become very popular in teh TeX world if it had: - A decent versioning support (where you can get documentation and code that match and not code from 2008 with documentation from 2001) - Side-by-side development of manuals and code
More or less, TeX and Latext suffer of the same problem.
As it is now, the developing community is restricted to the few gurus who can hack the ConTeXt source code.
From what I know, the developer of ConTeXt is Hans Hagen. There are some texnicians who help in debuggings; there are some people (wolfgang,mojca, aditja,...) who know context better than others and offers their support on the mailing list (we also need more people like them) . BTW, we are lucky that developing is firmly on the hands of Hans.
No other sane person will try to
release and support something on such a volatile foundation.
It's no true. What
ConTeXt looks to me currently, is a personal swiss army knife of a few people who have no need for end user documentation (so it never arrives).
ConTeXt/mkiv actually is the most advanced macro_packages_system build on top of luatex, the successor of pdftex; it's a serious competitor in the world of typesetting systems. With lua build in, will attract more 'traditional' programmers than tex/latex/pdftex etc. It's an ongoing process of development, because it's not easy to develop luatex-mplib-mkiv in synch (and taco is another giant ) It can be true that actually context is hard to learn, but I don't think that this is the right moment for a book. And to be clear: without luatex, TeX will not survive. Only my 1cent. -- luigi
On Fri, 25 Jul 2008, Gerben Wierda wrote:
On Jul 22, 2008, at 2:37 AM, John Culleton wrote:
There are days when I feel like collecting all the bits and pieces and writing somthing myself. But then I lie down until the fit passes.
The lack of proper end user documentation is one of the main problems with ConTeXt. There was talk of a book about ConTeXt but I haven't heard about that one for a while. Probably impossible given the lack of stability (aka ongoing development) of ConTeXt.
I believe a ConTeXt book is possible even with the problem of chasing a moving target. The user interface has not changed in quite some time. Moreover, we do not need an exhaustive manual listing all the features of ConTeXt; we need a user manual that explains the most commonly used features. Currently, the trouble with writing a book is that there is no one way of installing ConTeXt. Hopefully that will change once the minimal become more stable. The other thing is font handling, which is becoming considerably simpler with mkiv. Another thing is math support, which still lacks certain features that are critical. The right to left typsetting support is just beginning, and I imagine it will take some time before we settle on a stable interface. However, if we look at typsetting text in European languages with figures, tables, and footnotes, the interface has been more of less stable for more than 5 years. So, we can have a book that talks about the most common issues of these features and does not try to be exhaustive. I believe that it will be very useful to a lot of new users. The trouble is that writing such a book is a considerable effort. I don't know how much incentive and motivation there is for the authors.
ConTeXt could become very popular in teh TeX world if it had: - A decent versioning support (where you can get documentation and code that match and not code from 2008 with documentation from 2001)
If you really want, you can get code from 2001 and then the code and documentation will watch (Just kidding).
- Side-by-side development of manuals and code
That is done partly. The sources are very well documented in the most part. But then, that is not user interface documentation, it is code documentation.
As it is now, the developing community is restricted to the few gurus who can hack the ConTeXt source code. No other sane person will try to release and support something on such a volatile foundation. What ConTeXt looks to me currently, is a personal swiss army knife of a few people who have no need for end user documentation (so it never arrives). I moved to ConTeXt years ago for a project expecting ConTeXt to stabilize and come with better documentation. It never happened.
Unfortunately, when it comes to choosing TeX based markup alternatives, you have two options: latex and context. Latex has been dorment for 15 years, and the developers are discussing the best way of solving complex typesetting problems and the best way to design a user interface. It is fairly well documented, because it is not evolving. (I don't know if LaTeX takes advantage of etex primitives or not). Context is adding new features constantly, there is not too much discussion on what is the best way to do things, Hans adds features that work, and not many people mind the not optimal speed or placements. The documentation is old, and at places woefully inadequate. So as a user, you have to choose between the less of the two evils :-(. One way for ConTeXt to develop is to become modular (i.e. follow the LaTeX model of development). Write a set of core macros, that are fixed and stable. Document them well. Write a regression suite. And do not change them. If you want new features, write a separate module with these features. Every few years, move some of the functionality of the modules into the core. This will help in solving the documentation problem. But what about package clashes? Should I load the module on math after the module on fonts but before the module for references? What about documentation of modules? I don't know if this is a better scenario. Another option is to have a editable book on wikibooks or some other similar site, with a pdf export. Then the users can correct the mistakes of the original book and the documentation will be up to date. There will be difference in styles, although I am not sure how much this will matter. The trouble with this model is that one will need to check the documentation. Will the "many eyes will avoid mistakes" model work? Aditya
On Jul 26, 2008, at 1:31 AM, Aditya Mahajan wrote:
The sources are very well documented in the most part. But then, that is not user interface documentation, it is code documentation
Exactly. Let's give a simple example. My project needs both footnotes and endnotes. For footnotes I have \setupfootnotes[conversion=set 2,way=bypage] in my environment file. For endnotes, I use \endnote and \placenotes[endnote] in a separate chapter in \backmatter. When I asked Hans in 2005 if footnotes and endnotes together were possible he finished a part of ConTeXt that was not quite done and after some testing it ended up in ConTeXt. This is how it works. What I would like now is to get my end notes per chapter at the end of the chapter (because I want to work on my project per chapter and make per-chapter pdf-files I can send to people). I have been looking for documentation on endnotes. The term still does not appear in any official ConTeXt manual, not on the ConTeXt wiki. So, \endnote and \placenotes[endnote] have been there for *years*. But there is *no* mention of it anywhere. For fun: try googling for "endnote placenote". So, let's look at the well documented code then \def\dodoflushnotes % per class, todo: handle endnotes here {\ifdim\ht\localpostponednotes>\zeropoint \bgroup \dochecknote \ifendnotes \else ;-) Seriously, do you really expect ordinary users to look at the code of ConTeXt to find out how things can be done? I think nobody thinks that. Also funny: Look at what the wiki tells me about \setupfootnotes: http://texshow.contextgarden.net/cmd/setupfootnotes . How should a simple user like myself ever find out that the above is possible reading the table in the wiki? And who else than ConTeXt developers can write this? Or is it the idea that many people reverse engineer what ConTeXt does and fill a Wiki that way? So, what we have is Hans' and Taco's (and maybe some others) swiss army knife under development. WIth LuaTeX and MKIV all efforts go into the development of the entirely new engine and all the technical know how on the inside. My expectation is that the situation with respect to user documentation is not going to improve soon. G
On Sat, 26 Jul 2008 04:38:42 +0200, Gerben Wierda wrote:
My expectation is that the situation with respect to user documentation is not going to improve soon.
I don't know one way or the other about this. I do know that there are only a few people (fewer than ten) who can even think of fixing it. I can write clearly, but if I were to try to write documentation for ConTeXt, I would have to waste all my time asking stupid questions of that same tiny group of people. From my own selfish point of view, the solution is simple. A freeze on all code, not even allowing bug fixes, until there's a comprehensive and unified document written by Hans and Taco (plus whoever else) that explains how to use all the features of ConTeXt, covering absolutely all possibilities including any features that are currently half-finished. Unless a new bug is introduced tomorrow that makes all ConTeXt projects come out completely blank, the nonexistent documentation makes all other bugs insignificant. (In fact, many apparent bugs turn out to have secret workarounds anyway, and those would obviously be in the documentation.) I know that such a project is viewed by Hans and Taco & co. as a waste of their time, and as something that should be done only after the current burst of development is finished. - It's already proven that development isn't going to finish, but evolve. - No one else can document ConTeXt without bothering the same people every five minutes anyway, so what's the difference? - Documentation *could* be maintained and updated by someone outside of the small group, *IF* there was a reasonably up-to-date base of correct and complete documentation for them to start from. Currently, there is no such thing. Perhaps a reasonable compromise would be to publicly set a date in the near future (sometime before the end of 2008) as "code-freeze day", when development comes to a complete stop and the documentation project begins. Bringing a writer from outside and getting him "up to speed" has obviously become completely impractical. Sincerely David
On Jul 27, 2008, at 9:40 PM, David wrote:
From my own selfish point of view, the solution is simple. A freeze on all code, not even allowing bug fixes, until there's a comprehensive and unified document written by Hans and Taco (plus whoever else) that explains how to use all the features of ConTeXt, covering absolutely all possibilities including any features that are currently half-finished. Unless a new bug is introduced tomorrow that makes all ConTeXt projects come out completely blank, the nonexistent documentation makes all other bugs insignificant. (In fact, many apparent bugs turn out to have secret workarounds anyway, and those would obviously be in the documentation.)
I know that such a project is viewed by Hans and Taco & co. as a waste of their time, and as something that should be done only after the current burst of development is finished.
I think this assessment is correct. And this is IMO also the problem. It is a waste for Taco & Hans because they themselves do not need documentation. Others do. Hence my analysis that ConTeXt is not a product but a personal swiss army knife for those few that actually work on ConTeXt and for all other users it is a borrowed swiss army knife without a proper manual.
- It's already proven that development isn't going to finish, but evolve.
Hence my analysis that there will probably never be decent documentation unless attitudes change. And as long as Taco & Hans keep developing ConTeXt it will probably not be documented. And gauging Hans & Taco, they will keep on developing ConTeXt until they stop ConTeXt alltogether.
- No one else can document ConTeXt without bothering the same people every five minutes anyway, so what's the difference?
I was attracted to ConTeXt partly because at first sight the interface looked promisingly clean and orthogonal. But the fact that only Hans & Taco can document ConTeXt for users and that all kind of secret workarounds are needed to make it work seems to indicate that assessment was wrong.
- Documentation *could* be maintained and updated by someone outside of the small group, *IF* there was a reasonably up-to-date base of correct and complete documentation for them to start from. Currently, there is no such thing.
Even that would not work because such a documentation maintainer would not be able to keep up with finding out what changed. You know what is funny and telling? Hans & co quite recently produced a detailed, well written 158(!)-page document about the change from ConTeXt MkII to MkIV. This is documentation (promised to be kept up to date) about the technical process of developing ConTeXt/LUATeX. About how it works, about technical issues regarding speed etc. Most of it will be for ever hidden from and not interesting for ConTeXt users. 158 pages. That is book sized! For intermediary documentation of an ongoing technical development process. See: http://www.pragma-ade.com/general/manuals/mk.pdf There is no reason for a project to be frozen to create documentation. What is needed is that the developers accept that user documentation is as important as technical documentation and technical work. The developers currently see user documentation as a waste of time, because they do not need it themselves, they 'should do that when the development is finished'. What it actually means is that they like technical work far more than documentation work. So, technical work will for ever get a higher priority above user documentation work. And there will always be technical work that needs to be done before the nasty task of creating proper documentation is taken up. Concurrently, the technical work itself is indeed in many places unfinished, half, etc., mainly those places that the developers themselves are not interested in as users or where they know about workarounds and hacks. Writing user documentation in fact forces the developers to end that state of affairs and forces them not only to do documentation work (which they do not like) but it also forces them to do technical work in areas they do not like nor find interesting for their own uses. Hence, again, the assessment that ConTeXt is a personal swiss army tool for a few people. I am really wondering these days. Is there a serious stable and usable (and supported) alternative for TeX for large projects, with many cross references, footnotes, endnotes, etc. etc.? G
Hi, While most of what Gerben states is close enough to the truth to be a matter of opinion, I really object to the tone of 'there is no documentation'. There is, in fact, a whole lot of documentation. It may be incomplete (especially when it comes to recent developments), but that is quite different from not having documentation at all. There are thousands of pages of documentation on pragma-ade.com, and pretending they are totally inadequate by not even asserting their assistance is unfair. Best wishes, Taco
On Jul 28, 2008, at 12:46 PM, Taco Hoekwater wrote:
Hi,
While most of what Gerben states is close enough to the truth to be a matter of opinion, I really object to the tone of 'there is no documentation'. There is, in fact, a whole lot of documentation. It may be incomplete (especially when it comes to recent developments), but that is quite different from not having documentation at all.
There are thousands of pages of documentation on pragma-ade.com, and pretending they are totally inadequate by not even asserting their assistance is unfair.
OK Taco, that is a fair point concerning my pov. To answer it: I have made my comments knowing quite well what documentation there is and my *personal* (your mileage may vary) experience is that it hardly helps me. My personal experience has been with a result of close to 100% that if I want to do something / find out something I am unable to find it in the docs. Also, depending on what doc you take, I recall getting different solutions (I am reminded of the various incompatible ways to do tables) and if I recall correctly some of it had to be hunted down in MAPS articles and such. Maybe the answers of my questions are there. But in that case the documentation is such that I consider myself in the situation that I am unable to get my help from it. And the documentation is not just incomplete for recent developments. I have an idea. Why not have a live ConTeXt manual.pdf where you add something in the proper location and compile the document every time you answer a question from a user? As you are the person answering anyway, it should be little extra work. For instance: I have put out a question about the (afaik completely undocumented, incomplete and certainly not recent) endnotes feature. Why not take the manual now, add the info in and recompile and do that every time a question arrives that is not in the manual or that is maybe unclear in the manual? I would suggest looking at ways to make it as easy as possible (that is, as little work as possible) for yourself to keep a user&reference manual up to date. Something simple and fundamental as endnotes should not be undocumented. And limitations (like what to do if you want images in endnotes) should be available in documentation. In fact, you need only maintain one single integrated document en keep it up to date with the current ConTeXt version. Then, when you make MkIV the current ConTeXt version (and not a beta using a beta of a new compiler) you freeze the old and move to the new. Is it perhaps the case that the source of the manual is so old that it will not compile with a current ConTeXt anymore? If not, why not update it so it is less than 7 or 9 years out of date? If so, what does that possibly tell you about how valid the contents itself still are? Yours, G PS. To my own surprise (as I am a TeX fan) I have recently started to think about researching non-TeX alternatives. PPS. Before pressing send I just had a look at what is there on the pragma-ade site: http://www.pragma-ade.com/document-1.htm. I do not see any documentation other than the 1999 excursion and the 2001 'all of ConTeXt' manual. Maybe I am looking in the wrong place for documentation?
Gerben Wierda wrote:
I have an idea. Why not have a live ConTeXt manual.pdf where you add something in the proper location and compile the document every time you answer a question from a user? As you are the person answering anyway, it should be little extra work.
This is a good idea, I'll take it up with Hans as soon as he is online and up to speed again. Best wishes, Taco
On Mon, 28 Jul 2008, Taco Hoekwater wrote:
Gerben Wierda wrote:
I have an idea. Why not have a live ConTeXt manual.pdf where you add something in the proper location and compile the document every time you answer a question from a user? As you are the person answering anyway, it should be little extra work.
This is a good idea, I'll take it up with Hans as soon as he is online and up to speed again.
I remmeber that at least the beginners manual were in a svn repository to which I had write access. I once tried to change the first chapter of the beginner's manual to be more in line with what I thought that a beginner would understand more easily, but then realized that the tone of that chapter different from the rest of the manual: just a differece between Hans' and my writing style. That is always the difficulty with a collaborative documentation. But it will be great if the main manual is updated so that it compiles with current ConTeXt. Also, there needs to be a documentation to tell how to use the existing ConTeXt documentation. I will try to clean up the wiki page sometime next month (sorry no time before that). Aditya
Hello, Am Montag, 28. Juli 2008 schrieb Gerben Wierda:
I have an idea. Why not have a live ConTeXt manual.pdf where you add something in the proper location and compile the document every time you answer a question from a user? As you are the person answering anyway, it should be little extra work.
A good idea! But from my pov it should be clarified a bit. We must distinguish between: - a user manual that tells you how to use the system and give you an overview of the whole system and the most important parts (pictures, math, etc.) - and a reference manual, that describes all available commands in detail. The user manual exists (excursion and manual) but has to be revised. The reference manual exists (http://texshow.contextgarden.net/) but is by far not complete. As it is very difficult to make an automated process for producing the user manual, the candidate for the proposed semiautomatic production is the reference manual. Where does the XML-files that are the basis for the existing texshow applications come from? The production of this file(s) has to be somehow bound to the current sourcecode. Then at least all commands are present and "only" the documentation has to be filled in. The last commands I have learned by asking on this list, are all not present in texshow so that I was not able to add the description there ... For the user manual(s) (in my opinion the excursion is a part of "the manual"), there are these steps necessary: - provide a sourceversion that works with the current state of context - identify the portions that are completely out of sync and cut them out (or mark them clearly as outdated) - provide pointers to the more current documentation for every part (and mark differences between mkii and mkiv) - add the missing main features and as a bonus to the reference manual: - make groups of commands that belong together and describe their interactions (something like the portal pages of wikipedia) As far as I understand the situation, the completion of the reference manual is a realistic goal for the near future. And it is possible that everyone helps with this by filling the answers you get on this list into the command descriptions. Wow, this has been gotten longer than I wanted it to be :-) But let me close with a HUGE big THANK YOU to Hans and Taco and the other people that make context such a great tool! Uwe
David wrote:
documentation makes all other bugs insignificant. (In fact, many apparent bugs turn out to have secret workarounds anyway, and those would obviously be in the documentation.)
this is not entirely true ... there is often more than one way to solve a problem (esp if there is no robust solution possible in tex); if there is no official interface (say method=...], it might be an indication that the solution is suboptimal, even if the finetuning feature is to stay forever
- Documentation *could* be maintained and updated by someone outside of the small group, *IF* there was a reasonably up-to-date base of correct and complete documentation for them to start from. Currently, there is no such thing.
there's the matter of what a user expects ... the core of context is rather stable and in that respect the 'old documentation' is still valid i.e. apart from 'new features, which may of interest to only a small group', the date on a manual does not tell much (i run quite some software which rather ancient manuals); for instance ... how many users are really interested in tricky xml support? Hans ----------------------------------------------------------------- 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 -----------------------------------------------------------------
On Jul 28, 2008, at 4:20 PM, Hans Hagen wrote:
there's the matter of what a user expects ... the core of context is rather stable and in that respect the 'old documentation' is still valid i.e. apart from 'new features, which may of interest to only a small group', the date on a manual does not tell much (i run quite some software which rather ancient manuals); for instance ... how many users are really interested in tricky xml support?
Only a few. But if I want to use ConTeXt to write a book I am definitely interested in something as mundane as endnotes. And stuff having to do with chapter beginnings, the way paragraphs should look (e.g. indentation, whitespace, line distance) for various types (e.g. a normal text paragraph, a long quote from another book, etc.). And with producing draft products (e.g. a B5 sized book that in draft is printed two-up with the even pages on the right). Or everything that has to do with ConTeXt's power in organizing projects and producing mltiple outputs from single sources. All stuff I have fought with in the past, some I find not intuitive, some of which to date I have not been able to solve in a satisfying way. Oh, and though the documentation may still be valid, I recall that I was trying to do cerrtain table stuff with what was available in the manual or excursion (the two documents that together make up the current ConTeXt documentation) and I was pointed to another way of doing tables in a MAPS article. Those are very, very mundane things you want when writing a book that are underdocumented, documented in locations that are outside the manual or not documented at all. I do not care if the manual is old. But the onging development of ConTeXt has been offered as a reason why the documentation is lacking. If this is nonsense, good. In that case there is no reason to improve the docs so they actualy give a good overview of how to do things in ConTeXt and understandable by non-ConTeXt-developers. G knuth.tex from the ConTeXt distribution says: Thus, I came to the conclusion that the designer of a new system must not only be the implementer and first large||scale user; the designer should also write the first user manual. The separation of any of these four components would have hurt \TeX\ significantly. If I had not participated fully in all these activities, literally hundreds of improvements would never have been made, because I would never have thought of them or perceived why they were important. But a system cannot be successful if it is too strongly influenced by a single person. Once the initial design is complete and fairly robust, the real test begins as people with many different viewpoints undertake their own experiments. Somehow, this might be applied to ConTeXt I think ;-). Three out of four afaic...
Gerben Wierda wrote:
Somehow, this might be applied to ConTeXt I think ;-). Three out of four afaic...
well, it's one reason why we have multiple smaller manuals (often made in sync with the specific feature) anyhow ... taco and i only have one livetime, 24h/day etc etc currently we spend quite some time on luatex/mp/mkiv (if not we could as well stop using tex in the near future) alongside our regular jobs ... we simply have not much more time available ... on the other hand, we don't intend to stop soon, so eventually ... btw, quite some documentation about latex is *not* written by the author(s) so it's not entirely fair to expect that taco and i write all of it -) Hans ----------------------------------------------------------------- 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 -----------------------------------------------------------------
On Jul 28, 2008, at 10:36 PM, Hans Hagen wrote:
Gerben Wierda wrote:
Somehow, this might be applied to ConTeXt I think ;-). Three out of four afaic...
well, it's one reason why we have multiple smaller manuals (often made in sync with the specific feature)
anyhow ... taco and i only have one livetime, 24h/day etc etc
As you know, I know what you are talking about. And it is important also to keep your cups from running over if we want ConTeXt to succeed.
currently we spend quite some time on luatex/mp/mkiv (if not we could as well stop using tex in the near future) alongside our regular jobs ...
I was wondering if you already know what you would have to use if not TeX. Is there an alternative at all?
we simply have not much more time available ... on the other hand, we don't intend to stop soon, so eventually ...
btw, quite some documentation about latex is *not* written by the author(s) so it's not entirely fair to expect that taco and i write all of it -)
But the initial manual (as Knuth said) is different from overview books like Kopka & Daly etc. Knuth wrote the TeXbook, the Metafont book. Lamport wrote the initial LaTeX book Packages for LaTeX like memoir come with a manual written by the authors. There are 'combination' manuals (Kopka etc) but they all are based on the availability of full initial manuals. But apart from that, the most imporant thing is that resources are scarce and you guys have limits we need to honour. I think we should find a way for you guys to go on and not get swamped by too much and thus we need to find a way to make your documentation work lighter (as obviously - for me - it does not get the attention it should). So I would propose to set up a way that a group of others can maintain documentation. Your task would then be an editor's task: proofread, suggest changes and agree. Minor changes can be done by the editors. major changes go past you and Taco as editors-in-chief. Your OK promotes it to alpha. And something like a manual (book) needs to be part of it. This should be based on (imo) merging the content of the excursion and the manual. The editors should be able to start a compilation run. The result should be the 'work in progress' pdf that has a fixed location on the pragma site. So, what we initially need is some sort of svn repository with access by a limited group, a mailing list for that group only. An e-mail adress to send documentation suggestions to. I am prepared to do some work on this (e.g. editor work). G
Hi Gerben, On Tue, 29 Jul 2008, Gerben Wierda wrote:
This should be based on (imo) merging the content of the excursion and the manual.
Here (and sometime earlier in the thread) you have suggested that you find the scattered documentation of ConTeXt confusing and would like to see an exhaustive manual. I agree with that in principle, but still believe that excursion and the manual should be separate. The manual can be a superset of excursion, but there needs to be "beginner's manual". If there is a exhaustive manual, it will be *huge*. An exhaustive manual on math will be of the size of a book; so would an exhaustive manual on metapost/mp-lib (think of an updated metafun manual). I can also imagine an exhaustive manual for fonts to be big (how do we handle fonts for lua/xetex/pdftex; how do we handle fonts for different scripts, etc.); and fairly large manuals for floats (three four mechanism for tables, about 20 ways to move around floats, etc.), critical editions (I don't know the status of the proposed module), bib module (the user manual for biblatex, which is similar in spirit to bib module, is huge), etc. So, if we want exhaustive documentation and a beginner's manual, I see that we only have the option of expanding on the excursion to have an upto date beginner's manual, expanding on the manual to have an upto date (but not exhaustive) user manual, and have a series of specialized exhaustive manuals. But that will still mean that the documentation is scattered. The way I see it, we can update the documentation, but not really solve the problem of scattered documentation :-( Aditya
On Jul 29, 2008, at 2:44 PM, Aditya Mahajan wrote:
Hi Gerben,
On Tue, 29 Jul 2008, Gerben Wierda wrote:
This should be based on (imo) merging the content of the excursion and the manual.
Here (and sometime earlier in the thread) you have suggested that you find the scattered documentation of ConTeXt confusing and would like to see an exhaustive manual. I agree with that in principle, but still believe that excursion and the manual should be separate. The manual can be a superset of excursion, but there needs to be "beginner's manual".
If there is a exhaustive manual, it will be *huge*. An exhaustive manual on math will be of the size of a book; so would an exhaustive manual on metapost/mp-lib (think of an updated metafun manual). I can also imagine an exhaustive manual for fonts to be big (how do we handle fonts for lua/xetex/pdftex; how do we handle fonts for different scripts, etc.); and fairly large manuals for floats (three four mechanism for tables, about 20 ways to move around floats, etc.), critical editions (I don't know the status of the proposed module), bib module (the user manual for biblatex, which is similar in spirit to bib module, is huge), etc.
So, if we want exhaustive documentation and a beginner's manual, I see that we only have the option of expanding on the excursion to have an upto date beginner's manual, expanding on the manual to have an upto date (but not exhaustive) user manual, and have a series of specialized exhaustive manuals. But that will still mean that the documentation is scattered.
The way I see it, we can update the documentation, but not really solve the problem of scattered documentation :-(
Before things balloon to a size it is not feasible anymore, I would suggest keeping manual&reference apart from introductory documents like excursion or 'beginners manual'. And I would be very happy if there was only one decent manual&reference maintained by a group of people, complete and up to date. thers could maintain a beginner's manual on the basis of that, but add the maintenance of a second beginner's manual and suddenly one needs to maintain two things. This cannot completely be avoided (as also in the manual the same thing will be in many places as technique 1 is part of the example for technique 2, etc.). At first, I would suggest that the documentation project would consider itself with one thing: a 'user & reference manual' for ConTeXt. If that succeeds and people have energy left they can do a simplified beginner's manual. Note: personally, I think a beginner's manual could be part of the big manual. Say, an 'excursion' chapter or a 'beginner's section' at the start of each chapter.. G
Gerben Wierda wrote:
I was wondering if you already know what you would have to use if not TeX. Is there an alternative at all?
no, i'd probably choose a completely other job then (ok, maybe general programming as part time then) ... i simply can not use a program that i know will be replaced within 5 years Hans ----------------------------------------------------------------- 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 -----------------------------------------------------------------
On Jul 29, 2008, at 8:05 PM, Hans Hagen wrote:
I was wondering if you already know what you would have to use if not TeX. Is there an alternative at all?
no, i'd probably choose a completely other job then (ok, maybe general programming as part time then) ... i simply can not use a program that i know will be replaced within 5 years
Did you look at Lout? Font-wise restricted at first glance, but interesting nonetheless. Anyway, I still feel that something like LuaTeX with a decent ConTeXt is the best option. But the project could do with funding by some rich former dot-com billionaire. Because if it does not get out of the tool shed phase, it will remain problematic for ordinary users like myself. G
Fabrice Popineau wrote:
i simply can not use a program that i know will be replaced within 5 years
And there are not so many stable tools. TeX and Lisp.
:-)
and hopefully lua -) Hans ----------------------------------------------------------------- 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 -----------------------------------------------------------------
participants (10)
-
abbg770＠city.ac.uk -
Aditya Mahajan -
David -
Fabrice Popineau -
Gerben Wierda -
Hans Hagen -
John Culleton -
luigi scarso -
Taco Hoekwater -
Uwe Koloska