[Trac] Re: Trac wiki markup vs ReST
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Noah Kantrowitz skrev 04. juni 2009 22:13: Link to the last discussion on this (or at least one of the last) http://groups.google.com/group/trac-dev/browse_thread/thread/f79a1cbb894fe079/8e7d047d0c9fcf16 --Noah Thanks for the link -- didn't think to include it -- my questions re syntax was partly motivated by the points made in that thread. I'd be very interested to hear some more detailed views on ReST vs wiki markup - -- right now I see two points in favour of the wiki markup: 1) It's what a great number of trac users already know 2) Existing trac macros already integrated with the trac wiki processor. I'd be interested in hearing other points of view, especially against ReST, as I might be blind to any real deficiencies others find crippling ? Christian Boos mentioned the WikiEngine refactoring which will make it possible to generate structured output (e.g. Genshi events or docutils nodes, so that we could hijack the docutils writers for generating the static documentation) Has this taken place in trunk ? I think the consensus is that there are problems with managing documentation (exclusively) in the (any) wiki, due to difficulties with maintaining separate versions (0.11, 0.12 as well as multiple languages) -- but making it easier to do general transforms on the wiki content would be great either way. This is beginning to sound a bit like reinventing xml and xlst -- even though I personally think working with either of those tend to be painful. Christian further mentions: (Trac has) Much improved table markup (the reST table markup is unbearable). This would be: http://trac.edgewall.org/wiki/WikiFormatting#Tables vs: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables I agree the trac simple syntax is easier than the rest simple syntax, but I think unreadable is a bit strong ? It does illustrate a major difference between ReST and TracWiki-markup: Underline-markup vs side-by-side/inline-markup: ReST:Trac: Headline =Headline= = = =||Cell1||Cell2||Cell3|| Cell1 Cell2 Cell3||Cell4||Cell5||Cell6|| Cell4 Cell5 Cell6 = = = Mentioned in the thread on trac-dev is also the external dependencies problem -- and I agree that that needs to be taken into accounts. I'm not aware of any good way to ensure pdf-generation with included images that does not touch a wide range of dependencies, however. Also while a lot of the default ReST templates are horribly ugly -- the ability to seamlessly generate LaTeX is a great benefit -- this is of course something eg. docutils also would grant us. Best regards, - -- .---. Eirik Schwenke eirik.schwe...@nsd.uib.no ( NSD ) Harald Hårfagresgate 29Rom 150 '---' N-5007 Bergentlf: (555) 889 13 GPG-key at pgp.mit.edu Id 0x8AA3392C -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkotBeEACgkQxUW7FIqjOSwwzgCbB9INW793O1X+5jzG+dD/cire KI0AoIEOPqXQR5aDjtvp0zLZKorFAlRp =y77G -END PGP SIGNATURE- --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Noah Kantrowitz skrev 04. juni 2009 22:13: Link to the last discussion on this (or at least one of the last) http://groups.google.com/group/trac-dev/browse_thread/thread/f79a1cbb894fe079/8e7d047d0c9fcf16 --Noah Thanks for the link -- didn't think to include it -- my questions re syntax was partly motivated by the points made in that thread. I'd be very interested to hear some more detailed views on ReST vs wiki markup - -- right now I see two points in favour of the wiki markup: 1) It's what a great number of trac users already know 2) Existing trac macros already integrated with the trac wiki processor. I'd be interested in hearing other points of view, especially against ReST, as I might be blind to any real deficiencies others find crippling ? (this is all MHO, if that wasn't obvious). Its easier to write Trac wiki than ReST. I also find it more human readable. As a big fan of markdown languages, I was very enamored with ReST a few years ago. Now, I think its mostly awful, not that there aren't things about Trac wiki that I would change. Christian Boos mentioned the WikiEngine refactoring which will make it possible to generate structured output (e.g. Genshi events or docutils nodes, so that we could hijack the docutils writers for generating the static documentation) Has this taken place in trunk ? I think the consensus is that there are problems with managing documentation (exclusively) in the (any) wiki, due to difficulties with maintaining separate versions (0.11, 0.12 as well as multiple languages) -- but making it easier to do general transforms on the wiki content would be great either way. This is beginning to sound a bit like reinventing xml and xlst -- even though I personally think working with either of those tend to be painful. Christian further mentions: (Trac has) Much improved table markup (the reST table markup is unbearable). This would be: http://trac.edgewall.org/wiki/WikiFormatting#Tables vs: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables I agree the trac simple syntax is easier than the rest simple syntax, but I think unreadable is a bit strong ? It does illustrate a major difference between ReST and TracWiki-markup: Underline-markup vs side-by-side/inline-markup: ReST:Trac: Headline =Headline= = = =||Cell1||Cell2||Cell3|| Cell1 Cell2 Cell3||Cell4||Cell5||Cell6|| Cell4 Cell5 Cell6 = = = I've come to the conclusion than doing any sort of complicated table with any markdown language is just horrible. The whole reason to use a markdown language, vs WYSIWYG + HTML, is that it should be easy to read as text and easy to write. I've seen tables in both Trac wiki and ReST that are just boggling. Mentioned in the thread on trac-dev is also the external dependencies problem -- and I agree that that needs to be taken into accounts. I'm not aware of any good way to ensure pdf-generation with included images that does not touch a wide range of dependencies, however. Also while a lot of the default ReST templates are horribly ugly -- the ability to seamlessly generate LaTeX is a great benefit -- this is of course something eg. docutils also would grant us. I do agree that it would be nice to use something standard-ish, which is a plus for ReST. That being said, I would miss Trac wiki syntax greatly. The other alternative is to spin off Trac wiki (the markdown syntax, not the linking or macros or what not) into its own product. I'd probably use it. If other people would...I wouldn't want to guess. ReST has a long history and people are reluctant to change. Jeff Best regards, - -- .---. Eirik Schwenke eirik.schwe...@nsd.uib.no ( NSD ) Harald Hårfagresgate 29Rom 150 '---' N-5007 Bergentlf: (555) 889 13 GPG-key at pgp.mit.edu Id 0x8AA3392C -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkotBeEACgkQxUW7FIqjOSwwzgCbB9INW793O1X+5jzG+dD/cire KI0AoIEOPqXQR5aDjtvp0zLZKorFAlRp =y77G -END PGP SIGNATURE- --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Jeff Hammel skrev 08. juni 2009 14:46: On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote: Noah Kantrowitz skrev 04. juni 2009 22:13: [ Note somehow icedove chokes on mutt's quoting, apologies if the indendation/quotemarkers are still wrong. Pretty sure this is a problem with icedove not mutt --- anyway:] I'd be interested in hearing other points of view, especially against ReST, as I might be blind to any real deficiencies others find crippling ? (this is all MHO, if that wasn't obvious). Indeed, I might have made that explicit for my thoughts as well --- All IMHO :-) Its easier to write Trac wiki than ReST. I also find it more human readable. As a big fan of markdown languages, I was very enamored with ReST a few years ago. Now, I think its mostly awful, not that there aren't things about Trac wiki that I would change. Interesting, maybe I'm at the point you were a few years ago. One great advantage I failed to mention in favour of TracWikiMarkup, is ofcourse wiki links -- it's perhaps one of the biggest failings of ReST. On the other hand I've come to enjoy being able to have links/footnotes in one place in the text, and link to them like: [LinkToNamedFootnote]_. It does depend a bit on what one is writing. I often find myself moving text around, and parts of ReST syntax is better for that (section linking, footnotes/citations), and part of trac-syntax is better (better support for auto numbered lists). (...) I've come to the conclusion than doing any sort of complicated table with any markdown language is just horrible. The whole reason to use a markdown language, vs WYSIWYG + HTML, is that it should be easy to read as text and easy to write. I've seen tables in both Trac wiki and ReST that are just boggling. Indeed. While I have little love for text editors, there's a definitive need for rich content, that can accompany (hyper)text. I feel csv-tables is a possible compromise -- but any table beyond the simplest ones needs a rich editor IMHO. (...) I do agree that it would be nice to use something standard-ish, which is a plus for ReST. That being said, I would miss Trac wiki syntax greatly. The other alternative is to spin off Trac wiki (the markdown syntax, not the linking or macros or what not) into its own product. I'd probably use it. If other people would...I wouldn't want to guess. ReST has a long history and people are reluctant to change. One of the benefits I see with ReST is that it seems to be solid design, with great room to improve. It merges a lot of good ideas from Markdown/Structured Text/LaTeX with reasonable readability. I'd still like to see some example of ReST vs Trac that you feel illustrates the readability issues. We'll probably still view them differently though ;-) Best regards, - -- .---. Eirik Schwenke eirik.schwe...@nsd.uib.no ( NSD ) Harald Hårfagresgate 29Rom 150 '---' N-5007 Bergentlf: (555) 889 13 GPG-key at pgp.mit.edu Id 0x8AA3392C -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkotDMUACgkQxUW7FIqjOSzS9gCgjn8V5KUGKLQDC0NM/6LCqH4y dvEAnRG+4Rgdn+qJDaT6xl/uY98aHRws =VEJK -END PGP SIGNATURE- --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
On Mon, Jun 08, 2009 at 03:06:13PM +0200, Eirik Schwenke wrote: snip/ Its easier to write Trac wiki than ReST. I also find it more human readable. As a big fan of markdown languages, I was very enamored with ReST a few years ago. Now, I think its mostly awful, not that there aren't things about Trac wiki that I would change. Interesting, maybe I'm at the point you were a few years ago. One great advantage I failed to mention in favour of TracWikiMarkup, is ofcourse wiki links -- it's perhaps one of the biggest failings of ReST. Just as a point of clarity, while wiki has come to mean (markdown formatting) + (linking syntax), I think of the two quite differently. Linking + macros could (and IMHO should) be done as post-processing regardless of what the underlying markdown formatting is. Jeff --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
On Mon, Jun 8, 2009 at 7:46 AM, Jeff Hammeljham...@openplans.org wrote: On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Noah Kantrowitz skrev 04. juni 2009 22:13: Link to the last discussion on this (or at least one of the last) http://groups.google.com/group/trac-dev/browse_thread/thread/f79a1cbb894fe079/8e7d047d0c9fcf16 --Noah Thanks for the link -- didn't think to include it -- my questions re syntax was partly motivated by the points made in that thread. I'd be very interested to hear some more detailed views on ReST vs wiki markup - -- right now I see two points in favour of the wiki markup: 1) It's what a great number of trac users already know 2) Existing trac macros already integrated with the trac wiki processor. (Besides) IMHO I also like Trac syntax because : - It's extensible (macros + processors) - It's more close to what humans have in mind when they write something (yes ! the users mental model do care :)) e.g. TracLinks - Productivity (one line generates one million :P) - The only thing I like about ReST is the way it handles links. I mean, I write the link target just once and thereinafter I dont need to repeat the link URL anymore. OTOH using Trac wiki syntax I need to write [url text] everywhere I need to insert a link to some location. That's the only thing that makes me waste my time (and therefore I'm not comfortable with ...) but I can live with that . BTW this is also why links are frequently missing while using ReST, but also why its relatively simple to fix it IMHO . but all this can also raise a number of incompatibilities | «dont know what to do» situations for transformations (e.g. to obtain HTML, PDF, ...) | every body is doing it a different way. So that's hardly against standards, but it is really powerful. In fact I even use Trac wiki syntax to write my blog posts (Blogger). In the end, (in this case) the only thing that matters is HTML ;) Christian further mentions: (Trac has) Much improved table markup (the reST table markup is unbearable). [...] I agree the trac simple syntax is easier than the rest simple syntax, but I think unreadable is a bit strong ? [...] I've come to the conclusion than doing any sort of complicated table with any markdown language is just horrible. Oh yes ! you 'r right. -- Regards, Olemis. Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article: ¡ Bienvenido OpenSolaris 2009.06 ! - http://feedproxy.google.com/~r/simelo-es/~3/UY8IF3M3Alw/bienvenido-opensolaris-200906.html --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
On Mon, Jun 8, 2009 at 8:46 AM, Jeff Hammel jham...@openplans.org wrote: I do agree that it would be nice to use something standard-ish, which is a plus for ReST. That being said, I would miss Trac wiki syntax greatly. The other alternative is to spin off Trac wiki (the markdown syntax, not the linking or macros or what not) into its own product. I'd probably use it. If other people would...I wouldn't want to guess. ReST has a long history and people are reluctant to change. +1. Trac wiki syntax is the first and only wiki-like syntax that I've been able to remember how to use. :) In fact I actually compose almost all my documents, even outside of the Trac environment, in Trac wiki syntax at least initially -- emails, notes to myself, first drafts of papers ... so I'm sure I'd use such a product too. egj --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
Eirik Schwenke wrote:
Christian Boos mentioned the WikiEngine refactoring which will make it
possible to generate structured output (e.g. Genshi events or docutils
nodes, so that we could hijack the docutils writers for generating the
static documentation)
Has this taken place in trunk ?
No, this is not yet started (0.13?).
I think the consensus is that there are
problems with managing documentation (exclusively) in the (any) wiki,
due to difficulties with maintaining separate versions (0.11, 0.12 as
well as multiple languages) -- but making it easier to do general
transforms on the wiki content would be great either way.
This is beginning to sound a bit like reinventing xml and xlst -- even
though I personally think working with either of those tend to be painful.
Christian further mentions: (Trac has) Much improved table markup (the
reST table markup is unbearable).
The (Trac has) shortcut is quite misleading. I never said that the
current Trac table markup is any better than the reStructuredText one...
What I actually said was:
...
I don't see why we should stop improving Trac abilities in this domain
(producing documentation).
Here are some of the relevant *work items*:
- the WikiEngine refactoring which will make it possible to generate
structured output (e.g. Genshi events or docutils nodes, so that we
could hijack the docutils writers for generating the static documentation)
- Section editing (#1024) so that big pages like the FAQ could be
easily edited
- *Much improved table markup* (the reST table markup is unbearable)
- Lots of possible minor improvements to the syntax and rendering, in
order to make writing documentation a more enjoyable experience (i.e. we
have full control over the feature set)
...
(from http://groups.google.com/group/trac-dev/msg/4d2ae7546c67fba4?hl=en)
... so this was instead recognizing the weaknesses of both markups when
it comes to tables.
= = =||Cell1||Cell2||Cell3||
Cell1 Cell2 Cell3||Cell4||Cell5||Cell6||
Cell4 Cell5 Cell6
= = =
The reStructuredText markup is easier to read, but a pain to write (the
cells have to line up). The current Trac wiki is less trouble to write,
but harder to read in the wiki source.
There are several improvements I'd like to do in the specific case of
tables. One is to make it possible to use a wiki processor for big
cells, e.g.
{{{
#!td
any multiline wiki markup here ...
(much like #!div)
}}}
Also, I just took the occasion of this mail to dump some some Wiki
syntax enhancement ideas in
http://trac.edgewall.org/wiki/TracDev/Proposals/AdvancedWikiFormatting
and there are some more ideas related to tables there.
-- Christian
--~--~-~--~~~---~--~~
You received this message because you are subscribed to the Google Groups Trac
Users group.
To post to this group, send email to trac-users@googlegroups.com
To unsubscribe from this group, send email to
trac-users+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/trac-users?hl=en
-~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
On Mon, Jun 8, 2009 at 8:51 AM, Eirik Schwenkeeirik.schwe...@nsd.uib.no wrote: Olemis Lang skrev 08. juni 2009 15:24: On Mon, Jun 8, 2009 at 7:46 AM, Jeff Hammeljham...@openplans.org wrote: On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote: (...) In fact I even use Trac wiki syntax to write my blog posts (Blogger). In the end, (in this case) the only thing that matters is HTML ;) Interesting. Those of you that use trac markup so extensively -- what part of the markup do you actually use? Are you mainly reffering to headers and linking, or also the various format (non structural, non semantic) stuff ? Well I'll tell you about my blog (other people could tell you about other things too ;) and mainly about a specific entry [1]_ - I use Dojo ... - I use Trac CSS ... - I use div macro for the collapsible panel stuff. The benefits are - Users only read a summary of the article - If they want to they read the full article - without navigating to a different page - I'm focused on writing my article and not on seting up the html + js code needed for that. - *DONT LIKE BLOGGER EDITOR*. Even if there's a lot of effort in there, it doesnt help me much (too many clicks or otherwise pure HTML). Wiki is just fast great ... - I use syntax highlighting (processors) for code snippets. - I dont use ImageMacro because I dont know URLs to images beforehand, but I could ;) - I use TracLinks for definitions and more - I use iGoogleGadget macro (TracGViz plugin [2]_) for including Gadgets in posts. (not in the article I mention :-/) - I plan to implement more specific stuff to do many other things fast as hell. - Header linking of course ;) - The `span + icon` thing for links (fast as hell as compared with plain HTML) ... but these days I've not much time :( and all this is tremendously non-std, but is useful that's what matters for me . Just curios. Dont if it helps and if it's related with the main subject; but u just asked for it ;) BE CAREFUL ! If you use all these ideas you'll be violating my copyrights ... c'u in court ( XD .. [1] PyUMLGraph : Otra manera de contemplar el código (http://simelo-es.blogspot.com/2009/06/pyumlgraph-mirando-al-codigo-de-python.html) .. [2] TracGViz plugin (https://opensvn.csie.org/traccgi/swlcu/wiki/En/Devel/TracGViz) -- Regards, Olemis. Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article: ¡ Bienvenido OpenSolaris 2009.06 ! - http://feedproxy.google.com/~r/simelo-es/~3/UY8IF3M3Alw/bienvenido-opensolaris-200906.html --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
Olemis, I tried to look at your blog, but I think your formatter is broken or something. Everything is coming out in some foreign language, I think Spanish or something. Made it very hard to read and understand. Perhaps you should look into using a different markup scheme? Xenophobically yours, Ariel Olemis Lang wrote: On Mon, Jun 8, 2009 at 8:51 AM, Eirik Schwenkeeirik.schwe...@nsd.uib.no wrote: Olemis Lang skrev 08. juni 2009 15:24: On Mon, Jun 8, 2009 at 7:46 AM, Jeff Hammeljham...@openplans.org wrote: On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote: (...) In fact I even use Trac wiki syntax to write my blog posts (Blogger). In the end, (in this case) the only thing that matters is HTML ;) Interesting. Those of you that use trac markup so extensively -- what part of the markup do you actually use? Are you mainly reffering to headers and linking, or also the various format (non structural, non semantic) stuff ? Well I'll tell you about my blog (other people could tell you about other things too ;) and mainly about a specific entry [1]_ - I use Dojo ... - I use Trac CSS ... - I use div macro for the collapsible panel stuff. The benefits are - Users only read a summary of the article - If they want to they read the full article - without navigating to a different page - I'm focused on writing my article and not on seting up the html + js code needed for that. - *DONT LIKE BLOGGER EDITOR*. Even if there's a lot of effort in there, it doesnt help me much (too many clicks or otherwise pure HTML). Wiki is just fast great ... - I use syntax highlighting (processors) for code snippets. - I dont use ImageMacro because I dont know URLs to images beforehand, but I could ;) - I use TracLinks for definitions and more - I use iGoogleGadget macro (TracGViz plugin [2]_) for including Gadgets in posts. (not in the article I mention :-/) - I plan to implement more specific stuff to do many other things fast as hell. - Header linking of course ;) - The `span + icon` thing for links (fast as hell as compared with plain HTML) ... but these days I've not much time :( and all this is tremendously non-std, but is useful that's what matters for me . Just curios. Dont if it helps and if it's related with the main subject; but u just asked for it ;) BE CAREFUL ! If you use all these ideas you'll be violating my copyrights ... c'u in court ( XD .. [1] PyUMLGraph : Otra manera de contemplar el código (http://simelo-es.blogspot.com/2009/06/pyumlgraph-mirando-al-codigo-de-python.html) .. [2] TracGViz plugin (https://opensvn.csie.org/traccgi/swlcu/wiki/En/Devel/TracGViz) -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ Ariel I Balter, Ph.D. Postdoc Biological Monitoring/Modeling Fundamental and Computational Sciences Directorate Pacific Northwest National Laboratory Mail: PO Box 999, MS P7-58,Richland, WA 99352 Shipping: 790 6th Street, MS P7-58, Richland, WA 99354 Tel: 509-376-7605 Cell: 509-713-0087 ariel.bal...@pnl.gov www.arielbalter.com www.pnl.gov --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~--- begin:vcard fn:Ariel Balter, PhD n:Balter;Ariel email;internet:abal...@indiana.edu tel;home:812-332-2721 tel;cell:812-219-4558 x-mozilla-html:TRUE url:http://arielbalter.com version:2.1 end:vcard
[Trac] Re: Trac wiki markup vs ReST
A little bit OT, oops ! On Mon, Jun 8, 2009 at 11:22 AM, Ariel Balterar...@arielbalter.com wrote: Olemis, I tried to look at your blog, but I think your formatter is broken or something. Everything is coming out in some foreign language, I think Spanish or something. Dont get it, it's in Spanish - I love spanish, french english :) I've not learned yet ;) -. I thought that wouldnt be a problem to depict the main idea (considering the question ;o). I wanted to start a separate blog for each language but I've no time for that, so I included Google Translate gadget in the top left corner . I'd really like to have more time, but I dont ... désolé:-/ Made it very hard to read and understand. Perhaps you should look into using a different markup scheme? Dont get it ... what for ? Any suggestions will be welcomed : but I personally think they should be sent to me directly unless they are related to trac ;) Xenophobically yours, Ariel Oh wow ! -- Regards, Olemis. Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article: PyUMLGraph : Otra manera de contemplar el código - http://feedproxy.google.com/~r/simelo-es/~3/lLsxDz4Rkgc/pyumlgraph-mirando-al-codigo-de-python.html --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
Interesting thread and also interesting to see how much everyone likes Trac wiki syntax. I will add my $0.02 US and also take as IMHO: While I agree that simple text and things like TODO and instruction related documentation are relatively easy to do in markdown, I have (and it may be due to my lack of experience with) had difficulties with almost all mark down languages when it comes to technical documentation. If it is simply a question of Trac wiki or ReST, then I don't really have a strong preference, but I would lean toward Trac wiki (as much as I like what I have reviewed and researched with regard to Rest) as then all my work with/around Trac would use a consistent format; however... At the risk of (a strict interpretation of the thread) taking us off topic, I would also suggest that if we plan to leverage version controlled documentation for various releases that some of the limitations (tables being a big one) of markdown will become more significant and for that reason I would suggest at least considering another richer format. As mentioned previously, I have settled on just such a format for the bulk of the content I develop and thankfully, the other OSS project I am working on also supports the same format for their documentation. The advantages of these are their (obviously) richer format and (at least based on my limited knowledge of Trac wiki and ReST) ability to be easily transformed to other format and supported by a significant number of tools. The is obviously more complex, but there are tools available to help assist with the development of the documentation (which is another big advantage of a standard mark up)... Lance Roger Oberholtzer wrote: On Mon, 2009-06-08 at 14:36 +0200, Eirik Schwenke wrote: Christian further mentions: (Trac has) Much improved table markup (the reST table markup is unbearable). This would be: http://trac.edgewall.org/wiki/WikiFormatting#Tables vs: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables I do miss the ability to span columns and rows. Especially columns. If Trac had this, I would not need any change to the table syntax. I confess, I use the WYSIWYG trac plugin to manipulate tables. I get some pretty hefty ones, and adding a column can be a real PITA. Even if I cut/paste from my favorite vi. -- Roger Oberholtzer --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1
Christian Boos skrev 08. juni 2009 16:26:
Eirik Schwenke wrote:
Christian Boos mentioned the WikiEngine refactoring which will make it
possible to generate structured output (e.g. Genshi events or docutils
nodes, so that we could hijack the docutils writers for generating the
static documentation)
Has this taken place in trunk ?
No, this is not yet started (0.13?).
Ok, thanks for the update.
(...)
Christian further mentions: (Trac has) Much improved table markup (the
reST table markup is unbearable).
The (Trac has) shortcut is quite misleading. I never said that the
current Trac table markup is any better than the reStructuredText one...
What I actually said was:
...
I don't see why we should stop improving Trac abilities in this domain
(producing documentation).
Here are some of the relevant *work items*:
- the WikiEngine refactoring which will make it possible to generate
structured output (e.g. Genshi events or docutils nodes, so that we
could hijack the docutils writers for generating the static documentation)
- Section editing (#1024) so that big pages like the FAQ could be
easily edited
- *Much improved table markup* (the reST table markup is unbearable)
- Lots of possible minor improvements to the syntax and rendering, in
order to make writing documentation a more enjoyable experience (i.e. we
have full control over the feature set)
...
(from http://groups.google.com/group/trac-dev/msg/4d2ae7546c67fba4?hl=en)
... so this was instead recognizing the weaknesses of both markups when
it comes to tables.
Ah, my apologies. I must've read through that thread at too high
speed... Not sure how I managed to misread you so completely.
If it helps, I did find it very strange of you to make such an
out-of-character seemingly nonsensical comment ;-)
= = =||Cell1||Cell2||Cell3||
Cell1 Cell2 Cell3||Cell4||Cell5||Cell6||
Cell4 Cell5 Cell6
= = =
The reStructuredText markup is easier to read, but a pain to write (the
cells have to line up). The current Trac wiki is less trouble to write,
but harder to read in the wiki source.
Agreed. As mentioned in this thread already, there are (currently) no
*good* alternatives -- personally I think the trac syntax has better
potential here -- but i'd like to see table headers.
There are several improvements I'd like to do in the specific case of
tables. One is to make it possible to use a wiki processor for big
cells, e.g.
{{{
#!td
any multiline wiki markup here ...
(much like #!div)
}}}
Hm... not sure if I agree
alternative-syntax-x-which-is-just-a-wrapper-for-html is better than just:
{{{
#!html
table
(...)
}}}
Both html and LaTeX have powerful (but IMNHO painful to read/write)
table markup.
I think that some kind of csv-table might be better -- in general I lean
quite strongly towards What-You-Mean vs What-You-Get syntax for markup.
This is somewhat related to the render-as-anything functionality which I
think is quite essential both for wiki and documentation.
(Eg: pdf/ps w/inline rich content such as vector/bitmap images, graphs,
tables, links; slideshows (ppt or s5), html, infotex etc).
Also, I just took the occasion of this mail to dump some some Wiki
syntax enhancement ideas in
http://trac.edgewall.org/wiki/TracDev/Proposals/AdvancedWikiFormatting
and there are some more ideas related to tables there.
Many interesting points.
I still think there is some disagreement (or non-explicitness) whether
wiki-markup shows meaning or appearance. Personally I prefer to mark up
meaning, even if that will always be abused for visual gain by
creative users.
Perhaps a strict, not-quite-so-friendly wiki markup coupled with a
simple-yet-powerful rich html/js-editor might be a good idea ?
That way, those that prefer to use eg It'sAllText-plugin with vim and
syntax-highlighting should be able to stay happy, as well as the more
casual users using only the web front-end ?
- -e
- --
.---. Eirik Schwenke eirik.schwe...@nsd.uib.no
( NSD ) Harald Hårfagresgate 29Rom 150
'---' N-5007 Bergentlf: (555) 889 13
GPG-key at pgp.mit.edu Id 0x8AA3392C
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
iEYEARECAAYFAkotTfsACgkQxUW7FIqjOSxa3QCfYbOQ3vNHRysAMWtnesobrG3N
xdsAni6oh58zSUenHXff+iWywYcyGyIp
=RrhG
-END PGP SIGNATURE-
--~--~-~--~~~---~--~~
You received this message because you are subscribed to the Google Groups Trac
Users group.
To post to this group, send email to trac-users@googlegroups.com
To unsubscribe from this group, send email to
trac-users+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/trac-users?hl=en
-~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
FYI, you link to your copyright on your web site points to a non- existent file in your source control browser. I'd like to read it. I was very interesting in your GraphViz plugin, but based on your comments i am not scared off a bit, depending on what you copyright actually says. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
On Mon, Jun 8, 2009 at 3:37 PM, yoheebyoh...@gmail.com wrote: FYI, you link to your copyright on your web site points to a non- existent file in your source control browser. I'd like to read it. I was very interesting in your GraphViz plugin, but based on your comments i am not scared off a bit, depending on what you copyright actually says. If you 'r talking about TracGViz plugin then it is distributed under the Apache License and distributes gviz_api module under the same terms (and under permission from Google ;). All this is documented in COPYRIGHT and NOTICE files included in both source and EGG packages . TracPyTpp is distributed under the same terms of the original implementation PyDotOrg theme which is BSD licence ... AFAICR ... (Yes, I dont like interactions between Licences, specially when I've just done 5% of the whole ;) So dont worry ... was a little JOKE ! (I even wrote a smiley like this XD, didnt I? ) If not talking about TracGViz, sorry I thought I should reply, but it was not clear in your previos message -and TracGViz is not related to GraphViz- ;) Dont worry : All that is plain FOSS ... just use it :) PS: If you want a comprehensive understanding of all terms and so on, please also read the Terms of Service for Google Visualization API and iGoogle Gadgets. They are SaaS products provided by Google. Good luck ! -- Regards, Olemis. Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article: ¡ Bienvenido OpenSolaris 2009.06 ! - http://feedproxy.google.com/~r/simelo-es/~3/UY8IF3M3Alw/bienvenido-opensolaris-200906.html --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
[Trac] Re: Trac wiki markup vs ReST
Eirik Schwenke wrote:
Christian Boos skrev 08. juni 2009 16:26:
There are several improvements I'd like to do in the specific case of
tables. One is to make it possible to use a wiki processor for big
cells, e.g.
{{{
#!td
any multiline wiki markup here ...
(much like #!div)
}}}
Hm... not sure if I agree
alternative-syntax-x-which-is-just-a-wrapper-for-html is better than just:
{{{
#!html
table
(...)
}}}
It's not at all comparable. Within an !html block, you can't use any
Wiki markup.
And since 0.11, you can't use the older trick of starting a
table/row/cell in one !html block, close it and interleave some wiki
markup, open a another !html block for closing the cell/row/table, etc.
Starting with 0.11, the HTML markup in an !html block has to be
self-contained (see http://trac.edgewall.org/wiki/WikiHtml for details).
-- Christian
--~--~-~--~~~---~--~~
You received this message because you are subscribed to the Google Groups Trac
Users group.
To post to this group, send email to trac-users@googlegroups.com
To unsubscribe from this group, send email to
trac-users+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/trac-users?hl=en
-~--~~~~--~~--~--~---
