From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.comp.tex.context/96390 Path: news.gmane.org!.POSTED!not-for-mail From: Wolfgang Schuster Newsgroups: gmane.comp.tex.context Subject: Re: Ideas for improving documentation of ConTeXt Date: Sun, 09 Oct 2016 22:51:10 +0200 Message-ID: <57FAADBE.3050703@gmail.com> References: Reply-To: mailing list for ConTeXt users NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============2910336281879010323==" X-Trace: blaine.gmane.org 1476046326 28712 195.159.176.226 (9 Oct 2016 20:52:06 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 9 Oct 2016 20:52:06 +0000 (UTC) User-Agent: Postbox 5.0.4 (Macintosh/20161007) To: mailing list for ConTeXt users Original-X-From: ntg-context-bounces@ntg.nl Sun Oct 09 22:52:01 2016 Return-path: Envelope-to: gctc-ntg-context-518@m.gmane.org Original-Received: from zapf.boekplan.nl ([5.39.185.232] helo=zapf.ntg.nl) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1btL4V-000589-6K for gctc-ntg-context-518@m.gmane.org; Sun, 09 Oct 2016 22:51:47 +0200 Original-Received: from localhost (localhost [127.0.0.1]) by zapf.ntg.nl (Postfix) with ESMTP id D10151A97F; Sun, 9 Oct 2016 22:51:30 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at zapf.boekplan.nl Original-Received: from zapf.ntg.nl ([127.0.0.1]) by localhost (zapf.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Iyaldd-5DZRH; Sun, 9 Oct 2016 22:51:29 +0200 (CEST) Original-Received: from zapf.ntg.nl (localhost [IPv6:::1]) by zapf.ntg.nl (Postfix) with ESMTP id DE3EF1A98A; Sun, 9 Oct 2016 22:51:29 +0200 (CEST) Original-Received: from localhost (localhost [127.0.0.1]) by zapf.ntg.nl (Postfix) with ESMTP id E27631A971 for ; Sun, 9 Oct 2016 22:51:27 +0200 (CEST) X-Virus-Scanned: Debian amavisd-new at zapf.boekplan.nl Original-Received: from zapf.ntg.nl ([127.0.0.1]) by localhost (zapf.ntg.nl [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id v8lBFqajBVoA for ; Sun, 9 Oct 2016 22:51:25 +0200 (CEST) Original-Received: from mail-lf0-f52.google.com (mail-lf0-f52.google.com [209.85.215.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by zapf.ntg.nl (Postfix) with ESMTPS id 30B491A96C for ; Sun, 9 Oct 2016 22:51:15 +0200 (CEST) Original-Received: by mail-lf0-f52.google.com with SMTP id b81so90918568lfe.1 for ; Sun, 09 Oct 2016 13:51:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=message-id:date:from:user-agent:mime-version:to:subject:references :in-reply-to; bh=pANTr1sjNZTF20yEC08ihdaNbTCvf6N5MubR8FqWelk=; b=pHkVzU0LNGxm0nbfFbRADma/jwUgWpU1IJ64F1RAruF0D3vNc/6reXbBxrQ2v0gYS/ iksRSyVcAjPJKckggjETytjwCFi/2HPNXDhh+kHWISO7lqYxwVKzXA5L7QRItRHis9cc KKzLWNFMQkFUTEjXieSYFb/ud605JipVYxAa6xZpOlWDyaTgjfv1qv1Tlgf1ntfWHBes mn0V7L8ivMWm3/MM0LIKFjzNxWgYy3Izpb55GWZg/jfYwz3JuHR8YJdBqybDg+frNxOu nLmScurJApIdGaPFU4HKPApF13T9jN5DKCnL8Feci6Qj2bmHaQWNlLK68ozw7zYVoe0b G1uw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:message-id:date:from:user-agent:mime-version:to :subject:references:in-reply-to; bh=pANTr1sjNZTF20yEC08ihdaNbTCvf6N5MubR8FqWelk=; b=aOnfzkk0gRXJOGf6OEP8+EajTlceR4/yNc1QPTXDXAoHmjInrSOH3lPMpq+XytokIq nClU+CBYpvUnUFFhJAovojizlXa14DRDu/2LUFKE9bar+iL/EoYzqUW338DDvHZpg1S/ F0bVe09uI9N3VLY8UY/yFuWXTQbeRahH8aW8tBWkhDkxA/y25/GkI8CakWamWYFEk8Pa 6FbzhpzDvsMC4aSxBrKD3Oj4Pe98lYTS1svUDRyP9TZMAyXn1suXDSbYyU2bVvqFBtWy lbtrj3c5ovvA+2YjeZKxCs6C/+8o0pC+01hAp5cxj8Ud3UUz4xdFRZyTtHrQxJ9X64Ok 8nbA== X-Gm-Message-State: AA6/9Rnpn8we0JqVpWg36BqGjuDk+n9qS7K3vyzoe1LPmsEJ9+cbCNpfDS0q53pwJpixtA== X-Received: by 10.194.248.226 with SMTP id yp2mr24946684wjc.117.1476046274035; Sun, 09 Oct 2016 13:51:14 -0700 (PDT) Original-Received: from keima.localdomain (x2f28044.dyn.telefonica.de. [2.242.128.68]) by smtp.gmail.com with ESMTPSA id qq7sm1671683wjc.30.2016.10.09.13.51.12 for (version=TLS1 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Sun, 09 Oct 2016 13:51:13 -0700 (PDT) In-Reply-To: X-BeenThere: ntg-context@ntg.nl X-Mailman-Version: 2.1.16 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" Xref: news.gmane.org gmane.comp.tex.context:96390 Archived-At: This is a multi-part message in MIME format. --===============2910336281879010323== Content-Type: multipart/alternative; boundary="------------020104060704060903090405" This is a multi-part message in MIME format. --------------020104060704060903090405 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit > Jonas Baggett > 9. Oktober 2016 um 13:18 > Hello everyone, > > I am new to new to ConTeXt and I was thinking about how to improve > documentation to help users and then make ConTeXt more appealing. > Because, if there is one weak point in my eyes with ConTeXt, it is the > lack of documentation, which is too bad because ConTeXt seems to be > really great. And google search is also a little tricky, since context > is a common name. On the other hand, most of the help I found was on > the wiki, the mailing list, TeX Stack Exchange and some pdf > documentations. Sometimes, I also faced the problem about the > documentation being outdated and when I am trying to find the solution > on the internet, I may have a hard time finding solutions that aren't > outdated too. The worse is maybe when a command option isn't working > anymore with not even a warning. Many of the old manuals got updates by Hans and he included the PDF’s (together with the source files) in the normal ConTeXt download, you can find them in the doc folder in your ConTeXt installation. > The basic idea I have is a database of ConTeXt documents, where > everyone can add his own documents. We have also to make it easy to > find there insightful examples in ConTeXt that will help someone to > achieve what he is trying to do. Then users, especially beginners, > will less likely be stuck at one point and looking for hours for a > solution and less help will be asked on the mailing list too. The wiki has a page for examples and you’re free to update the existing examples or add new ones. > Here are the basic concepts about the database : > - When someone adds a document, he can specify the type of the > document like e.g. report, letter, CV, book, etc. Subcategories could > be a good idea too, e.g. letters can have a subcategory called cover > letters. Some extra tags could also be useful, like e.g.: math, > luatex, tables, positioning, etc when there is some use of the > preceding, maybe not necessarily essential when the use is only basic. > - If some extra fonts or modules are needed to be installed in order > to make the example fully work, this could also be specified. > - Search could be done by specifying one or more categories and tags. > It will also be possible to search all the occurrences in the database > of a command with optionally a command parameter. > - It will be like a wiki so that everyone could improve the existing > examples. > - It can be also useful to allow comments, because it is possible that > an example is close to what someone is trying to do, in which case he > will look on the comments hoping that there was already someone who > asked there the question and got answered. > - In order to mitigate the problem with deprecation stuffs after some > language changes, we could have all the commands and their options > listed somewhere in the database, then when a command or command > parameter is getting deprecated, it will be possible to mark it as so > and provide some hints on how to fix it. After that, all the examples > that use the deprecated stuffs will get a warning and hints will be > showed about how to fix them. And since that examples are editable by > anyone, there won't be hopefully very much of outdated documents. > > Here some are possible scenarios about searching in the database : > - Someone is writing a letter and is trying to move one element (e.g. > date, his address, receiver address) in another location without any > success so far. Then he will go to this database, choose letter as > category and positioning as extra tag and launch the search. Maybe he > will get about 20 results, then chances are that some of the found > examples will be doing something close enough to what he's trying to > do, so that he could analyse the source and understand what he needs > to do in his case. > - Someone is looking about how to set the background color of a framed > box. Then he will search occurrences of the uses of the \framed > command which have color in their arguments. Then by looking at the > found examples, he will find out that the color is set with the > backgroundcolor argument and that the background argument need to be > set to "color" too. > > What do you think about the idea ? I believe this could be a good > complement to the existing ressources. Sounds interesting and the best thing you can do is to start with it. Wolfgang --------------020104060704060903090405 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 8bit
9. Oktober 2016 um 13:18
Hello everyone,

I am new to new to ConTeXt and I was thinking about how to improve documentation to help users and then make ConTeXt more appealing. Because, if there is one weak point in my eyes with ConTeXt, it is the lack of documentation, which is too bad because ConTeXt seems to be really great. And google search is also a little tricky, since context is a common name. On the other hand, most of the help I found was on the wiki, the mailing list, TeX Stack Exchange and some pdf documentations. Sometimes, I also faced the problem about the documentation being outdated and when I am trying to find the solution on the internet, I may have a hard time finding solutions that aren't outdated too. The worse is maybe when a command option isn't working anymore with not even a warning.
Many of the old manuals got updates by Hans and he included the PDF’s (together with the source files) in the normal ConTeXt download, you can find them in the doc folder in your ConTeXt installation.
The basic idea I have is a database of ConTeXt documents, where everyone can add his own documents. We have also to make it easy to find there insightful examples in ConTeXt that will help someone to achieve what he is trying to do. Then users, especially beginners, will less likely be stuck at one point and looking for hours for a solution and less help will be asked on the mailing list too.
The wiki has a page for examples and you’re free to update the existing examples or add new ones.
Here are the basic concepts about the database :
- When someone adds a document, he can specify the type of the document like e.g. report, letter, CV, book, etc. Subcategories could be a good idea too, e.g. letters can have a subcategory called cover letters. Some extra tags could also be useful, like e.g.: math, luatex, tables, positioning, etc when there is some use of the preceding, maybe not necessarily essential when the use is only basic.
- If some extra fonts or modules are needed to be installed in order to make the example fully work, this could also be specified.
- Search could be done by specifying one or more categories and tags. It will also be possible to search all the occurrences in the database of a command with optionally a command parameter.
- It will be like a wiki so that everyone could improve the existing examples.
- It can be also useful to allow comments, because it is possible that an example is close to what someone is trying to do, in which case he will look on the comments hoping that there was already someone who asked there the question and got answered.
- In order to mitigate the problem with deprecation stuffs after some language changes, we could have all the commands and their options listed somewhere in the database, then when a command or command parameter is getting deprecated, it will be possible to mark it as so and provide some hints on how to fix it. After that, all the examples that use the deprecated stuffs will get a warning and hints will be showed about how to fix them. And since that examples are editable by anyone, there won't be hopefully very much of outdated documents.

Here some are possible scenarios about searching in the database  :
- Someone is writing a letter and is trying to move one element (e.g. date, his address, receiver address) in another location without any success so far. Then he will go to this database, choose letter as category and positioning as extra tag and launch the search. Maybe he will get about 20 results, then chances are that some of the found examples will be doing something close enough to what he's trying to do, so that he could analyse the source and understand what he needs to do in his case.
- Someone is looking about how to set the background color of a framed box. Then he will search occurrences of the uses of the \framed command which have color in their arguments. Then by looking at the found examples, he will find out that the color is set with the backgroundcolor argument and that the background argument need to be set to "color" too.

What do you think about the idea ? I believe this could be a good complement to the existing ressources.
Sounds interesting and the best thing you can do is to start with it.

Wolfgang
--------------020104060704060903090405-- --===============2910336281879010323== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX18KSWYgeW91ciBxdWVzdGlvbiBpcyBvZiBpbnRlcmVz dCB0byBvdGhlcnMgYXMgd2VsbCwgcGxlYXNlIGFkZCBhbiBlbnRyeSB0byB0aGUgV2lraSEKCm1h aWxsaXN0IDogbnRnLWNvbnRleHRAbnRnLm5sIC8gaHR0cDovL3d3dy5udGcubmwvbWFpbG1hbi9s aXN0aW5mby9udGctY29udGV4dAp3ZWJwYWdlICA6IGh0dHA6Ly93d3cucHJhZ21hLWFkZS5ubCAv IGh0dHA6Ly90ZXguYWFuaGV0Lm5ldAphcmNoaXZlICA6IGh0dHA6Ly9mb3VuZHJ5LnN1cGVsZWMu ZnIvcHJvamVjdHMvY29udGV4dHJldi8Kd2lraSAgICAgOiBodHRwOi8vY29udGV4dGdhcmRlbi5u ZXQKX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX18= --===============2910336281879010323==--