From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.comp.tex.context/88111 Path: news.gmane.org!not-for-mail From: Hans Hagen Newsgroups: gmane.comp.tex.context Subject: Re: State of documentation of ConTeXt? Date: Tue, 15 Jul 2014 22:08:16 +0200 Message-ID: <53C58A30.1030106@wxs.nl> References: <1642f57885676cbd1020027a2bff7c40.squirrel@webmail.xs4all.nl> <53C41372.7080802@wxs.nl> Reply-To: mailing list for ConTeXt users NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="windows-1252"; Format="flowed" Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1405454935 24264 80.91.229.3 (15 Jul 2014 20:08:55 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 15 Jul 2014 20:08:55 +0000 (UTC) To: ntg-context@ntg.nl Original-X-From: ntg-context-bounces@ntg.nl Tue Jul 15 22:08:49 2014 Return-path: Envelope-to: gctc-ntg-context-518@m.gmane.org Original-Received: from balder.ntg.nl ([5.39.185.229]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1X791t-0006V6-An for gctc-ntg-context-518@m.gmane.org; Tue, 15 Jul 2014 22:08:49 +0200 Original-Received: from localhost (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id CC9DF102B3 for ; Tue, 15 Jul 2014 22:08:48 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at balder.ntg.nl Original-Received: from balder.ntg.nl ([127.0.0.1]) by localhost (balder.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with LMTP id YYJBIkXMWBqF for ; Tue, 15 Jul 2014 22:08:48 +0200 (CEST) Original-Received: from balder.ntg.nl (localhost [IPv6:::1]) by balder.ntg.nl (Postfix) with ESMTP id 5E6BE10222 for ; Tue, 15 Jul 2014 22:08:40 +0200 (CEST) Original-Received: from localhost (localhost [127.0.0.1]) by balder.ntg.nl (Postfix) with ESMTP id 3E4A2101E3 for ; Tue, 15 Jul 2014 22:08:37 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at balder.ntg.nl Original-Received: from balder.ntg.nl ([127.0.0.1]) by localhost (balder.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with LMTP id DEU2IRJfLR1p for ; Tue, 15 Jul 2014 22:08:31 +0200 (CEST) Original-Received: from filter4-til.mf.surf.net (filter4-til.mf.surf.net [194.171.167.220]) by balder.ntg.nl (Postfix) with ESMTP id 6B032101E2 for ; Tue, 15 Jul 2014 22:08:23 +0200 (CEST) Original-Received: from smtp.ziggozakelijk.nl (D57D1DA2.static.ziggozakelijk.nl [213.125.29.162]) by filter4-til.mf.surf.net (8.14.3/8.14.3/Debian-9.4) with ESMTP id s6FK8MhH018638 for ; Tue, 15 Jul 2014 22:08:22 +0200 X-Default-Received-SPF: pass (skip=loggedin (res=PASS)) x-ip-name=10.100.1.103; Original-Received: from [10.100.1.103] (unverified [10.100.1.103]) by pragma-net.nl (SurgeMail 6.5a2) with ESMTP id 132-1713362 for ; Tue, 15 Jul 2014 22:08:21 +0200 User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.6.0 In-Reply-To: X-Authenticated-User: hagen@controller-9 X-Bayes-Prob: 0.0001 (Score 0, tokens from: ntg-context@ntg.nl, base:default, @@RPTN) X-CanIt-Geo: ip=213.125.29.162; country=NL; region=Provincie Overijssel; city=Zwolle; latitude=52.5058; longitude=6.0858; http://maps.google.com/maps?q=52.5058,6.0858&z=6 X-CanItPRO-Stream: uu:ntg-context@ntg.nl (inherits from uu:default, base:default) X-Canit-Stats-ID: 0VMqI8mcT - d7bfe258019d - 20140715 (trained as not-spam) X-Scanned-By: CanIt (www . roaringpenguin . com) on 194.171.167.220 X-BeenThere: ntg-context@ntg.nl X-Mailman-Version: 2.1.14 Precedence: list List-Id: mailing list for ConTeXt users List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: ntg-context-bounces@ntg.nl Original-Sender: ntg-context-bounces@ntg.nl Xref: news.gmane.org gmane.comp.tex.context:88111 Archived-At: On 7/15/2014 5:33 PM, Yuri Teixeira wrote: > As I wrote in another thread, the state of the docs worries me too. I > take it that the suggestion to study the source was not serious, and > perhaps it is indeed a matter of priorities. As a new user I have a > strong opinion that the documentation should be a higher priority than > it seems to be. All the arguments about how many person-hours it would > take and the huge task it is, in my eyes, only furthers the point that > it is not considered as important as doing "real development". I Well, without development (like luatex and mp and fonts and so) it would = be a dead end anyway. Also, without some of the new things I could not = use context myself in projects (and thereby put time in it). > consider the docs a core part of the project, and the code another part, > hence the disagreement in regards to the priorities. Pro-bono or not is > not an issue, since time is spent on the project in some form. Writing > features that few people know about and are able to use is only half of > the dev work. Most mechanism that are new or renewed also come with pretty recent = manuals (like xtables and new bibliography support); older code is = mostly compatible with what old manuals describe (ok we could just bump = the date to 2014 but why). For me that's the most I can so ... write in = sync with development. (I simply run out of time otherwise.) > But I get it that documenting is a pain, and seemingly frivolous work. > The separate manuals may have been good, but they look fragmented and > there is no unified docs to go to when in doubt. And having one place to > go is even easier to maintain than many. The wiki is a nice idea, but it > needs much more rigour to function as real docs. hm, I spend quite some time on writing code but also on documentations; = did you read the xtable, xml, cld, fonts, metafun, etc manuals as well = as mk, hybrid, allkind? It's up to others to translate that into = something better. There are articles published (ok, in that case it = helps to be a member if a user group, which helps keeping tex alive = anyway). There are also examples in the test suite that can probably be turned = into docu. > Some suggestions. I'm assuming some form of wiki-like website that can > be the contextgarden or (preferably) another official > docs/wiki/wiki-like site. everyone can write documentation (and it also happens) ... we have the = wiki etc to publish them .. and everyone can conrtibute to make the wiki = better (and provide pointers to documentation) > All the content of the manuals should be unified in this site. > If a crowdsourcing/users-can-do-it approach is taken, a clear structure > needs to be previously laid out, so that we know what blanks to fill. > And even with collaboration/feedback, core people should do it. > It is important that reviewing and check marking the new edits be done > by some authoritative group, so that the community knows what to trust, > what should work as documented so that we can report real issues. > It is important to label the information as reviwed and up to date, and > to which version it applies, mkii/mkiv > If this structure is put on top of the context garden, some labeling is > needed to distinguish the extra pages from the structural docs pages. the problem there is that it needs some users who dedicate time and so = that for many years in order to keep consistency (btw, there are some = real good sections on the wiki already) > There are many good examples out there of good docs structure and > presentation. I'm willing to collaborate what I can with my limited > knowledge and time, even if little while writing my master's thesis. In that case, coordinate with Sietse. One of the things we want to (be) = do(ne) is a split between mkii and mkiv on the wiki. > Sorry to annoy with this again, No problem, as you also offer to help, > YT > > 2014-07-15 11:55 GMT-03:00 luigi scarso >: > > > > > On Tue, Jul 15, 2014 at 11:59 AM, Gerben Wierda > > wrote: > > On 14 Jul 2014, at 19:29, Hans Hagen > wrote: > >> quite some sub-systems are described in their own manuals >> (fonts, tables, xml, ...) and these manuals are quite up to >> date (and easier to maintain than one big fat manual >> >> also, additional documentation is something that users need to >> participate in (just pick a topic) >> >> even if it has high priority, that doesn't mean that those >> involved have much free time left to do that next to their >> regular work (as usual most development is done in spare time) >> >> so, patience is needed, > > I like ConTeXt (still do, I liked its approach when I first > encountered it). But the project is more the ongoing private > tinkering of a small in-crowd (that communicates with some > followers). > > ConTeXt is managed a bit like a small group of researchers > sharing a couple of complex and undocumented models/programs and > tinkering with them as they go along. It=92s an activity without > formal design, but with a lot of trial-and-error/testing. > > Given that status (and the fact that it has had that status for > over a /decennium/), I don=92t expect it to ever become a serious > product that is (semi-)professionally managed. I prefer content > over management every day, but something like this needs some > minimal management. That requires both time (=3Dmoney) and > capabilities. Besides, the tinkering researchers may not be > inclined to do that, they want to tinker. > > BTW, you can=92t be serious asking the /users/ to provide the > documentation, can you? > > > These are still good > > Fonts in ConTeXt > Layouts in ConTeXt > MetaFun manual > MKII - MKIV, the history of LuaTeX > > http://www.h2o-books.com/catalog/5 > > -- > luigi > > _____________________________________________________________________= ______________ > If your question is of interest to others as well, please add an > entry to the Wiki! > > maillist : ntg-context@ntg.nl / > http://www.ntg.nl/mailman/listinfo/ntg-context > webpage : http://www.pragma-ade.nl / http://tex.aanhet.net > archive : http://foundry.supelec.fr/projects/contextrev/ > wiki : http://contextgarden.net > _____________________________________________________________________= ______________ > > > > > _________________________________________________________________________= __________ > 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-co= ntext > webpage : http://www.pragma-ade.nl / http://tex.aanhet.net > archive : http://foundry.supelec.fr/projects/contextrev/ > wiki : http://contextgarden.net > _________________________________________________________________________= __________ > -- = ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | voip: 087 875 68 74 | www.pragma-ade.com | www.pragma-pod.nl ----------------------------------------------------------------- ___________________________________________________________________________= ________ If your question is of interest to others as well, please add an entry to t= he Wiki! maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-cont= ext webpage : http://www.pragma-ade.nl / http://tex.aanhet.net archive : http://foundry.supelec.fr/projects/contextrev/ wiki : http://contextgarden.net ___________________________________________________________________________= ________