Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-13 Thread Aditya Mahajan 

On Thu, 13 Oct 2016, Henning Hraban Ramm wrote:


Am 2016-10-12 um 23:27 schrieb Jonas Baggett :


There are ConTeXt threads on tex.stackexchange.com

You are confusing Stack Overflow and Stack Exchange ;-). Actually I didn't find 
the ConTeXt tag there : http://stackoverflow.com/tags.


No, I’m not confusing them. They’re the same company, share accounts, 
reputation etc. All TeX related questions belong on 
tex.stackexchange.com, not on stackoverflow, so there *shouldn’t* exist 
any tex, latex, context, luatex etc. tags on stackoverflow. But look 
here: http://tex.stackexchange.com/tags


But the stackexchange documentation feature only works for languages that 
have tags on stackoverflow, not on stackexchange.


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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-13 Thread Henning Hraban Ramm 
Am 2016-10-12 um 23:27 schrieb Jonas Baggett :

>> There are ConTeXt threads on tex.stackexchange.com
> You are confusing Stack Overflow and Stack Exchange ;-). Actually I didn't 
> find the ConTeXt tag there : http://stackoverflow.com/tags.

No, I’m not confusing them. They’re the same company, share accounts, 
reputation etc.
All TeX related questions belong on tex.stackexchange.com, not on 
stackoverflow, so there *shouldn’t* exist any tex, latex, context, luatex etc. 
tags on stackoverflow.
But look here: http://tex.stackexchange.com/tags

>> Hm, in my experience you get the necessary basic permissions really soon.
> Ok, I can't remember exactly, but it was possible that I wanted to answer a 
> question in a comment below someone post, which require a reputation of 50.

Of course, there are hurdles. I can understand they might be too high to start, 
but their quality assurance mostly works well.

It’s getting OT here, let’s stop.

Greetlings, Hraban
---
http://www.fiee.net
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)
GPG Key ID 1C9B22FD

___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Jonas Baggett 

Le 11.10.16 à 22:40, Henning Hraban Ramm a écrit :


Am 2016-10-11 um 22:26 schrieb Jonas Baggett :


http://meta.stackoverflow.com/questions/328667/new-tags-and-documentation-beta

And a ConTeXt tag must already exist on Stack Overflow, which I didn't find. So 
it seems we can wait a while before there would be examples in ConTeXt.

There are ConTeXt threads on tex.stackexchange.com


You are confusing Stack Overflow and Stack Exchange ;-). Actually I 
didn't find the ConTeXt tag there : http://stackoverflow.com/tags.

I find stackoverflow too elitist, once I was reading a question and I wanted to 
help with an answer but it wasn't possible to do because it was the first time 
I wanted to contribute in stackoverflow and of course I was lacking the needed 
reputation. I am interested to help when I see an occasion to and when I am in 
the mood for that ;-). So I found that frustrating and it didn't make me 
interested to contribute there.

On the other hand, I understand their will to have good quality questions and 
answer and I appreciate that. I am just feeling it must be a better way to do 
that.

Hm, in my experience you get the necessary basic permissions really soon.


Ok, I can't remember exactly, but it was possible that I wanted to 
answer a question in a comment below someone post, which require a 
reputation of 50.

___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Jonas Baggett 

Hello Jean-Pierre,

Le 10.10.16 à 19:04, Jean-Pierre Delange a écrit :


A simple question : is it usefull to get a very quick access to a documentation 
where explanation is absent ? That's why the current explanation is very useful 
: even if you have to read full pages at length, the explanation given in the 
PDF documentation is an accurate information and oftenly says something which 
allow to lead to a solve your issue. So, it seems there is a conflict between 
the desire of a quick access to relevant information and the need of learning 
ConTeXt with patience !


Actually we can have the advantage of both. When someone is accessing an 
example that has e.g. the tags "table" and "luatex", then links to the 
pdf and wiki documentation about tables and luatex could be shown aside. 
And thanks for pointing that ! I would not have think about that otherwise.


And your wiki is something I should definitively have a look at. Thanks 
for the work !


Cheers,
Jonas
___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Bomber K. 
Changing the name won't give you any benefit over information that is 
written online somewhere already. Because then everybody would have to 
refresh their post and documents and so on.


The best solution is to be as specific as you can be, like ppl before me 
posted already. Type, frame document, tex and any keywords you would 
expect to read about the ConTeXt.


Because from the origin point of view, the name ConTeXt is great. In 
Netherlands you spell it like Contecht. It's a great pun / wordplay and 
should remain. :D



Am 12.10.2016 um 17:29 schrieb Yi Qingliang:

can we change name other than context? it is too difficult to search
it on google :(


___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Bomber K. 
Not for somebody who is new to the game. I was a newbie before and i 
know that the very least you are looking for is mkiv. ;)



Am 12.10.2016 um 19:32 schrieb Jonas Baggett:


Or "mkiv" is also a usefull keyword for search



___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Jonas Baggett 

Or "mkiv" is also a usefull keyword for search.


Le 12.10.16 à 17:33, Mica Semrick a écrit :
I often find adding 'TeX' to my search query to be helpful. Something 
like 'ConTeXt TeX margin error'


-m

On October 12, 2016 8:29:45 AM PDT, Yi Qingliang 
 wrote:


can we change name other than context? it is too difficult to search
it on google :(

On Wed, Oct 12, 2016 at 7:30 PM, Jonas Baggett  wrote:

Le 10. 10. 16 à 09:24, Hans Hagen a écrit : This will only
work when someone takes the lead. If you do that you then
others will help you. If you need something special on the
wiki, just discuss it with Taco and Mojca who deal with the
technicalities. Yes that would be great to have a page on the
wiki. Then I could describe there the goals of the project and
elaborate and put there the specifications of the project.
Then waiting for some feed-back in order to improve the ideas
behind the project. When the specifications are mature enough,
the technological choices could be made and finally I will be
able to put there a roadmap. At which point it would be easier
to know what needs to be done and how much time investment
will be needed, and what are the tasks I can reasonably do for
the project and what are those where help is welcome.
Hopefully there would be other people at that point who could
share the vision and are willing to help. How do you think
about that ? Have a nice afternoon, Jonas

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://context.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://context.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://context.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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Mica Semrick 
I often find adding 'TeX' to my search query to be helpful. Something like 
'ConTeXt TeX margin error'

-m

On October 12, 2016 8:29:45 AM PDT, Yi Qingliang  
wrote:
>can we change name other than context? it is too difficult to search
>it on google :(
>
>On Wed, Oct 12, 2016 at 7:30 PM, Jonas Baggett 
>wrote:
>> Le 10. 10. 16 à 09:24, Hans Hagen a écrit :
>>
>> This will only work when someone takes the lead. If you do that you
>then
>> others will help you. If you need something special on the wiki, just
>> discuss it with Taco and Mojca who deal with the technicalities.
>>
>>
>> Yes that would be great to have a page on the wiki. Then I could
>describe
>> there the goals of the project and elaborate and put there the
>> specifications of the project. Then waiting for some feed-back in
>order to
>> improve the ideas behind the project. When the specifications are
>mature
>> enough, the technological choices could be made and finally I will be
>able
>> to put there a roadmap. At which point it would be easier to know
>what needs
>> to be done and how much time investment will be needed, and what are
>the
>> tasks I can reasonably do for the project and what are those where
>help is
>> welcome. Hopefully there would be other people at that point who
>could share
>> the vision and are willing to help. How do you think about that ?
>>
>> Have a nice afternoon,
>> Jonas
>>
>>
>___
>> 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://context.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://context.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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Yi Qingliang 
can we change name other than context? it is too difficult to search
it on google :(

On Wed, Oct 12, 2016 at 7:30 PM, Jonas Baggett  wrote:
> Le 10. 10. 16 à 09:24, Hans Hagen a écrit :
>
> This will only work when someone takes the lead. If you do that you then
> others will help you. If you need something special on the wiki, just
> discuss it with Taco and Mojca who deal with the technicalities.
>
>
> Yes that would be great to have a page on the wiki. Then I could describe
> there the goals of the project and elaborate and put there the
> specifications of the project. Then waiting for some feed-back in order to
> improve the ideas behind the project. When the specifications are mature
> enough, the technological choices could be made and finally I will be able
> to put there a roadmap. At which point it would be easier to know what needs
> to be done and how much time investment will be needed, and what are the
> tasks I can reasonably do for the project and what are those where help is
> welcome. Hopefully there would be other people at that point who could share
> the vision and are willing to help. How do you think about that ?
>
> Have a nice afternoon,
> Jonas
>
> ___
> 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://context.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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Jonas Baggett 

Le 10. 10. 16 à 09:24, Hans Hagen a écrit :

This will only work when someone takes the lead. If you do that you 
then others will help you. If you need something special on the wiki, 
just discuss it with Taco and Mojca who deal with the technicalities. 


Yes that would be great to have a page on the wiki. Then I could 
describe there the goals of the project and elaborate and put there the 
specifications of the project. Then waiting for some feed-back in order 
to improve the ideas behind the project. When the specifications are 
mature enough, the technological choices could be made and finally I 
will be able to put there a roadmap. At which point it would be easier 
to know what needs to be done and how much time investment will be 
needed, and what are the tasks I can reasonably do for the project and 
what are those where help is welcome. Hopefully there would be other 
people at that point who could share the vision and are willing to help. 
How do you think about that ?


Have a nice afternoon,
Jonas
___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-12 Thread Jonas Baggett 

Le 10. 10. 16 à 09:57, Thomas A. Schmitz a écrit :


On 10/10/2016 07:43 AM, Jonas Baggett wrote:


Thanks for your encouragement ! Yes that looks like an interesting
challenge for me, but it is not something I am wanting to do alone
because of my lack of experience, at least I would need someone to coach
me. Actually I don't have really experience with web developpment and I
would at least need help for the technological choices. Having someone
that tells me that if I use technology X, there are module Y and Z that
will be a good fit is a good start.


Just two small remarks:

1. there are not that many modules in ConTeXt because most of the 
functionality is in the core. If you come from the LaTeX world, you 
may expect several hundred packages, each with their own 
idiosyncracies and documentation. That's not the case here.


I wasn't thinking about ConTeXt modules here but choosing the right web 
framework that has the right modules.


2. As for your documentation project, let me be honest: unless someone 
very dedicated and very knowledgeable makes a long-term commitment and 
looks after these examples, they are worse than useless. Unless there 
is very tight control, they may contain bad and/or outdated code and 
lead newcomers in the wrong direction


Ok, thanks for pointing a possible problem with code quality. Yes it is 
something we have to think about and find a solution that will ensure 
good code quality among the examples. Here would be my vision for the 
project in 3 points :
1. It's about learning ConTeXt by examples, not only learning how to 
make the code work as expected, but to make it work the correct way.
2. Encourage a collaborative spirit so that the community is willing to 
help anyone to reach point 1 (by posting examples and making suggestion 
or improving existing examples).

3. See below
If this vision could be enough advertised to those who want to 
contribute with their examples, I believe a lot less control would be 
need, as the community will do the control itself.


Concerning outdated code, as I understood, the ConTeXt core interface is 
stable so if we add a tag for the ConTeXt Mark (II, IV, VI) that would 
do it. But for examples using modules, yes that's right, interfaces 
could change and make the existing examples outdated. So I believe that 
having in the database a description of the modules interface, will 
mitigates the problem. And when a command in a module becomes 
deprecated, then the description of the module interface needs to be 
updated and a hint could be added to fix outdated code, like : "command> is deprecated, replace it by ". Then warnings will 
be added automatically on examples using outdated code with useful hints 
to fix it.


The context way has always been to avoid boilerplate templates and let 
users roll their own styles. Which makes sense since in context almost 
every detail can be changed easily via dedicated setup commands. (This 
is again quite unlike LaTeX and its document classes that predefine 
many details.) I have problems imagining a collection of sample 
documents that will be more than a haphazard bunch of fortuitous designs.


So if I understand well the philosophy difference between LaTeX and 
ConTeXt, the LaTeX philosophy would be about using document classes and 
avoid making much tweaks but be more focused on the content. With 
ConTeXt on the other hand, the philosophy is more about being able to 
customize everything.


Actually there could be 2 categories of ConTeXt documents on the database :
1. Those that are more aimed toward making others learn ConTeXt, like 
tutorials

2. Those who are templates.

It's very likely that the 2nd category will be more present, as I 
imagine that a typical contribution would be someone who spend some time 
with a document he has made in ConTeXt and is happy with the result and 
want to post it on the database in order to allow others to benefit from 
his work.


Indeed, the third point of my vision would be to make a big collection 
of templates available, but my goal isn't to go against the ConTeXt 
philosophy. The idea would be more like if someone has a particular 
need, he could find a suitable template in the database, take it, 
analyze it, tweak it and learn more about ConTeXt in the process. 
Templates would be also a good advertisement for ConTeXt : before 
someone could be interested in ConTeXt he has to believe that ConTeXt 
could fit his needs and that it hopefully isn't a pain to use. If he 
could find a suitable template, he would be in a very short time 
convinced that ConTeXt can do what he needs to and that it is nice to 
use thanks to its clean well-though synthax. Then he will probably 
become a new ConTeXt user.


I believe that having precise tags and allow to sort by popularity will 
help to structure the database so that it doesn't become haphazard and 
also the higher quality works will have more visibility.


Before starting any project it is good to analyze wha

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-11 Thread Jonas Baggett 

Le 10. 10. 16 à 09:35, Hans Hagen a écrit :

Don't worry, no one feels offended. FYI, Pragma is not that large a 
company so we cannot allocate more resources than we do now (and did 
the last couple of decades). We just provide the manuals we write in 
the process and happily leave the rest to others.

(...)
Not all old manuals will be updates. There are already a lot in the 
distribution and another 6 on my disk waiting for an mkiv update. 
These are often covering a specific aspect. I happily leave writing 
additional manuals to others.


Good approach, I believe. It is always better to have a community that 
participate to the work instead of doing all the work.
Each year at the context meeting this topic pops op and there are many 
plans but a lack of time interferes.


Btw, Alan is writing a larger story for beginners.


Having a good tutorial for beginners will be a good advertisement for 
ConTeXt, I guess.
The interface is actually rather stable otherwise we could not use it 
ourselves. However the move to luatex made it possible to kick out 
code related to input and font encoding as well as update to new 
technologies so there have been changes. So, the trick is to point new 
users to the right examples and documentation.


The letter generator was located there in my system : 
/usr/share/texmf/doc/context/base/examplap/gui/letter.pdf. You have 
written previously that the examplap code and examples where mkii. In 
this case, if this would be located there 
/usr/share/texmf/doc/context/base/mkii/examplap/gui/letter.pdf instead, 
in a mkii folder, I would have known at first glance that it is outdated 
documentation. So a quick first improvement could be to put mkii related 
documentation in a mkii folder.


Cheers,
Jonas
___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-11 Thread Jonas Baggett 

Le 10. 10. 16 à 09:24, Hans Hagen a écrit :
What context installation do you use? The reference is the one on the 
context garden. Each year tex lives has a snapshot of that one. So, 
first make sure you run the latest version.


I am using version 2016.05.17 19:20. I saw that context live is using 
version 2016.05.19 13:43, so I have fast the latest version.


Concerning old manuals: they often refer to mkii but with mkiv we have 
different (often better) solutions. The examplap code and examples are 
mkii and also relate to pdf trickery and as pdf evolved it became more 
clear what was bound to acrobat i.e. not picked up (ignored) by open 
source alternatives and therefore less relevant.


Ok, I didn't know that about the pdf format. Thanks for the information.

An important source are the setup-*.pdf files as these describe the 
interface which is described in the interface definition files (in xml 
format). These have recently be updated by Wolfgang and are very accurate.


Yes, that was one of the thinks I was looking for, thanks !

You mentioned that keys (functionality) that disappears should be 
somehow documented but normally no functionality disappears. What 
happened was that mkiv has some more (because it's possible) and less 
(because it was no longer needed) than mkii and has been made more 
consistent.


I was more thinking about commands or commands option becoming 
deprecated and replaced by another way of making thinks. But it is also 
true that I tried to make the moderncv interface work from the letter 
module but its interface is now gone. I didn't notice at first that the 
letter module is still under development which means its interfaces 
aren't stable. So it seems now that what I was saying doesn't really 
apply to ConTeXt's core.



The wiki has a page for examples and you’re free to update the
existing examples or add new ones.


Do you mean http://wiki.contextgarden.net/Sample_documents ? Yes, that's
a good idea, since I believe that it is a way to improve documentation
with little efforts. Then I plan to add the cover letter style I made
since I am happy with the results, although 1 or 2 things could have
some improvement. There are also some letter styles there, then I will
have a look on them too. I don't know if people are intimidated about
writing contents in the wiki because it is the official wiki and feel
that only programmers are supposed to update it, but it will be really
helpfull if the users have more the habit of posting there the document
styles they made.


Indeed.


My cover letter template is now maturing, since it is only the beginning 
I am using it, but I believe it will be ready soon to be posted in the 
wiki :-).



Sounds interesting and the best thing you can do is to start with it.


Thanks for your encouragement ! Yes that looks like an interesting
challenge for me, but it is not something I am wanting to do alone
because of my lack of experience, at least I would need someone to coach
me. Actually I don't have really experience with web developpment and I
would at least need help for the technological choices. Having someone
that tells me that if I use technology X, there are module Y and Z that
will be a good fit is a good start.


This will only work when someone takes the lead. If you do that you 
then others will help you. If you need something special on the wiki, 
just discuss it with Taco and Mojca who deal with the technicalities.


OK, it is still an idea that needs maturation. I know I tend to be 
quickly enthusiastic about an idea and overly optimistic about my 
abilities to implement it which means that I eventually end giving up. 
So now I need some thinking about the idea, about if I am ready to 
invest the needed time. Maybe the task is to big for me but there could 
be a less time consuming solution that can be OK although not as great. 
Or I could still go for the original idea with being clear about what I 
can do and how much time I can invest to and how much help I need to 
complete what I couldn't reasonably do.


Cheers,
Jonas
___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-11 Thread Henning Hraban Ramm 
Am 2016-10-11 um 22:26 schrieb Jonas Baggett :

>> http://meta.stackoverflow.com/questions/328667/new-tags-and-documentation-beta
> 
> And a ConTeXt tag must already exist on Stack Overflow, which I didn't find. 
> So it seems we can wait a while before there would be examples in ConTeXt.

There are ConTeXt threads on tex.stackexchange.com

> I find stackoverflow too elitist, once I was reading a question and I wanted 
> to help with an answer but it wasn't possible to do because it was the first 
> time I wanted to contribute in stackoverflow and of course I was lacking the 
> needed reputation. I am interested to help when I see an occasion to and when 
> I am in the mood for that ;-). So I found that frustrating and it didn't make 
> me interested to contribute there.
> 
> On the other hand, I understand their will to have good quality questions and 
> answer and I appreciate that. I am just feeling it must be a better way to do 
> that.

Hm, in my experience you get the necessary basic permissions really soon.

Greetlings, Hraban
---
http://www.fiee.net
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)
GPG Key ID 1C9B22FD

___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-11 Thread Jonas Baggett 

Le 10.10.16 à 07:43, Aditya Mahajan a écrit :


Recently, stackexchange started a similar project:
https://blog.stackoverflow.com/2016/07/introducing-stack-overflow-documentation-beta/ 



You can create a context tag and create example documents. The 
difficulty with such projects, as usual, is to have a critical mass 
for others to browse and contribute. One could start by "porting" 
existing examples from the wiki, mailing list, tex.stackexchange, etc.


Scratch that. It seems that documentation tags can only be created for 
topics that are popular on stackoverflow (not stackexchange).


http://meta.stackoverflow.com/questions/328667/new-tags-and-documentation-beta


And a ConTeXt tag must already exist on Stack Overflow, which I didn't 
find. So it seems we can wait a while before there would be examples in 
ConTeXt.


I find stackoverflow too elitist, once I was reading a question and I 
wanted to help with an answer but it wasn't possible to do because it 
was the first time I wanted to contribute in stackoverflow and of course 
I was lacking the needed reputation. I am interested to help when I see 
an occasion to and when I am in the mood for that ;-). So I found that 
frustrating and it didn't make me interested to contribute there.


On the other hand, I understand their will to have good quality 
questions and answer and I appreciate that. I am just feeling it must be 
a better way to do that.
___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Jean-Pierre Delange 


- Mail original -
De: "Henning Hraban Ramm" 
À: "mailing list for ConTeXt users" 
Envoyé: Lundi 10 Octobre 2016 23:41:11
Objet: Re: [NTG-context] Ideas for improving documentation of ConTeXt

Am 2016-10-10 um 19:04 schrieb Jean-Pierre Delange :

> https://fr.wikibooks.org/wiki/ConTeXt 

A user named Piksi started (and immediately abandoned) an English one at
https://en.wikibooks.org/wiki/ConTeXt

I have a look at it in the beginning of 2016. Why don't feed this page with a 
few ConTeXt starter docs ?

I did the same here:
https://www.gitbook.com/book/fiee/context-starter/welcome

error 403 ...

While I _am_ planning to write a ConTeXt book in German and already created an 
extensive outline, I found gitbook to be the wrong platform. Anyway I guess it 
will just end up on my big pile of started-and-abandoned projects...

BTW Alan let me have a look at his book: it already looks good and has a lot of 
content, but has still a long way to go until we can hope to see it printed.

Some more information about this project ?

Thanks,
JP


Greetlings, Hraban
---
http://www.fiee.net
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)
GPG Key ID 1C9B22FD

___
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://context.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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Henning Hraban Ramm 
Am 2016-10-10 um 19:04 schrieb Jean-Pierre Delange :

> https://fr.wikibooks.org/wiki/ConTeXt 

A user named Piksi started (and immediately abandoned) an English one at
https://en.wikibooks.org/wiki/ConTeXt

I did the same here:
https://www.gitbook.com/book/fiee/context-starter/welcome

While I _am_ planning to write a ConTeXt book in German and already created an 
extensive outline, I found gitbook to be the wrong platform. Anyway I guess it 
will just end up on my big pile of started-and-abandoned projects...

BTW Alan let me have a look at his book: it already looks good and has a lot of 
content, but has still a long way to go until we can hope to see it printed.


Greetlings, Hraban
---
http://www.fiee.net
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)
GPG Key ID 1C9B22FD

___
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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Hans Hagen 

On 10/10/2016 7:04 PM, Jean-Pierre Delange wrote:

Dear List,

This discussion (and proposals) is very interesting and I am afraid to say that all the points of 
view are relevant. But the core idea of Jonas is to get a kind of samples database where access is 
defined by key-word as "columnset" or "frame", etc. I don't know if making this 
kind of tool is as simple as it appears to be, but why not ? Surely, the individual (or group) has 
to be very devoted. Certainly it is possible to get code containing many errors, but Jonas would be 
inspired to get a further enquiry on this matter. Surely, there is a need to access quickly to the 
relevant information, but I don't know if it is possible to clear the way much more than the 
ConTeXt Garden wiki allows to do so.

I order to learn ConTeXt for my own purpose and work, I have begun to start a Wikibook, because a few months 
ago I simply didn't know the name of ConTeXt, but I was sure that it was a best way for me to use it than 
LaTeX : my aim was not to build a very well structured database, but to get some code with samples on the 
same page (as a quick first help), chapter by chapter, from simple to complex (e. g. "simple 
frame"; "frame in a column" etc.) in order to access quickly to my documentation, and to help 
beginners like me. I feed this "database" with ConTeXt Garden samples and with test samples from 
the mailing-list, as long as I can understand them (I am not a mathematician, only someone who needs to print 
classical texts) : https://fr.wikibooks.org/wiki/ConTeXt

A simple question : is it usefull to get a very quick access to a documentation 
where explanation is absent ? That's why the current explanation is very useful 
: even if you have to read full pages at length, the explanation given in the 
PDF documentation is an accurate information and oftenly says something which 
allow to lead to a solve your issue. So, it seems there is a conflict between 
the desire of a quick access to relevant information and the need of learning 
ConTeXt with patience !


One trap that a user can fall into is to make a complete style at once. 
because much works out of the box, one can delay styling and just define 
/ setup things as the document evolves.


Another trap is to start with some existing complex style. If you look 
at the manuals you'll notice that there is not that much being set up. 
Of course there are complex setups possible and we need them for complex 
xml to pdf workflows with lots of different structural elements and 
designer demands and exceptions, but that's not that common i guess.


Your wikibook approach sounds useful. I often put examples i run into 
(or make when testing new code) in the test suite that can be downloaded 
but i wonder if many users can use that (too many files).


Some kind of "if you need this, look there" system would be nice. If you 
want keywords, the i-*.xml files are a good starting point.




- Mail original -
De: "Thomas A. Schmitz" 
À: "mailing list for ConTeXt users" 
Envoyé: Lundi 10 Octobre 2016 09:57:24
Objet: Re: [NTG-context] Ideas for improving documentation of ConTeXt

On 10/10/2016 07:43 AM, Jonas Baggett wrote:


Thanks for your encouragement ! Yes that looks like an interesting
challenge for me, but it is not something I am wanting to do alone
because of my lack of experience, at least I would need someone to coach
me. Actually I don't have really experience with web developpment and I
would at least need help for the technological choices. Having someone
that tells me that if I use technology X, there are module Y and Z that
will be a good fit is a good start.


Just two small remarks:

1. there are not that many modules in ConTeXt because most of the
functionality is in the core. If you come from the LaTeX world, you may
expect several hundred packages, each with their own idiosyncracies and
documentation. That's not the case here.

2. As for your documentation project, let me be honest: unless someone
very dedicated and very knowledgeable makes a long-term commitment and
looks after these examples, they are worse than useless. Unless there is
very tight control, they may contain bad and/or outdated code and lead
newcomers in the wrong direction. The context way has always been to
avoid boilerplate templates and let users roll their own styles. Which
makes sense since in context almost every detail can be changed easily
via dedicated setup commands. (This is again quite unlike LaTeX and its
document classes that predefine many details.) I have problems imagining
a collection of sample documents that will be more than a haphazard
bunch of fortuitous designs.

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

maillist : ntg-context@ntg

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Jean-Pierre Delange 
Dear List,

This discussion (and proposals) is very interesting and I am afraid to say that 
all the points of view are relevant. But the core idea of Jonas is to get a 
kind of samples database where access is defined by key-word as "columnset" or 
"frame", etc. I don't know if making this kind of tool is as simple as it 
appears to be, but why not ? Surely, the individual (or group) has to be very 
devoted. Certainly it is possible to get code containing many errors, but Jonas 
would be inspired to get a further enquiry on this matter. Surely, there is a 
need to access quickly to the relevant information, but I don't know if it is 
possible to clear the way much more than the ConTeXt Garden wiki allows to do 
so.

I order to learn ConTeXt for my own purpose and work, I have begun to start a 
Wikibook, because a few months ago I simply didn't know the name of ConTeXt, 
but I was sure that it was a best way for me to use it than LaTeX : my aim was 
not to build a very well structured database, but to get some code with samples 
on the same page (as a quick first help), chapter by chapter, from simple to 
complex (e. g. "simple frame"; "frame in a column" etc.) in order to access 
quickly to my documentation, and to help beginners like me. I feed this 
"database" with ConTeXt Garden samples and with test samples from the 
mailing-list, as long as I can understand them (I am not a mathematician, only 
someone who needs to print classical texts) : 
https://fr.wikibooks.org/wiki/ConTeXt 

A simple question : is it usefull to get a very quick access to a documentation 
where explanation is absent ? That's why the current explanation is very useful 
: even if you have to read full pages at length, the explanation given in the 
PDF documentation is an accurate information and oftenly says something which 
allow to lead to a solve your issue. So, it seems there is a conflict between 
the desire of a quick access to relevant information and the need of learning 
ConTeXt with patience !
JP



- Mail original -
De: "Thomas A. Schmitz" 
À: "mailing list for ConTeXt users" 
Envoyé: Lundi 10 Octobre 2016 09:57:24
Objet: Re: [NTG-context] Ideas for improving documentation of ConTeXt

On 10/10/2016 07:43 AM, Jonas Baggett wrote:
>
> Thanks for your encouragement ! Yes that looks like an interesting
> challenge for me, but it is not something I am wanting to do alone
> because of my lack of experience, at least I would need someone to coach
> me. Actually I don't have really experience with web developpment and I
> would at least need help for the technological choices. Having someone
> that tells me that if I use technology X, there are module Y and Z that
> will be a good fit is a good start.

Just two small remarks:

1. there are not that many modules in ConTeXt because most of the 
functionality is in the core. If you come from the LaTeX world, you may 
expect several hundred packages, each with their own idiosyncracies and 
documentation. That's not the case here.

2. As for your documentation project, let me be honest: unless someone 
very dedicated and very knowledgeable makes a long-term commitment and 
looks after these examples, they are worse than useless. Unless there is 
very tight control, they may contain bad and/or outdated code and lead 
newcomers in the wrong direction. The context way has always been to 
avoid boilerplate templates and let users roll their own styles. Which 
makes sense since in context almost every detail can be changed easily 
via dedicated setup commands. (This is again quite unlike LaTeX and its 
document classes that predefine many details.) I have problems imagining 
a collection of sample documents that will be more than a haphazard 
bunch of fortuitous designs.

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://context.aanhet.net
archive  : http://foundry.supelec.fr/projects/contextrev/
wiki : http://contextgarden.net
___

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Thomas A. Schmitz 

On 10/10/2016 07:43 AM, Jonas Baggett wrote:


Thanks for your encouragement ! Yes that looks like an interesting
challenge for me, but it is not something I am wanting to do alone
because of my lack of experience, at least I would need someone to coach
me. Actually I don't have really experience with web developpment and I
would at least need help for the technological choices. Having someone
that tells me that if I use technology X, there are module Y and Z that
will be a good fit is a good start.


Just two small remarks:

1. there are not that many modules in ConTeXt because most of the 
functionality is in the core. If you come from the LaTeX world, you may 
expect several hundred packages, each with their own idiosyncracies and 
documentation. That's not the case here.


2. As for your documentation project, let me be honest: unless someone 
very dedicated and very knowledgeable makes a long-term commitment and 
looks after these examples, they are worse than useless. Unless there is 
very tight control, they may contain bad and/or outdated code and lead 
newcomers in the wrong direction. The context way has always been to 
avoid boilerplate templates and let users roll their own styles. Which 
makes sense since in context almost every detail can be changed easily 
via dedicated setup commands. (This is again quite unlike LaTeX and its 
document classes that predefine many details.) I have problems imagining 
a collection of sample documents that will be more than a haphazard 
bunch of fortuitous designs.


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] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Hans Hagen 

On 10/10/2016 12:49 AM, Jonas Baggett wrote:

Hello Henri,


Most probably no one else will volunteer to do it and especially the
people from PRAGMA surely have better things to do. They merely
develop and use ConTeXt (...)

Here I don't agree. People from PRAGMA are probably better at
developping ConTeXt than starting in parallel a new project like that,
but it doesn't mean that this idea is necessarly not worth considering.
I wasn't either suggesting that they should be the people who start
implementing the idea.

(...) and were so kind as to provide us a huge bunch of documentation
already (http://pragma-ade.nl/document-1.htm).

Yes I just saw that you are right about the documentation, they have
already made a huge work on that. I was maybe too quick about my
conclusion, I am sorry if I did offend those who have already make all
that work. I was actually doing a cover letter in ConTeXt and since I
wasn't able to find uptodate informations about some of the commands I
was a little frustrated. But yes the letter module is third party and I
just saw in the wiki that it is said to be still in developpment, so
interface changes are to be expected and not necessarly all documented.
Since I am new to ConTeXt, my views on ConTeXt documentation got biased.
But now I am pretty happy with the results I have with my document, so
most of the troubles are behind, I guess :-).


Don't worry, no one feels offended. FYI, Pragma is not that large a 
company so we cannot allocate more resources than we do now (and did the 
last couple of decades). We just provide the manuals we write in the 
process and happily leave the rest to others.



On the other hand, some of the documentation still need to be updated.
Since ConTeXt is quick to evolue, having uptodate documentation would be
a huge task and I also understand that it may not be the most
interesting part for developpers ;-). My proposition was about to
mitigate that problem with making accessible examples with some advanced
search to quickly find relevant results.


Not all old manuals will be updates. There are already a lot in the 
distribution and another 6 on my disk waiting for an mkiv update. These 
are often covering a specific aspect. I happily leave writing additional 
manuals to others.


Each year at the context meeting this topic pops op and there are many 
plans but a lack of time interferes.


Btw, Alan is writing a larger story for beginners.


Maybe someday ConTeXt will be more mature and have a more stable
interface, then it would be easier to have uptodate documentation. But
it is only the analysis of someone who is only starting to know ConTeXt,
so I won't assume to be totally correct.


The interface is actually rather stable otherwise we could not use it 
ourselves. However the move to luatex made it possible to kick out code 
related to input and font encoding as well as update to new technologies 
so there have been changes.  So, the trick is to point new users to the 
right examples and documentation.


Hans

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

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

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-10 Thread Hans Hagen 

On 10/10/2016 7:43 AM, Jonas Baggett wrote:

Hello Wolfgang,


Le 09. 10. 16 à 22:51, Wolfgang Schuster a écrit :

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.


Ok, I don't have enough the habit of consulting documentation that is
installed in my system. I have found something interesting here that
could be helpfull to me :
/usr/share/texmf/doc/context/base/examplap/gui/letter.pdf. It seems to
be a letter generator, but unfortunately I wasn't able to make it work.
Maybe it is outdated since it is 10 years old.


What context installation do you use? The reference is the one on the 
context garden. Each year tex lives has a snapshot of that one. So, 
first make sure you run the latest version.


Concerning old manuals: they often refer to mkii but with mkiv we have 
different (often better) solutions. The examplap code and examples are 
mkii and also relate to pdf trickery and as pdf evolved it became more 
clear what was bound to acrobat i.e. not picked up (ignored) by open 
source alternatives and therefore less relevant.


In the distribution the manuals made at out end will be added but that's 
mkiv only. The bigger ones will take a while as i have rather strict 
rules (for myself) for the quality of the sources of manuals.


In parallel there is a set of manuals made and being made by users 
(fonts and layout are done, tables and graphics is being worked on) and 
for these the context group is responsible.


Then of course there are all kind of manuals written by other developers 
and users.


An important source are the setup-*.pdf files as these describe the 
interface which is described in the interface definition files (in xml 
format). These have recently be updated by Wolfgang and are very accurate.


You mentioned that keys (functionality) that disappears should be 
somehow documented but normally no functionality disappears. What 
happened was that mkiv has some more (because it's possible) and less 
(because it was no longer needed) than mkii and has been made more 
consistent.



The wiki has a page for examples and you’re free to update the
existing examples or add new ones.


Do you mean http://wiki.contextgarden.net/Sample_documents ? Yes, that's
a good idea, since I believe that it is a way to improve documentation
with little efforts. Then I plan to add the cover letter style I made
since I am happy with the results, although 1 or 2 things could have
some improvement. There are also some letter styles there, then I will
have a look on them too. I don't know if people are intimidated about
writing contents in the wiki because it is the official wiki and feel
that only programmers are supposed to update it, but it will be really
helpfull if the users have more the habit of posting there the document
styles they made.


Indeed.


Sounds interesting and the best thing you can do is to start with it.


Thanks for your encouragement ! Yes that looks like an interesting
challenge for me, but it is not something I am wanting to do alone
because of my lack of experience, at least I would need someone to coach
me. Actually I don't have really experience with web developpment and I
would at least need help for the technological choices. Having someone
that tells me that if I use technology X, there are module Y and Z that
will be a good fit is a good start.


This will only work when someone takes the lead. If you do that you then 
others will help you. If you need something special on the wiki, just 
discuss it with Taco and Mojca who deal with the technicalities.


Hans

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

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

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Aditya Mahajan 

On Sun, 9 Oct 2016, Aditya Mahajan wrote:


On Sun, 9 Oct 2016, Jonas Baggett wrote:

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.


Recently, stackexchange started a similar project:
https://blog.stackoverflow.com/2016/07/introducing-stack-overflow-documentation-beta/

You can create a context tag and create example documents. The difficulty 
with such projects, as usual, is to have a critical mass for others to 
browse and contribute. One could start by "porting" existing examples from 
the wiki, mailing list, tex.stackexchange, etc.


Scratch that. It seems that documentation tags can only be created for 
topics that are popular on stackoverflow (not stackexchange).


http://meta.stackoverflow.com/questions/328667/new-tags-and-documentation-beta

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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Jonas Baggett 

Hello Wolfgang,


Le 09. 10. 16 à 22:51, Wolfgang Schuster a écrit :
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.


Ok, I don't have enough the habit of consulting documentation that is 
installed in my system. I have found something interesting here that 
could be helpfull to me : 
/usr/share/texmf/doc/context/base/examplap/gui/letter.pdf. It seems to 
be a letter generator, but unfortunately I wasn't able to make it work. 
Maybe it is outdated since it is 10 years old.


The wiki has a page for examples and you’re free to update the 
existing examples or add new ones.


Do you mean http://wiki.contextgarden.net/Sample_documents ? Yes, that's 
a good idea, since I believe that it is a way to improve documentation 
with little efforts. Then I plan to add the cover letter style I made 
since I am happy with the results, although 1 or 2 things could have 
some improvement. There are also some letter styles there, then I will 
have a look on them too. I don't know if people are intimidated about 
writing contents in the wiki because it is the official wiki and feel 
that only programmers are supposed to update it, but it will be really 
helpfull if the users have more the habit of posting there the document 
styles they made.



Sounds interesting and the best thing you can do is to start with it.


Thanks for your encouragement ! Yes that looks like an interesting 
challenge for me, but it is not something I am wanting to do alone 
because of my lack of experience, at least I would need someone to coach 
me. Actually I don't have really experience with web developpment and I 
would at least need help for the technological choices. Having someone 
that tells me that if I use technology X, there are module Y and Z that 
will be a good fit is a good start.


Have a nice day,
Jonas
___
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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Aditya Mahajan 

On Sun, 9 Oct 2016, Jonas Baggett wrote:

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.


Recently, stackexchange started a similar project:
https://blog.stackoverflow.com/2016/07/introducing-stack-overflow-documentation-beta/

You can create a context tag and create example documents. The difficulty 
with such projects, as usual, is to have a critical mass for others to 
browse and contribute. One could start by "porting" existing examples from 
the wiki, mailing list, tex.stackexchange, etc.


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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Jonas Baggett 

Le 09. 10. 16 à 15:49, Yi Qingliang a écrit :


GOOD IDEA！


Thanks for the encouragement :-).
___
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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Jonas Baggett 

Hello Henri,

Le 09. 10. 16 à 21:31, Henri Menke a écrit :

please don't be disappointed but you are not the first person to suggest such a 
thing.  You may now ask, why doesn't such a thing exist then?  Well, the basic 
answer is, go ahead and implement it.
I won't go ahead and implement it if I am the only one who would think 
it is a good idea. That's why I asked for some feedback. It happens 
sometimes that I could have an idea that looks great in my eyes, but 
then seems a little less shiny after hearing some feedback. But since I 
wasn't the first person to suggest such a thing, It seems to me that my 
idea goes in the right direction, isn't it ? It doesn't mean that no 
improvement is needed, and it still need to be implemented.



Most probably no one else will volunteer to do it and especially the people 
from PRAGMA surely have better things to do. They merely develop and use 
ConTeXt (...)
Here I don't agree. People from PRAGMA are probably better at 
developping ConTeXt than starting in parallel a new project like that, 
but it doesn't mean that this idea is necessarly not worth considering. 
I wasn't either suggesting that they should be the people who start 
implementing the idea.

(...) and were so kind as to provide us a huge bunch of documentation already 
(http://pragma-ade.nl/document-1.htm).
Yes I just saw that you are right about the documentation, they have 
already made a huge work on that. I was maybe too quick about my 
conclusion, I am sorry if I did offend those who have already make all 
that work. I was actually doing a cover letter in ConTeXt and since I 
wasn't able to find uptodate informations about some of the commands I 
was a little frustrated. But yes the letter module is third party and I 
just saw in the wiki that it is said to be still in developpment, so 
interface changes are to be expected and not necessarly all documented. 
Since I am new to ConTeXt, my views on ConTeXt documentation got biased. 
But now I am pretty happy with the results I have with my document, so 
most of the troubles are behind, I guess :-).


On the other hand, some of the documentation still need to be updated. 
Since ConTeXt is quick to evolue, having uptodate documentation would be 
a huge task and I also understand that it may not be the most 
interesting part for developpers ;-). My proposition was about to 
mitigate that problem with making accessible examples with some advanced 
search to quickly find relevant results.


Maybe someday ConTeXt will be more mature and have a more stable 
interface, then it would be easier to have uptodate documentation. But 
it is only the analysis of someone who is only starting to know ConTeXt, 
so I won't assume to be totally correct.


Cheers,
Jonas
___
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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Wolfgang Schuster 

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
___
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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Henri Menke 
Dear Jonas,

please don't be disappointed but you are not the first person to suggest such a 
thing.  You may now ask, why doesn't such a thing exist then?  Well, the basic 
answer is, go ahead and implement it.  Most probably no one else will volunteer 
to do it and especially the people from PRAGMA surely have better things to do. 
 They merely develop and use ConTeXt and were so kind as to provide us a huge 
bunch of documentation already (http://pragma-ade.nl/document-1.htm).

Cheers, Henri

On 10/09/2016 01:18 PM, Jonas Baggett wrote:
> 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.
> 
> 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.
> 
> 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.
> 
> Have a nice sunday,
> Jonas
> ___
> 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

Re: [NTG-context] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Yi Qingliang 
GOOD IDEA！

On Sun, Oct 9, 2016 at 7:18 PM, Jonas Baggett  wrote:
> 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.
>
> 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.
>
> 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.
>
> Have a nice sunday,
> Jonas
> ___
> 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] Ideas for improving documentation of ConTeXt

2016-10-09 Thread Jonas Baggett 

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.


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.


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.


Have a nice sunday,
Jonas
___
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
___