Hi, During a recent plane ride, I started to read the ConTeXt manual to get a better understanding: http://www.ctex.org/documents/context/cont-enp.pdf If anyone has plans to revise it, I have attached a file with corrections, specific comments, and general comments. I did not have the ConTeXt manual source code on hand, so I could not directly modify it. Take the comments with a grain of salt: I have little ConTeXt experience. I hope it proves useful. Kindest regards.
On 2013–09–18 Thangalin wrote: Hi Dave,
During a recent plane ride, I started to read the ConTeXt manual to get a better understanding: http://www.ctex.org/documents/context/cont-enp.pdf
A more recent manual can be found at http://pmrb.free.fr/contextref.pdf
If anyone has plans to revise it,
I assume everybody on this list had at some point plans to revise the manual(s). Due to lack of time this has never happened.
I have attached a file with corrections, specific comments, and general comments.
Thanks a lot for the corrections and suggestions.
I did not have the ConTeXt manual source code on hand, so I could not directly modify it.
http://wiki.contextgarden.net/Improving_the_manuals Do not count on someone else to fix it. Create an account and fix what you think could be improved, especially the grammar and spelling mistakes. If you're unsure about something, write a mail to the manual mailing list¹ for questions about the manual (style, layout, etc.) or this list for everything else. Note: The manual has not been updated since a while and it's broken at the moment. I'll prepare a fix soon, so it will compile with a recent MkIV.
Take the comments with a grain of salt:
Take the existing manuals with a grain of salt ;)
ConTeXT Manual Errata & Suggestions ===================================
Section 1.3. ------------ The word "something" needs to be defined before it is used. For example, "\setupsomething" <- What does "something" mean?
A placeholder like foobar or whatever. I think it's clear from the context, otherwise feel free to define it.
The \defineenumeration[Question] creates a \Question command, but \definehead[Procedure][section] does not create \Procedure command?
It does: \definehead [Procedure] [section] \starttext \Procedure{something} \stoptext However, I'd suggest to instead use: \startProcedure [title=something] … \stopProcedure
The \startnarrower requires an explanation on how it affects the resulting document. Likewise \startitemnize.
Feel free to add some info from the wiki. http://wiki.contextgarden.net/Command/startnarrower http://wiki.contextgarden.net/Enumerations
What does the "of" in "\beginofAnswer" mean? Is it required?
It's not required. It's actually wrong.
Where does it come from? Why is it not simply "\beginAnswer"?
MkII maybe?
"Figure 1.1 is typeset this way" should include the page number.
That's more difficult than it seems to be. The manual is available in different paper sizes and formats. This means the page number can't be coded as \in{figure}[foo] on \at{page}[foo], since the figure might end up on the same page. As far as I know ConTeXt does not have a general mechanism for automatically placing the “on page…” string if the reference is not on the current page. \atpage comes close, though.
Document processing is best done by TeXexec -- is this still true?
Well, your manual is from 2000.
I thought the "context" program supercedes TeXexec?
yes
Describe the relationship between TeX and ConTeXt. For example, why do the subsequent sections discuss TeX examples?
ConTeXt uses TeX and the following sections introduce some TeX concepts that hold true for ConTeXt as well.
Section 1.9. ------------ Relatively empty page.
On purpose. The reader is invited to take a break and grab a coffee. ;)
Section 2.2. ------------ "It is advisable to type the document setups before the \start--command," -- What start command? \starttext, perhaps?
\starttext, \startdocument, \startcomponent, etc. Marco
On 2013–09–21 Marco Patzer wrote:
I did not have the ConTeXt manual source code on hand, so I could not directly modify it.
http://wiki.contextgarden.net/Improving_the_manuals
Do not count on someone else to fix it. Create an account and fix what you think could be improved, especially the grammar and spelling mistakes. If you're unsure about something, write a mail to the manual mailing list¹ for questions about the manual (style, layout, etc.) or this list for everything else.
Note: The manual has not been updated since a while and it's broken at the moment. I'll prepare a fix soon, so it will compile with a recent MkIV.
I committed a fix today and now it should compile again. I did not fix any of your suggestions. You are invited to fix the source or send in a patch. I or someone else can review and merge them. The dedicated mailing list for the manual seems to be broken at the moment. Using this list for manual discussions is also fine, I guess. Marco
Hi,
I registered an account, but have not seen any confirmation.
Kindest regards.
On Thu, Sep 26, 2013 at 10:44 AM, Marco Patzer
On 2013–09–21 Marco Patzer wrote:
I did not have the ConTeXt manual source code on hand, so I could not directly modify it.
http://wiki.contextgarden.net/Improving_the_manuals
Do not count on someone else to fix it. Create an account and fix what you think could be improved, especially the grammar and spelling mistakes. If you're unsure about something, write a mail to the manual mailing list¹ for questions about the manual (style, layout, etc.) or this list for everything else.
Note: The manual has not been updated since a while and it's broken at the moment. I'll prepare a fix soon, so it will compile with a recent MkIV.
I committed a fix today and now it should compile again. I did not fix any of your suggestions. You are invited to fix the source or send in a patch. I or someone else can review and merge them.
The dedicated mailing list for the manual seems to be broken at the moment. Using this list for manual discussions is also fine, I guess.
Marco
___________________________________________________________________________________ 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
___________________________________________________________________________________
On Thu, 26 Sep 2013, Thangalin wrote:
Hi,
I registered an account, but have not seen any confirmation.
Kindest regards.
On Thu, Sep 26, 2013 at 10:44 AM, Marco Patzer
wrote: On 2013–09–21 Marco Patzer wrote:
I did not have the ConTeXt manual source code on hand, so I could not directly modify it.
http://wiki.contextgarden.net/Improving_the_manuals
Do not count on someone else to fix it. Create an account and fix what you think could be improved, especially the grammar and spelling mistakes. If you're unsure about something, write a mail to the manual mailing list¹ for questions about the manual (style, layout, etc.) or this list for everything else.
Note: The manual has not been updated since a while and it's broken at the moment. I'll prepare a fix soon, so it will compile with a recent MkIV.
I committed a fix today and now it should compile again. I did not fix any of your suggestions. You are invited to fix the source or send in a patch. I or someone else can review and merge them.
The dedicated mailing list for the manual seems to be broken at the moment. Using this list for manual discussions is also fine, I guess.
Wouldn't it be better to move the manuals to github rather than keeping them on an svn server? Aditya
@Peter github makes collaboration quite painless. Users can manage their
own accounts.
+1 for github from me too!
On Thu, Sep 26, 2013 at 1:42 PM, Peter Münster
On Thu, Sep 26 2013, Aditya Mahajan wrote:
Wouldn't it be better to move the manuals to github rather than keeping them on an svn server?
Why?
-- Peter
___________________________________________________________________________________ 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
___________________________________________________________________________________
On Thu, Sep 26 2013, Mica Semrick wrote:
@Peter github makes collaboration quite painless. Users can manage their own accounts.
I like git because of its features. And when I don't need those features, I prefer svn because of its simplicity. Where is the pain? What would be the benefit when moving to github? -1 (not worth the trouble for me) (On the other hand, if you sent me some bitcoins, I would be glad to copy contextman to github. ;) -- Peter
Where is the pain? What would be the benefit when moving to github?
On the thread someone wanted to add something to the manual, but didn't
have SVN access. The admin wasn't getting email, and thus couldn't grant
the new account. The material was not added the to manual.
If the manual was on github, it could have been forked, branched, content
added, pull request made. End of story. So we do want the features of
github.
On Thu, Sep 26, 2013 at 2:50 PM, Peter Münster
On Thu, Sep 26 2013, Mica Semrick wrote:
@Peter github makes collaboration quite painless. Users can manage their own accounts.
I like git because of its features. And when I don't need those features, I prefer svn because of its simplicity. Where is the pain? What would be the benefit when moving to github?
-1 (not worth the trouble for me)
(On the other hand, if you sent me some bitcoins, I would be glad to copy contextman to github. ;)
-- Peter
___________________________________________________________________________________ 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
___________________________________________________________________________________
That is an excellent summation, Mica.
On Thu, Sep 26, 2013 at 2:56 PM, Mica Semrick
Where is the pain? What would be the benefit when moving to github?
On the thread someone wanted to add something to the manual, but didn't have SVN access. The admin wasn't getting email, and thus couldn't grant the new account. The material was not added the to manual.
If the manual was on github, it could have been forked, branched, content added, pull request made. End of story. So we do want the features of github.
On Thu, Sep 26, 2013 at 2:50 PM, Peter Münster
wrote: On Thu, Sep 26 2013, Mica Semrick wrote:
@Peter github makes collaboration quite painless. Users can manage their own accounts.
I like git because of its features. And when I don't need those features, I prefer svn because of its simplicity. Where is the pain? What would be the benefit when moving to github?
-1 (not worth the trouble for me)
(On the other hand, if you sent me some bitcoins, I would be glad to copy contextman to github. ;)
-- Peter
___________________________________________________________________________________ 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
___________________________________________________________________________________
On Thu, 26 Sep 2013, Peter Münster wrote:
On Thu, Sep 26 2013, Mica Semrick wrote:
@Peter github makes collaboration quite painless. Users can manage their own accounts.
I like git because of its features. And when I don't need those features, I prefer svn because of its simplicity. Where is the pain?
The last time I tried, merging multiple version in svn is a huge pain. One of the advantages of DVCS is that branching and merging are easy.
What would be the benefit when moving to github?
Github seems to be the most popular DVCS hosting site at the moment. For manuals, I think that Github is particularly useful because you can click on edit and make the change. Github automatically creates a fork, a new branch, and pull request for you. So the technical barrier to participation is low.
-1 (not worth the trouble for me)
(On the other hand, if you sent me some bitcoins, I would be glad to copy contextman to github. ;)
https://github.com/nirvdrum/svn2git Using this is usually as simple as svn2git http://svn.example.com/path/to/repo Aditya
On Fri, Sep 27 2013, Aditya Mahajan wrote:
The last time I tried, merging multiple version in svn is a huge pain. One of the advantages of DVCS is that branching and merging are easy.
I understand. Please go ahead if you need git. My preference for svn is just my personal opinion, coming from my personal experience: people wanted to change a well running system, using the latest and greatest tools. In the end, after quite some efforts, there was no benefit, it was just a bit more complicated. I'm just lucky doing my 3 svn-commits per year, and with git I would do git-commits. -- Peter
On Sep 27, 2013, at 9:01 AM, Peter Münster
On Fri, Sep 27 2013, Aditya Mahajan wrote:
The last time I tried, merging multiple version in svn is a huge pain. One of the advantages of DVCS is that branching and merging are easy.
I understand. Please go ahead if you need git. My preference for svn is just my personal opinion, coming from my personal experience: people wanted to change a well running system, using the latest and greatest tools. In the end, after quite some efforts, there was no benefit, it was just a bit more complicated.
+1 from me: I have exactly the same experience personally.
I'm just lucky doing my 3 svn-commits per year, and with git I would do git-commits.
+1 again. The manual is on supelec because that is where the metapost and luatex repositories are, and it is a subversion repo because when the project was first added, the software system on supelec did not understand git. The current version of Forge does support git repos, but I never switched since (as I wrote above) I have a small personal preference for subversion. So it would be possible to have a git on supelec; for that reason there is no need to switch to github. There may be a small advantage to staying with supelec as then the main project URL does not have to change. OTOH, supelec's email stuff breaks easily and somewhat often. Best wishes, Taco
On 9/27/2013 3:38 AM, Taco Hoekwater wrote:
On Sep 27, 2013, at 9:01 AM, Peter Münster
wrote: On Fri, Sep 27 2013, Aditya Mahajan wrote:
The last time I tried, merging multiple version in svn is a huge pain. One of the advantages of DVCS is that branching and merging are easy. I understand. Please go ahead if you need git. My preference for svn is just my personal opinion, coming from my personal experience: people wanted to change a well running system, using the latest and greatest tools. In the end, after quite some efforts, there was no benefit, it was just a bit more complicated. +1 from me: I have exactly the same experience personally.
I'm with Taco and Peter on this one. SVN is part of my everyday workflow; Git requires a lot more reading and fumbling. However I know the need to be fluent with Git is becoming more and more prevalent, and for many people it's already the easiest thing. So I wouldn't argue against moving to Git. I'm just reporting my preference. BTW I committed several changes to the manual yesterday, and plan to do a fair bit more in the coming week or two. I would appreciate if someone knowledgeable could check and make sure that I haven't said things that are misleading or incorrect. Lars
On 9/26/2013 9:10 PM, Aditya Mahajan wrote:
Github seems to be the most popular DVCS hosting site at the moment. For manuals, I think that Github is particularly useful because you can click on edit and make the change. Github automatically creates a fork, a new branch, and pull request for you. So the technical barrier to participation is low.
I would question the perception that the technical barrier to participation on Github is low. Not long ago I tried to submit a patch to a project on Github, improving documentation and adding features. It took several hours (distributed over a couple of weeks) to learn how to do all that was required. It was *not* automatic. It strongly discouraged me from making more contributions to that project. Maybe some major things have changed on Github since then. In any case, I have no doubt that once you know the system, and have the infrastructure set up, it's easy to participate. And I'm not saying that SVN makes it easy for non-SVN users to participate. All I'm saying is that for non-Git users, the technical barrier to participation was substantial, last time I tried it. Again, I'm not arguing against a move to Git. I would just like to contribute my recent experience toward a well-informed decision process. Lars
Dnia 2013-09-27, o godz. 09:10:04
Lars Huttar
On 9/26/2013 9:10 PM, Aditya Mahajan wrote:
Github seems to be the most popular DVCS hosting site at the moment. For manuals, I think that Github is particularly useful because you can click on edit and make the change. Github automatically creates a fork, a new branch, and pull request for you. So the technical barrier to participation is low.
I would question the perception that the technical barrier to participation on Github is low. Not long ago I tried to submit a patch to a project on Github, improving documentation and adding features. It took several hours (distributed over a couple of weeks) to learn how to do all that was required. It was *not* automatic. It strongly discouraged me from making more contributions to that project.
Maybe some major things have changed on Github since then. In any case, I have no doubt that once you know the system, and have the infrastructure set up, it's easy to participate. And I'm not saying that SVN makes it easy for non-SVN users to participate. All I'm saying is that for non-Git users, the technical barrier to participation was substantial, last time I tried it.
Again, I'm not arguing against a move to Git. I would just like to contribute my recent experience toward a well-informed decision process.
Just my 3 cents. I am not a heavy Git user (though I am quite accustomed to Mercurial instead), and I agree that the entry point for Git is not very low. However, it seems that nowadays, for a *new* user, learning to use SVN is pointless (unless he joins a project where SVN is used etc.): distributed VCSs seem to be just much better (and I heard that SVN has its own problems, too). So I would perceive this question as touching a demography issue: younger people are more likely to know/use Git (and not know SVN), older folk might know/use SVN. Also, if this matters, Git has an excellent Emacs front-end, Magit. I don't know whether SVN has something similar.
Lars
Best, -- Marcin Borkowski http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski Adam Mickiewicz University
On Fri, Sep 27 2013, Marcin Borkowski wrote:
However, it seems that nowadays, for a *new* user, learning to use SVN is pointless
For our use case (enhancing the documentation) that's a nonissue: git or svn, there is nothing to learn, just pull, edit, commit. 3 lines on the project web page will show you what to do. Of course, if you choose a complicated workflow (maintaining several branches, test and validation cycles, commit signatures, and so on), then git would be a good choice, and yes, then you'll have to learn it. But please don't spend more time with the DVCS than with the improvement of the manual... ;) -- Peter
On 9/27/2013 3:26 PM, Marcin Borkowski wrote:
Also, if this matters, Git has an excellent Emacs front-end, Magit. I don't know whether SVN has something similar.
github has a nice windows backend but (as with more open source developments) the real nice stuff is closed ... i tried several times but never could install easily some git server infrastructure similar to github on a (linux) server so at our company we stay with svn (but i keep copies of the context-on-github on my machine, but only for viewing) Hans ----------------------------------------------------------------- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | voip: 087 875 68 74 | www.pragma-ade.com | www.pragma-pod.nl -----------------------------------------------------------------
Maybe we can have the best of both: https://gist.github.com/ticean/1556967 ?
On Fri, Sep 27, 2013 at 7:27 AM, Hans Hagen
On 9/27/2013 3:26 PM, Marcin Borkowski wrote:
Also, if this matters, Git has an excellent Emacs front-end, Magit. I
don't know whether SVN has something similar.
github has a nice windows backend but (as with more open source developments) the real nice stuff is closed ... i tried several times but never could install easily some git server infrastructure similar to github on a (linux) server so at our company we stay with svn (but i keep copies of the context-on-github on my machine, but only for viewing)
Hans
------------------------------**------------------------------**----- Hans Hagen | PRAGMA ADE Ridderstraat 27 | 8061 GH Hasselt | The Netherlands tel: 038 477 53 69 | voip: 087 875 68 74 | www.pragma-ade.com | www.pragma-pod.nl ------------------------------**------------------------------**-----
______________________________**______________________________** _______________________ If your question is of interest to others as well, please add an entry to the Wiki!
maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/** listinfo/ntg-context 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/http://foundry.supelec.fr/projects/contextrev/ wiki : http://contextgarden.net ______________________________**______________________________** _______________________
+π from me. My preference would be BitBucket (slightly simpler than github and allows for free private repositories), but, either way, the result is the same: fewer steps to updating the manual. Moving away from svn to git is also a step in the right direction, IMO. One aspect of wikis that I thoroughly enjoy is the ability to fix something (contribute) immediately. Moving to a web-based repository for the manual removes barriers (such as waiting upon moderated approvals whilst the moderator vacations) to letting people contribute to projects. Throw in a nightly build (with blaming) to ensure that the manual compile is never broken (for long). Regards.
On 2013–09–26 Peter Münster wrote:
On Thu, Sep 26 2013, Aditya Mahajan wrote:
Wouldn't it be better to move the manuals to github rather than keeping them on an svn server?
Why?
In my opinion, for the “3 commits per year” it doesn't really matter which version control system is being used. No particular git feature is required for such a simple and low-traffic code base as the manual. For me it's more a choice of infrastructure. It is easier to collaborate on github. It's popular, people know how to use it and it doesn't require an invitation. Github's GUI is more friendly to beginners not familiar with revision control systems. The simpler it is to contribute the more likely it is for people to do so. But, I agree, there are valid reasons to stay with supelec, the main one being that it's already there. Still, I would support a change. More importantly I would like to see people actually contributing. Marco
On Fri, Sep 27 2013, Marco Patzer wrote:
More importantly I would like to see people actually contributing.
+1 And it would be no problem for me (and for other contextman members) to apply contributed patches. Whoever wants to contribute without worrying about the VCS can send a patch here. -- Peter
On 2013–09–26 Thangalin wrote:
I registered an account, but have not seen any confirmation.
Supelec has problems with the mail system at the moment. So Taco doesn't get a notification if someone requests commit access. I cc'd him, so he should get notified that way. In case you still don't get a confirmation, wait until next week, then he'll be back. Marco
participants (9)
-
Aditya Mahajan
-
Hans Hagen
-
Lars Huttar
-
Marcin Borkowski
-
Marco Patzer
-
Mica Semrick
-
Peter Münster
-
Taco Hoekwater
-
Thangalin