[web2py] Re: for your info
Some experiences from many years of working with wikis, small to medium to large: -- Autoconversion: It is very hard to *automatically* convert any bigger, heterogenous material to a *good* wiki format. Attemptions are plenty, all of them failed. Probably it is impossible. Except conversions from other wikis (e.g. from MediaWiki to DokuWiki or vice versa). Causes are many. Lots of. (Opposite ends: manual conversion, small material, homogenous material, poor quality wiki.) It is very hard to *automatically* convert any wiki to a *good* book format. Probably impossible. (Opposite ends: manual conversion, poor quality book.) I suggest abdicating the hope for autoconversions. Superfluous work. -- Why HTML? Main argument for an *HTML documentation*: anybody can link into one of its pages. This seemingly simple feature brings huge benefits over the time. Internal and external linking and link handling capabilities in PDF and other formats are very limited. Hypertext offers huge inherent benefits, but document formats (PDF, CHM, DOC, RTF etc.) are essentially sequential. Sequential structure of conventional documents helps *learning* and storytelling. Structure of heavily linked hypertexts helps *writing* (for example thru ad-hoc linking of new subpages) and similarity based searching (thru surfing). It follows that conventional documents helps beginners, hypertexts helps to write and read complete documentations. -- Why wiki? Main arguments for a *wiki* (online, editable HTML documentation): * Simple syntax, so anybody can contribute. (Better, if only registered users can.) * Unlimited page revisions. So you can compare them. Easy to find the modifications with colored, side by side diff (built in feature in better wikis). * List of recent changes. So easy to find the new parts. * Section editing helps quick changes. * Easy to embed images in many formats and arbitrary sizes. * Page locking or conflict resolution precludes edit conflicts. -- Which wiki? Web2py has a wiki, with unique, powerful features: T3 (e.g. wiki.web2py.com). While I'm delighted with T3, and I hope its wiki capabilities will improve over the time, *now* and in the near future it isn't appropriate for carrying a *complete* documentation of a serious software project. There are lots of wiki. There are only a few good ones. While it can be hotly debated, I'm sure DokuWiki is the best choice for documenting web2py. Because: * All data is stored in plain text files. So we can versioning them, parallelly with other parts of the project. And it is easy to generate wiki pages. * DokuWiki is easy to use, feature rich and standards-compliant. * If a project using Trac, then probably it is better choice than DokuWiki. (Trac uses plain text files, easy to use, moderately feature rich.) But web2py project don't using Trac. * If a project similar to Wikipedia, then probably it is better choice than DokuWiki. But web2py: ** less popular than Wikipedia (yet ;), so don't require eminent scalability of internal search, ** and don't require advanced media handling (media revisions etc.). (Scalability of search function in non-public, large dokuwikis is problematic. In public dokuwikis web search engines can substitute internal search.) Yes, DokuWiki is PHP-based. So we will lose the purity. Bearable pain. -- How to wiki? This deserves longer explanation. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
I have checked some other projects (django, tg, pylons, python.org etc). My understanding is that, = The core documentation must be maintained by core-devs who know the code inside out, This doc is the ultimate reference and should be in Restructured format text-files, in a SVN/Hg repository. RST to HTML conversion should be performed and published online. Users should be able to submit comments (Django allows at the paragraph level, pylons allows comments at the page level). These comments should be reviewed the core-dev or core-doc team and the docs updated frequently. = User generated docs which are likely to contain errors , inaccuracies, tips, hints etc should be maintained in a separate wiki/ site such as moinmoin or a CMS such as Drupal or Joomla. Some extremely useful tips etc can be pulled into the core-docs. Some can be left in this state and maintained separately. I am accumulating all my comments here: http://webtopy.org/community/w2py-doc-conundrum I am willing to assist in a one time Latex or PDF to ReST manual conversion . A group of members on this list can form a taskforce and splitup chapters and perform the conversion. If one of the list members can come up with a budget and a deadline to develop a kickass web2py wiki, we can come up with contributions / funds. I am willing to put up USD 100 -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
I am taking this approach for now: 1) convert the book to markdown (including conversion of eps images to png and conversion of references) 2) real time markdown to html (using special markup for references) 3) ability to annotate the book sections with user comments 4) automatically link all keywords in code example with corresponding docstrings 5) everything will have versioning so periodically I can diff the book and the docstrings and generate a patch (this will not be fully automated because the patch will be for wiki syntax not latex but I can convert back). When done I will loose some money from book sales so I will start taking donations. ;-) *** If you want to help, help make the Sphinx documentation work!!! *** So we can replace epydoc with Sphinx. Massimo On Feb 9, 7:59 am, Anand Vaidya anandvaidya...@gmail.com wrote: I have checked some other projects (django, tg, pylons, python.org etc). My understanding is that, = The core documentation must be maintained by core-devs who know the code inside out, This doc is the ultimate reference and should be in Restructured format text-files, in a SVN/Hg repository. RST to HTML conversion should be performed and published online. Users should be able to submit comments (Django allows at the paragraph level, pylons allows comments at the page level). These comments should be reviewed the core-dev or core-doc team and the docs updated frequently. = User generated docs which are likely to contain errors , inaccuracies, tips, hints etc should be maintained in a separate wiki/ site such as moinmoin or a CMS such as Drupal or Joomla. Some extremely useful tips etc can be pulled into the core-docs. Some can be left in this state and maintained separately. I am accumulating all my comments here:http://webtopy.org/community/w2py-doc-conundrum I am willing to assist in a one time Latex or PDF to ReST manual conversion . A group of members on this list can form a taskforce and splitup chapters and perform the conversion. If one of the list members can come up with a budget and a deadline to develop a kickass web2py wiki, we can come up with contributions / funds. I am willing to put up USD 100 -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
On Feb 9, 2010, at 1:58 AM, Beerc wrote: Some experiences from many years of working with wikis, small to medium to large: This all sounds very sensible. We ought to take advantage of homogeneous material where we can find it. Docstrings in particular could feed a set of wiki pages (read-only, unless someone wants to take on the back-edit problem). On the choice of wiki, I'd take a look at MoinMoin (with the caveat that I have all of about 20 minutes experience looking at it). It seems relatively mature, uses plain-text files, uses a MediaWiki-flavor markup, and is written in Python to boot. (I agree that this isn't a major point, but it's at least a plus, in that it's the home team, and as a group we have the resources to contribute there if we really need a feature or a fix. And if it's really good, I'd consider it as an adjunct to a web2py website of my own.) -- Autoconversion: It is very hard to *automatically* convert any bigger, heterogenous material to a *good* wiki format. Attemptions are plenty, all of them failed. Probably it is impossible. Except conversions from other wikis (e.g. from MediaWiki to DokuWiki or vice versa). Causes are many. Lots of. (Opposite ends: manual conversion, small material, homogenous material, poor quality wiki.) It is very hard to *automatically* convert any wiki to a *good* book format. Probably impossible. (Opposite ends: manual conversion, poor quality book.) I suggest abdicating the hope for autoconversions. Superfluous work. -- Why HTML? Main argument for an *HTML documentation*: anybody can link into one of its pages. This seemingly simple feature brings huge benefits over the time. Internal and external linking and link handling capabilities in PDF and other formats are very limited. Hypertext offers huge inherent benefits, but document formats (PDF, CHM, DOC, RTF etc.) are essentially sequential. Sequential structure of conventional documents helps *learning* and storytelling. Structure of heavily linked hypertexts helps *writing* (for example thru ad-hoc linking of new subpages) and similarity based searching (thru surfing). It follows that conventional documents helps beginners, hypertexts helps to write and read complete documentations. -- Why wiki? Main arguments for a *wiki* (online, editable HTML documentation): * Simple syntax, so anybody can contribute. (Better, if only registered users can.) * Unlimited page revisions. So you can compare them. Easy to find the modifications with colored, side by side diff (built in feature in better wikis). * List of recent changes. So easy to find the new parts. * Section editing helps quick changes. * Easy to embed images in many formats and arbitrary sizes. * Page locking or conflict resolution precludes edit conflicts. -- Which wiki? Web2py has a wiki, with unique, powerful features: T3 (e.g. wiki.web2py.com). While I'm delighted with T3, and I hope its wiki capabilities will improve over the time, *now* and in the near future it isn't appropriate for carrying a *complete* documentation of a serious software project. There are lots of wiki. There are only a few good ones. While it can be hotly debated, I'm sure DokuWiki is the best choice for documenting web2py. Because: * All data is stored in plain text files. So we can versioning them, parallelly with other parts of the project. And it is easy to generate wiki pages. * DokuWiki is easy to use, feature rich and standards-compliant. * If a project using Trac, then probably it is better choice than DokuWiki. (Trac uses plain text files, easy to use, moderately feature rich.) But web2py project don't using Trac. * If a project similar to Wikipedia, then probably it is better choice than DokuWiki. But web2py: ** less popular than Wikipedia (yet ;), so don't require eminent scalability of internal search, ** and don't require advanced media handling (media revisions etc.). (Scalability of search function in non-public, large dokuwikis is problematic. In public dokuwikis web search engines can substitute internal search.) Yes, DokuWiki is PHP-based. So we will lose the purity. Bearable pain. -- How to wiki? This deserves longer explanation. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
On Feb 9, 2010, at 6:55 AM, mdipierro wrote: *** If you want to help, help make the Sphinx documentation work!!! *** So we can replace epydoc with Sphinx. What would this entail? I'm guessing that most of us don't have a clue about Sphinx. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
On the choice of wiki, I'd take a look at MoinMoin I admit my experiences with MoinMoin are old (around 2005). Then it was mediocre. After your current recommendation I revised my memories. Latest versions are far better than the older ones. * It still hasn't section editing. Seemingly minor feature, but *crucial*. * The size of editing textarea is fixed. In DokuWiki you can resize it, size data stored in cookie. Valuable feature (not crucial). * Otherwise now it seems very good. Despite its deficiencies, I'm not opposing MoinMoin. Cut and paste+desktop editor+cut and paste is an affordable substitute for section editing. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
On Feb 9, 2010, at 10:19 AM, Beerc wrote: On the choice of wiki, I'd take a look at MoinMoin I admit my experiences with MoinMoin are old (around 2005). Then it was mediocre. After your current recommendation I revised my memories. Latest versions are far better than the older ones. * It still hasn't section editing. Seemingly minor feature, but *crucial*. I agree. * The size of editing textarea is fixed. In DokuWiki you can resize it, size data stored in cookie. Valuable feature (not crucial). Nice, though (for me) not an issue, because Safari resizes textareas. Also, the default MM edit textarea is pretty big, fwiw. * Otherwise now it seems very good. Despite its deficiencies, I'm not opposing MoinMoin. Cut and paste+desktop editor+cut and paste is an affordable substitute for section editing. Painful, though. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
sounds like this app will be like djangobook - neat. On Feb 10, 1:55 am, mdipierro mdipie...@cs.depaul.edu wrote: I am taking this approach for now: 1) convert the book to markdown (including conversion of eps images to png and conversion of references) 2) real time markdown to html (using special markup for references) 3) ability to annotate the book sections with user comments 4) automatically link all keywords in code example with corresponding docstrings 5) everything will have versioning so periodically I can diff the book and the docstrings and generate a patch (this will not be fully automated because the patch will be for wiki syntax not latex but I can convert back). When done I will loose some money from book sales so I will start taking donations. ;-) *** If you want to help, help make the Sphinx documentation work!!! *** So we can replace epydoc with Sphinx. Massimo On Feb 9, 7:59 am, Anand Vaidya anandvaidya...@gmail.com wrote: I have checked some other projects (django, tg, pylons, python.org etc). My understanding is that, = The core documentation must be maintained by core-devs who know the code inside out, This doc is the ultimate reference and should be in Restructured format text-files, in a SVN/Hg repository. RST to HTML conversion should be performed and published online. Users should be able to submit comments (Django allows at the paragraph level, pylons allows comments at the page level). These comments should be reviewed the core-dev or core-doc team and the docs updated frequently. = User generated docs which are likely to contain errors , inaccuracies, tips, hints etc should be maintained in a separate wiki/ site such as moinmoin or a CMS such as Drupal or Joomla. Some extremely useful tips etc can be pulled into the core-docs. Some can be left in this state and maintained separately. I am accumulating all my comments here:http://webtopy.org/community/w2py-doc-conundrum I am willing to assist in a one time Latex or PDF to ReST manual conversion . A group of members on this list can form a taskforce and splitup chapters and perform the conversion. If one of the list members can come up with a budget and a deadline to develop a kickass web2py wiki, we can come up with contributions / funds. I am willing to put up USD 100 -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
After some quick testing, I have found that MoinMoin works fine with RST without any additional software (only python-docutils needed) and with markdown too (needs python-markdown installed). Moreover, with a theme such as Moniker, the wiki looks neat. Regards Anand On Feb 10, 8:02 am, Richard richar...@gmail.com wrote: sounds like this app will be like djangobook - neat. On Feb 10, 1:55 am, mdipierro mdipie...@cs.depaul.edu wrote: I am taking this approach for now: 1) convert the book to markdown (including conversion of eps images to png and conversion of references) 2) real time markdown to html (using special markup for references) 3) ability to annotate the book sections with user comments 4) automatically link all keywords in code example with corresponding docstrings 5) everything will have versioning so periodically I can diff the book and the docstrings and generate a patch (this will not be fully automated because the patch will be for wiki syntax not latex but I can convert back). When done I will loose some money from book sales so I will start taking donations. ;-) *** If you want to help, help make the Sphinx documentation work!!! *** So we can replace epydoc with Sphinx. Massimo On Feb 9, 7:59 am, Anand Vaidya anandvaidya...@gmail.com wrote: I have checked some other projects (django, tg, pylons, python.org etc). My understanding is that, = The core documentation must be maintained by core-devs who know the code inside out, This doc is the ultimate reference and should be in Restructured format text-files, in a SVN/Hg repository. RST to HTML conversion should be performed and published online. Users should be able to submit comments (Django allows at the paragraph level, pylons allows comments at the page level). These comments should be reviewed the core-dev or core-doc team and the docs updated frequently. = User generated docs which are likely to contain errors , inaccuracies, tips, hints etc should be maintained in a separate wiki/ site such as moinmoin or a CMS such as Drupal or Joomla. Some extremely useful tips etc can be pulled into the core-docs. Some can be left in this state and maintained separately. I am accumulating all my comments here:http://webtopy.org/community/w2py-doc-conundrum I am willing to assist in a one time Latex or PDF to ReST manual conversion . A group of members on this list can form a taskforce and splitup chapters and perform the conversion. If one of the list members can come up with a budget and a deadline to develop a kickass web2py wiki, we can come up with contributions / funds. I am willing to put up USD 100 -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
subjective part I ***LOVE*** the tight integration of web2py components. I ***LOVE*** the compactness of web2py. I ***HATE*** over-abstracted, over-engineered, over-complicated, Java- style enterprisey code. YAGNI, KISS, less is more are hard-earned parts of developer wisdom. Most of the web frameworks somehow derailed their trains from the lean track. Most of them follow a wrong set of _dogmas_. Weheh said: Web2py is wonderful because of its simplicity, consistency and performance. YES, and of its security, and of its backward compatibility, and... and... and... /subjective part objective part Selecting developer toolset is a matter of taste. Obviously. Always. If you abominate from web2py, don't use it. /objective part !! Web2py has a single, but big weak point: scattered, hard-to-follow documentation. The importance of up-to-date, detailed, clear documentation is undeniable. Undocumented features are similar to untested code. Out-of-date docs are similar to buggy code. Most programmers hate writing documents. But writing docs is *easy*: * It is error prone? Errors are fixable, docs are never perfect! * It is time consuming? Write some *short* sentences after succesful coding! Be proud, praise your work! * It is difficult to write in clear, concise, elegant style? Then write some foggy, verbose, clumsy fragment. Somebody, some time will make it clear, concise, elegant. Good documentation has two mains parts: * A wiki to keep the front. With *all* of the usable informations, details and fragments. [MISSING BADLY]. * A book for beginners, to ease the start, to stimulate the appetite. [CHECK]. Toss details into the wiki, reference them in the book. [THIS IS A TRICK, NOT A REQUIREMENT]. /!! -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
On Feb 8, 2010, at 2:46 AM, Beerc wrote: I ***LOVE*** the tight integration of web2py components. I ***LOVE*** the compactness of web2py. These are by far the two biggest reasons I started using web2py, mainly over Django and its kin. Now that I have a little more experience, I'd add this mailing list to my list of reasons. My biggest complaint is what has been referred to as magic behavior, and in particular the relative opaqueness of some of that magic. Documentation could help there by making more clear what's going on inside; there's a little too much do this and it just works right now. But that's true of (say) RoR, too, so web2py isn't alone. I like the idea of a wiki that parallels the structure of the book. I'd also like to see a page each for all (or at least the important) classes, linked to their mentions in the mainline docs, where among other things magic behavior is explained. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
I am considering posting most of the book on line in HTML. This may be possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. On Feb 8, 10:18 am, Jonathan Lundell jlund...@pobox.com wrote: On Feb 8, 2010, at 2:46 AM, Beerc wrote: I ***LOVE*** the tight integration of web2py components. I ***LOVE*** the compactness of web2py. These are by far the two biggest reasons I started using web2py, mainly over Django and its kin. Now that I have a little more experience, I'd add this mailing list to my list of reasons. My biggest complaint is what has been referred to as magic behavior, and in particular the relative opaqueness of some of that magic. Documentation could help there by making more clear what's going on inside; there's a little too much do this and it just works right now. But that's true of (say) RoR, too, so web2py isn't alone. I like the idea of a wiki that parallels the structure of the book. I'd also like to see a page each for all (or at least the important) classes, linked to their mentions in the mainline docs, where among other things magic behavior is explained. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
Lookin into that but I am not sure they work as good as they should. Moreover they are not reversible so changes in the wiki would not easily propagate into the latex book (which I consider the master documentation). On Feb 8, 10:43 am, DenesL denes1...@yahoo.ca wrote: On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
On Feb 8, 2010, at 8:43 AM, DenesL wrote: On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. I investigated that a couple of years ago for an online journal. There are tools, but (at least at the time) they were not very good, and not maintained. So we gave up and stuck with pdf. How about a restricted-use PDF? -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
my two cents: decide where to host this new documentation (http://wiki.web2py.com/ may be the most obvious bet). set up a page of links that reproduces the tree structure of the pdf summary. then one by one, anyone can copy / past text from the pdf to the new pages and format it. this is the most straight forward way to get it done, i think, and it leaves plenty of space for people to correct / add / update infos on all the topics. On Feb 8, 6:01 pm, mdipierro mdipie...@cs.depaul.edu wrote: Lookin into that but I am not sure they work as good as they should. Moreover they are not reversible so changes in the wiki would not easily propagate into the latex book (which I consider the master documentation). On Feb 8, 10:43 am, DenesL denes1...@yahoo.ca wrote: On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
Better, look at http://www.djangobook.com/en/2.0 I like especially the side notes... The author would review each comment and decide what to do, so IMHO no need for an automatic hypothetic html2latex tool... On Feb 8, 6:16 pm, pistacchio pistacc...@gmail.com wrote: my two cents: decide where to host this new documentation (http://wiki.web2py.com/ may be the most obvious bet). set up a page of links that reproduces the tree structure of the pdf summary. then one by one, anyone can copy / past text from the pdf to the new pages and format it. this is the most straight forward way to get it done, i think, and it leaves plenty of space for people to correct / add / update infos on all the topics. On Feb 8, 6:01 pm, mdipierro mdipie...@cs.depaul.edu wrote: Lookin into that but I am not sure they work as good as they should. Moreover they are not reversible so changes in the wiki would not easily propagate into the latex book (which I consider the master documentation). On Feb 8, 10:43 am, DenesL denes1...@yahoo.ca wrote: On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
the problem with pdf is it is not searchable. Take a look at http://www.cubicweb.org/doc/en/index.html That is nice, its in a tutorial style format, but it is a wiki so it supports contextual searching via google. Its not all that special just a basic wiki where the pages are linked together in order. -Thadeus On Mon, Feb 8, 2010 at 11:07 AM, Jonathan Lundell jlund...@pobox.com wrote: On Feb 8, 2010, at 8:43 AM, DenesL wrote: On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. I investigated that a couple of years ago for an online journal. There are tools, but (at least at the time) they were not very good, and not maintained. So we gave up and stuck with pdf. How about a restricted-use PDF? -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
Also, the ones who complain about the documentation, are not knowledgeable enough in web2py to write documentation. The ones who are knowledgeable enough in web2py are too busy (either with web2py or real world) to write documentation. I cannot stress enough the fact that any and all contributors (including Massimo) needs to start documenting as you go, put it in the source code, put it on the wiki. As long as the information is there then english majors can come along and format the docs correctly and in a logical manner. We need to write documentation on how we are going to document web2py A page needs to be added to the wiki, that will be a complete structured document of how web2py will be documented, including coding style, doctest style, and wikidoc style. We don't need a non-web2py based system, we have web2py wiki system that can do all that we need, we just need to use it. -Thadeus On Mon, Feb 8, 2010 at 11:54 AM, Thadeus Burgess thade...@thadeusb.com wrote: the problem with pdf is it is not searchable. Take a look at http://www.cubicweb.org/doc/en/index.html That is nice, its in a tutorial style format, but it is a wiki so it supports contextual searching via google. Its not all that special just a basic wiki where the pages are linked together in order. -Thadeus On Mon, Feb 8, 2010 at 11:07 AM, Jonathan Lundell jlund...@pobox.com wrote: On Feb 8, 2010, at 8:43 AM, DenesL wrote: On Feb 8, 11:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be +1000! possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. No latex to HTML conversion tools?. I investigated that a couple of years ago for an online journal. There are tools, but (at least at the time) they were not very good, and not maintained. So we gave up and stuck with pdf. How about a restricted-use PDF? -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
On Feb 8, 2010, at 9:54 AM, Thadeus Burgess wrote: the problem with pdf is it is not searchable. Take a look at http://www.cubicweb.org/doc/en/index.html That is nice, its in a tutorial style format, but it is a wiki so it supports contextual searching via google. Its not all that special just a basic wiki where the pages are linked together in order. I'm not arguing for pdf (though of course it *can* be searchable); only that it's a better match for latex than html is. I do like having printable docs. Djangobook is nice. A problem with wiki.web2py is that the underlying wiki is limited, so it's relatively hard to edit, and the appearance of the output leaves a lot to be desired. (And no, I don't have time to work on it, though if web2py had a first-class wiki, I'd seriously consider using for my CMS needs.) -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
Re: [web2py] Re: for your info
I will document code that I contribute (such as sql reserved keywords check). I just need somebody to tell me where to put it. -Thadeus On Mon, Feb 8, 2010 at 12:11 PM, Jonathan Lundell jlund...@pobox.com wrote: On Feb 8, 2010, at 9:54 AM, Thadeus Burgess wrote: the problem with pdf is it is not searchable. Take a look at http://www.cubicweb.org/doc/en/index.html That is nice, its in a tutorial style format, but it is a wiki so it supports contextual searching via google. Its not all that special just a basic wiki where the pages are linked together in order. I'm not arguing for pdf (though of course it *can* be searchable); only that it's a better match for latex than html is. I do like having printable docs. Djangobook is nice. A problem with wiki.web2py is that the underlying wiki is limited, so it's relatively hard to edit, and the appearance of the output leaves a lot to be desired. (And no, I don't have time to work on it, though if web2py had a first-class wiki, I'd seriously consider using for my CMS needs.) -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
[web2py] Re: for your info
On Feb 9, 3:33 am, mdipierro mdipie...@cs.depaul.edu wrote: I am considering posting most of the book on line in HTML. This may be possible with a disclaimer about do not reproduce in print. The main issue is that the book is in latex and not easy to convert. this is fantastic news!! On Feb 9, 4:01 am, mdipierro mdipie...@cs.depaul.edu wrote: Lookin into that but I am not sure they work as good as they should. Moreover they are not reversible so changes in the wiki would not easily propagate into the latex book (which I consider the master documentation). An automated solution sounds difficult and time consuming. If you permitted, I could manually copy the PDF into a wiki or some other app. And I'm sure others would be willing to help too. -- You received this message because you are subscribed to the Google Groups web2py-users group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
