Trac Recipies
abalter
There is a ton of great information in this email list and forums and
out there on the web. I think it would be great to take a sort of
"best of" of the actual solutions and organize them into a set of
recipes such as "You want to do XXX...Do this:".
Not surprisingly, I thing the best way to build this recipe book is
with a Trac site. The first thing I would need would be a place to
host it. Perhaps the folks that run Trac-hacks would be willing to
give me some space. Or, perhaps edgewall.com. I'm open to
suggestions.
I'd love to hear feedback on this idea.
Thanks, Ariel
Noah Kantrowitz
--Noah
Ariel Balter
-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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....@pnl.gov www.arielbalter.com www.pnl.gov
Chris Nelson
> ... Perhaps the folks that run Trac-hacks would be willing to
> give me some space. ...
1. Register @ TH
2. Create a wiki page
Jeff Hammel
Of course, the other side of things is how to use Trac to get the most bang for your buck. And yeah, I think there's a lot of expertise out there and some really good ways to use Trac and to think about Trac that would be nice to see collected.
Jeff
Dan Winslow
So do I. Track hacks is a OK place to get plugins from, but not information on how to do things. In general there is a crippling lack of information all across the web about TRAC. I have spent two weeks trying to understand various aspects of TRAC, and I am just now starting to get a vague idea. I am not a python programmer, nor do I have any wish to become one. All of the documentation I can find about a specific subject is usually only a few terse sentences, maybe a *very* short example, and then they all trail off with ‘ .. and of course, you can always write a plugin to do anything more.’. I don’t want to write plug-ins. I don’t want to have to read through bunch of alien-looking code to try and figure out what it means. I’m not faulting the developers in particular, they’ve done a fine job and it’s a huge amount of work to maintain decent docs.
I was so frustrated that I tried to get management to let me write my own system, but they declined. I think a collection point for trac recipies would be a greta idea.
Noah Kantrowitz
If people want to write up good docs please do so. You can see the new docs (which have kind of stagnated since I haven't been porting the existing docs over very much) at http://trac.edgewall.org/browser/sandbox/newhelp/doc
They are done using Sphinx, so you might want to look up ReST too.
--Noah
Lance Hendrix
topics) that you especially feel would be important/critical/useful to
develop (what were you unable to find documentation about). IMHO one of
the biggest issues facing the adoption of OSS is the lack of
documentation and as a result one of my major objectives to support the
OSS effort is to attempt to provide or at least assist with the
development of (I am capable of at generating content quickly, I'll let
someone else be the judge of it's usefulness) documentation; however, in
order to be most useful, I think the effort should be driven by the
community (as to what to develop).
In short, while you could develop the documentation yourself (as has
been suggested), there is also the option of assisting or collaborating
with someone (me?) to help improve the documentation.
Anyone else with any documentation requests would also be welcome. (I
know, be careful what you wish for...)
Lance
Dan Winslow wrote:
>
> So do I. Track hacks is a OK place to get plugins from, but not
> information on how to do things. In general there is a crippling lack
> of information all across the web about TRAC. I have spent two weeks
> trying to understand various aspects of TRAC, and I am just now
> starting to get a vague idea. I am not a python programmer, nor do I
> have any wish to become one. All of the documentation I can find about
> a specific subject is usually only a few terse sentences, maybe a
> want to write plug-ins. I don’t want to have to read through bunch of
> alien-looking code to try and figure out what it means. I’m not
> faulting the developers in particular, they’ve done a fine job and
> it’s a huge amount of work to maintain decent docs.
>
> I was so frustrated that I tried to get management to let me write my
> own system, but they declined. I think a collection point for trac
> recipies would be a greta idea.
>
>
> *From:* trac-...@googlegroups.com
> [mailto:trac-...@googlegroups.com] *On Behalf Of *Ariel Balter
> *Sent:* Wednesday, June 03, 2009 12:59 PM
> *To:* trac-...@googlegroups.com
> *Subject:* [Trac] Re: Trac Recipies
> www.arielbalter.com <http://www.arielbalter.com>
> www.pnl.gov <http://www.pnl.gov>
>
>
>
> >
>
Lance Hendrix
your ideas is great. I'll leave the discussions of where to others, but
let me know if you need any assistance with developing the documentation
or if you just want someone to review it.
Lance
Chris Nelson
> In line with your note, perhaps you could suggest a few items (or a
> few topics) that you especially feel would be
important/critical/useful
> to develop (what were you unable to find documentation about). IMHO
one
> of the biggest issues facing the adoption of OSS is the lack of
> documentation and as a result one of my major objectives to support
> the OSS effort is to attempt to provide or at least assist with the
> development of (I am capable of at generating content quickly, I'll
> let someone else be the judge of it's usefulness) documentation;
however,
> in order to be most useful, I think the effort should be driven by the
> community (as to what to develop).
>
> In short, while you could develop the documentation yourself (as has
> been suggested), there is also the option of assisting or
> collaborating with someone (me?) to help improve the documentation.
>
> Anyone else with any documentation requests would also be welcome. (I
> know, be careful what you wish for...)
I have trouble getting started generating content and I'm no Trac
expert. I am, however, an good editor (and married to an excellent
editor) and would try to clean up drafts others may submit.
Dan Winslow
workflow specification in the trac.ini was. I kept thinking that the
values in there referred to some kind of internal call or constructs,
when in reality they really are just abstract names that can be made up
at will. (I did finally notice two lines in the wiki page about workflow
that said as much ).
In general, if I had been aware of the way that the Python config reader
works, I probably would have come to that conclusion much sooner. Being
totally ignorant of python, I had no idea what to expect and everything
looked like code to me at that point.
So, some topic suggestions would be :
1. Detailed explanantions about workflow and how to set it up to meet
various 'best-of' practices. Now that I have some idea of what I am
doing I am setting one up for us to use, and I'd be happy to post an
annotated copy of it somewhere.
Here's some things I'd still like to know about (thread hijack warning):
1. How to validate fields pre-commit and block the commit with a fail
warning. I know about the ticketvalidator plugin but so far it doesn't
seem to work, and even if it did it doesn't seem to be able to validate
field content, just whether or not it has something in it. What we need
is either way more field types or a validation callout of some sort that
we can hook to. A SQL query tag comes to mind.
2. How to restrict fields from display/and or edit based on some
condition. This might be able to be done via a user-specifiable SQL
query tag on the field returning true or false. The query gets run, if
its true the field gets displayed, if its false it doesn't. Or something
like that.
3. How to modify workflow to select different states depending on
condition. Again, if I could specify a query that returned the status I
wanted, instead of having to specify it by name in the workflow, things
would be a lot more flexible.
-----Original Message-----
From: trac-...@googlegroups.com [mailto:trac-...@googlegroups.com]
On Behalf Of Lance Hendrix
Sent: Wednesday, June 03, 2009 1:28 PM
To: trac-...@googlegroups.com
Subject: [Trac] Re: Trac Recipies
Remy Blank
> In line with your note, perhaps you could suggest a few items (or a few
> topics) that you especially feel would be important/critical/useful to
> develop (what were you unable to find documentation about).
I have started a page to collect documentation topics:
http://trac.edgewall.org/wiki/SeaChange/DocumentationRequests
> one of my major objectives to support the
> OSS effort is to attempt to provide or at least assist with the
> development of (I am capable of at generating content quickly, I'll let
> someone else be the judge of it's usefulness) documentation;
We seem to have at least two people who are willing to spend some time
writing documentation for Trac. So here's your chance: add relevant
topics to the page above, vote for the topics you would find most
useful, and maybe, just maybe, this could be the starting point of a
vastly improved Trac documentation!
-- Remy
Dan Winslow
the trac wiki situation...are you suggesting we enter tickets, or are we
supposed to edit the wiki page directly?
If we are supposed to enter tickets, I am not sure exactly how that
would equate to actual documentation. Or are you suggesting that we use
the tickets to specify what we'd like to see? And then we write
documentation somewhere? Or somebody does?
The whole thing seems to remain slightly opaque to me..its probably due
to my own ignorance of course, but there you have it.
-----Original Message-----
From: trac-...@googlegroups.com [mailto:trac-...@googlegroups.com]
On Behalf Of Remy Blank
Sent: Wednesday, June 03, 2009 2:30 PM
To: trac-...@googlegroups.com
Subject: [Trac] Re: Trac Recipies
Ariel Balter
http://trac.edgewall.org/wiki/SeaChange
;~}
I'm just hanging out until a few more responses come in. It appears that there are already some emerging projects that address some/most of what I was after. I'll look over the responses in a bit and propose something....
Thanks, Ariel
-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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....@pnl.gov
Noah Kantrowitz
> From: trac-...@googlegroups.com [mailto:trac-...@googlegroups.com]
> On Behalf Of Dan Winslow
> Sent: Wednesday, June 03, 2009 12:41 PM
> To: trac-...@googlegroups.com
> Subject: [Trac] Re: Trac Recipies
>
>
> with
> the trac wiki situation...are you suggesting we enter tickets, or are
> we
> supposed to edit the wiki page directly?
>
> If we are supposed to enter tickets, I am not sure exactly how that
> would equate to actual documentation. Or are you suggesting that we use
> the tickets to specify what we'd like to see? And then we write
> documentation somewhere? Or somebody does?
We take what people can offer. If you want to just edit the page with a
suggestion, thats fine. If you want to write up a new page for the Sphinx
docs (or a patch for something already there) and file a ticket, thats great
too :-)
--Noah
Remy Blank
> Lance, that seems like a good place to start, but I am not familiar with
> the trac wiki situation...are you suggesting we enter tickets, or are we
> supposed to edit the wiki page directly?
I was thinking about the following two-step process, but I may have been
unclear:
- People who are missing documentation on some topic edit the mentioned
wiki page, and add their topic to the table. People can also vote for a
topic by incrementing the vote count in the table.
- People who want to contribute documentation look at the wiki page,
and decide on the topic they want to cover, based on a combination of
vote count and their personal interest. They start a new wiki page for
their topic on trac.edgewall.org, and ask for feedback here and/or on
trac-dev.
I have removed the note about opening a ticket, as feedback is probably
much easier on the mailing lists than in a ticket. Sorry about the
confusion.
-- Remy
Noah Kantrowitz
> From: trac-...@googlegroups.com [mailto:trac-...@googlegroups.com]
> On Behalf Of Remy Blank
> Sent: Wednesday, June 03, 2009 1:02 PM
> To: trac-...@googlegroups.com
> Subject: [Trac] Re: Trac Recipies
>
> > Lance, that seems like a good place to start, but I am not familiar
> > with the trac wiki situation...are you suggesting we enter tickets,
> or
> > are we supposed to edit the wiki page directly?
>
> I was thinking about the following two-step process, but I may have
> been
> unclear:
>
> - People who are missing documentation on some topic edit the
> mentioned wiki page, and add their topic to the table. People can also
> vote for a topic by incrementing the vote count in the table.
>
> - People who want to contribute documentation look at the wiki page,
> and decide on the topic they want to cover, based on a combination of
> vote count and their personal interest. They start a new wiki page for
> their topic on trac.edgewall.org, and ask for feedback here and/or on
> trac-dev.
>
Please do not write new docs in the wiki. We are trying to move away from
using the wiki for formal documentation and use it for more
discussion-oriented applications. If you want to sketch out new docs in the
wiki thats fine, but be sure to use the ReST processor so we can easily move
them into the sphinx stuff.
--Noah
Remy Blank
> Please do not write new docs in the wiki. We are trying to move away from
> using the wiki for formal documentation and use it for more
> discussion-oriented applications.
Speaking of the newhelp branch, does it correctly represent the current
state of the docs, or do you have more uncommitted docs up your sleeve?
> If you want to sketch out new docs in the
> wiki thats fine, but be sure to use the ReST processor so we can easily move
> them into the sphinx stuff.
That may be a high barrier to entry for some people. At least, if we
have the content in the wiki, it will be immediately useful to users,
and we can still transform it once the newhelp branch is merged.
-- Remy
yoheeb
"standardized" a bit for sub-wiki pages and sub-sub-wiki pages.
I.e. SeaOfChange:
blah blah....
although, sure seems to me like a LOT of this information is ACTUALLY
on the trac site, or trac hacks, people just don't like to look. The
originator of this thread list many VERY specific things they want to
know how to do, some of which are not possible the way they want to do
it. These types of things are perfect for asking the newsgroup. Not
picking on him, but for the sake of example: Wishlist item 1. The
ticket validator plugin works fine. yes it is limited in that it only
validates against empty. There are 2 other plugins on track hacks
that might meet the needs BlackMagicTicketTweaks, or the still in
infancy TicketSubmitPolicy (which, pretty much doesn't work quite
right). The point, after searching the haks a bit, might not quite of
had enough info, and the right place would of been the usergroup for
what amounts to special behavior. A more organized set of docs would
of only led you to the conclusion, base track doesn't support it,
these plugins might. You probably have to actually code something
custom, for a custom behavior.
The second wishlist item: Not possible currently. A quick search on
the user group would of (or the request a hacks, or the track haks
ticket list) would of found a few tickets have been requested to
consider how to implement this behavior in the future.....
And the final one, in this case. TypedTicketWorkflow. not hard to
find, does what you want. In any of these cases, A.) searching the
usergroup, then B.) asking the question if not found in A. would of
been likely, the best way to get to these tools, and some tips/answers
because they are really special cases.
I am a big fan of wiki linking etc., but people still have to actually
search the wiki, then dig a little, for specialized stuff.
The current wiki setup does have a LOT of information on "typical" use
cases. For example, I was able to find out how to set up trac, to use
apache and windows domain authentication, on windows, with subversion
from the TracOnWindows....and a few other links that you end up
getting to. Being an Apache nit-wit, I then had to use the usergroup
to ask some specific questions, which someone that knew anything about
Apache wouldn't of needed to have specified. In that case MAYBE, I
should of gone to those wiki pages and added some notes.
Although, I must ask: Why is the Trac Documentation in .rst format,
instead of trac wiki markup, OR, why doesn't trac drop it's wiki
format for straight .rst format, instead of having to use a markup
block? yes, maybe some of the docs existed before the tool...etc.
Just a thought.
Noah Kantrowitz
> From: trac-...@googlegroups.com [mailto:trac-...@googlegroups.com]
> On Behalf Of Remy Blank
> Sent: Wednesday, June 03, 2009 1:20 PM
> To: trac-...@googlegroups.com
> Subject: [Trac] Re: Trac Recipies
>
> > Please do not write new docs in the wiki. We are trying to move away
> > from using the wiki for formal documentation and use it for more
> > discussion-oriented applications.
>
> Speaking of the newhelp branch, does it correctly represent the current
> state of the docs, or do you have more uncommitted docs up your sleeve?
I'll have to check when I get home from work.
> > If you want to sketch out new docs in the wiki thats fine, but be
> sure
> > to use the ReST processor so we can easily move them into the sphinx
> > stuff.
>
> That may be a high barrier to entry for some people. At least, if we
> have the content in the wiki, it will be immediately useful to users,
> and we can still transform it once the newhelp branch is merged.
Converting Trac wiki markup to ReST is more annoying than it sounds ;-)
Definitely doable but be careful or you will be right back at wiki doc-rot.
--Noah
Remy Blank
> Converting Trac wiki markup to ReST is more annoying than it sounds ;-)
I bet it is. And automatic conversion is probably out of the question,
too. Still, better than having no content at all?
> Definitely doable but be careful or you will be right back at wiki doc-rot.
You mean this effort should be better coordinated? You are probably
right. I would suggest that contributors "take ownership" of the pages
they add, as opposed to the "anonymous" TracGuide pages, by indicating
their author status at the top of the page. This should clearly show
that they take responsibility for the quality of the content, and
moderate any changes done by third parties.
-- Remy
Remy Blank
> The
> originator of this thread list many VERY specific things they want to
> know how to do, some of which are not possible the way they want to do
> it. These types of things are perfect for asking the newsgroup.
This is a valid concern: support should not be confused with
documentation. Support requests still belong on the mailing list or IRC,
and should not be added as documentation topics.
Now, the OP asked for a collection of Trac recipes, and IMO this falls
under "documentation" rather than "support". There are already quite a
few recipes on t.e.o, maybe an index page would help users finding what
they need?
-- Remy
Ariel Balter
I'm want to reiterate my proposal and also explain how what I mean by "recipes" differs from documentation.
TRAC COOKBOOK
I proposed taking on the project of compiling a "cookbook" for Trac made of "recipes" collected from around the web, forums, mailing lists, etc. based on solutions to common tasks (not necessarily solutions to ''problems'').
There is a lot of information floating around in the web, especially in the middle and ends of threads, on how to achieve particular goals. Sometimes this information is hard to assemble and assimilate in a timely manner because it is non-centralized and, as I said, in pieces throughout discussions.
By a "recipe" I mean a more or less complete how-to from beginning (noob) to end for how to achieve a particular goal. A recipe would be a '''complete''' description such that if a person starts at step 1 and takes every step until the end, the goal will be reached and work for the specified version of Trac. No foreknowledge or pre-requisite settings required. Here are some examples that are just popping up:
1) How to set up track to use various methods of authentication.
I know a lot of this is in the docs and TracInstall. However, I found that I still needed to do a lot of trial and error. This was especially true when I wanted to use the login form rather than the .htaccess apache window and have true logout. I had to turn off some features of the accounts manager and not others.
2) How to install and use ticket enhancing plugins:
3) How to create, implement and package a new theme.
4) Different ways to structure and use the wiki.
5) Different ways to use a Trac site. For example: code development, project management, task management, etc. What would a typical installation geared towards these uses include and how would it be managed.
6) How to set up Trac to use my favorite method of ticket tracking. (Not really familiar enough with ticket systems to give examples, just an idea based on threads I see go by in this group).
RECIPES VS DOCUMENTATION
The purpose of documentation is to provide a comprehensive description of features and how to use them. The purpose is for reference, not necessarily for usability in a given context. For many programming languages and operating systems there exist both documentation and recipe books. They have separate goals. The python docs explicitly lay out the features of the python language and how to use them. The Python Cookbook (http://oreilly.com/catalog/9780596007973/) is a collection of snippets and solutions for doing things like: "Modifying the class hierarchy of an instance", "Splitting a path into all of its parts", "Manipulating Windows Services", "Grabbing a document from the web". These recipes use ''ingredients'' from the documentation to create a delicious python ''dish'' or ''meal''.
EXISTING EFFORTS
There are clearly a few efforts already out there to improve the usability and completeness of documentation. I'm glad the motivation is there as I think it will really help the Trac community. I plan to contribute to this effort.
I want to review the responses in this thread to see how I can best help.
However, I still think a "Cookbook" is different from documentation and will be a valuable companion. I would like to hear if others agree or disagree.
PROCESS
Here is an off-the-cuff proposal for how this would work. I and perhaps a few others would moderate the cookbook. We would begin populating the cookbook with just whatever occurs to us or appears useful based on irc chats and threads in this group. We would also lay out some sort of hierarchical structure such as (Installation, Authentication, Tickets, Workflow, etc...). We would also use tags. We would also try to set out some principles for our chief priorities.
The community would request recipes via tickets. Based on our priorities, the moderators and entire community would search around for solutions. When a solution is found, it will need to be tested and verified sufficiently. When the moderators agree that the solution works, we will commit it to the cookbook. As requests come in, we can update our priorities.
HOSTING
I'm still looking for suggestions for where this thing could be hosted. If all else fails, I can start it on my own server. I'd rather it be public/donated space.
Thanks again,
Ariel
-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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....@pnl.gov
Christian Boos
> seems to me some sort of hierarchy should be considered, or
> "standardized" a bit for sub-wiki pages and sub-sub-wiki pages.
>
> I.e. SeaOfChange:
>
> blah blah....
>
>
> I am a big fan of wiki linking etc., but people still have to actually
> search the wiki, then dig a little, for specialized stuff.
>
Yes, there's already a lot in the Trac Wiki, but as in any wiki, it's
only as good as its contributions, and it needs constant care. Sometimes
the tool is at fault (and if there are identified weaknesses, we should
fix them), sometimes it's just the social aspect. If this discussion has
the only effect to encourage Trac users to get more out of *their* wiki
at trac.edgewall.org, then this would have already been a great achievement.
For example, the TracFaq used to be quite useful in the 0.8 and 0.9
days, perhaps still 0.10, but now it would need some serious update to
reflect the current concerns of Trac use cases and caveats (as the
Frequency of Asked Questions is evolving over time!). One concern with
the FAQ page is that it grew too big, so one possibility would be to
phase out the current page (TracFaq => OldTracFaq?) and restart a new
one which should be kept minimal, mainly as a kind of index of the
questions, redirecting to more specific pages for the answers (some
could be TracFaq/ sub-pages, but not necessarily, don't forget we can
easily link to sections in other pages which might just already contain
the answer!).
I'm not sure if the original request (Trac Recipies) could fit in this
renewed FAQ (maybe we need to see some concrete examples of such
recipes), but if not, then we could just start a new TracRecipies/
hierarchy on trac.edgewall.org and the topics could be the ones picked
from the page started by Remy
(http://trac.edgewall.org/wiki/SeaChange/DocumentationRequests).
And is it really "recipie" or should it be "recipe"?
> The current wiki setup does have a LOT of information on "typical" use
> cases. For example, I was able to find out how to set up trac, to use
> apache and windows domain authentication, on windows, with subversion
> from the TracOnWindows....and a few other links that you end up
> getting to. Being an Apache nit-wit, I then had to use the usergroup
> to ask some specific questions, which someone that knew anything about
> Apache wouldn't of needed to have specified. In that case MAYBE, I
> should of gone to those wiki pages and added some notes.
>
One of the things I've found very useful in MoinMoin wikis (and
certainly many other wikis have this feature but Trac), is the ability
to have e-mail notifications upon changes to pages. This enables small
"expert" communities to form and aggregate around topics and so there's
a better chance that a given page will get maintained.
> Although, I must ask: Why is the Trac Documentation in .rst format,
> instead of trac wiki markup,
It's not. Some people thought it would be a good idea to restart the
documentation from scratch in .rst, targeting the use of Sphinx, but
that effort has stagnated and others (me being in the front line) are
quite skeptical to the very idea of using anything else than Trac's own
wiki markup for the purpose of writing the Trac admin and user
documentation. The Trac developer guide is another story and for that
purpose, Sphinx seems to be perfectly suited.
> OR, why doesn't trac drop it's wiki
> format for straight .rst format, instead of having to use a markup
> block? yes, maybe some of the docs existed before the tool...etc.
> Just a thought.
>
Because the barrier to entry is much lower for the Trac wiki markup, the
likeliness is really low that a Trac user will learn yet another markup
language (and .rst is not the most intuitive one) just for contributing
a bit of her knowledge to the Trac knowledge base.
The Trac wiki is the most direct route between the potential contributor
and its potential readers. This is true in the Trac environments we set
up and work with, so I don't see why this couldn't be true for the
trac.egdewall.org's Trac.
-- Christian
Eirik Schwenke
Hash: SHA1
Christian Boos skrev 03. juni 2009 23:37:
> yoheeb wrote:
> One of the things I've found very useful in MoinMoin wikis (and
> certainly many other wikis have this feature but Trac), is the ability
> to have e-mail notifications upon changes to pages. This enables small
> "expert" communities to form and aggregate around topics and so there's
> a better chance that a given page will get maintained.
Indeed - this is very useful -- and possible in trac:
http://trac-hacks.org/wiki/WikiNotificationPlugin
http://trac-hacks.org/wiki/AnnouncerPlugin
However - it's not enabled on trac.edgewall.org ?
Some of these features run parallel to how the all-new google wave works:
Personally I'm not convinced mega jabber server clusters is a viable (or
even desirable) alternative to the "web browse + email
announce"-architecture -- but there is always room for improvements and
new/refined ideas.
Is the reason WikiNotificationPlugin isn't installed on t.e.o lack of a
email validation feature (ie: risk of being abused for spamming) ?
Best regards,
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkon6nYACgkQxUW7FIqjOSxzsQCfTA4ozWA06ldceRLepO2nZwnd
MCIAoIVWsxggakIT6LrzRzVOKFtYurhM
=IT7Q
-----END PGP SIGNATURE-----
Ariel Balter
-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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....@pnl.gov
Noah Kantrowitz
What you describe _is_ documentation. It belongs with the rest of the documentation. If you would like to contribute such docs, we would welcome it. Just type them up and put them on the wiki or in a ticket.
--Noah
From: trac-...@googlegroups.com
[mailto:trac-...@googlegroups.com] On Behalf Of Ariel Balter
Sent: Wednesday, June 03, 2009 2:07 PM
To: trac-...@googlegroups.com
Subject: [Trac] Re: Trac Recipies
Ok. I'm starting to officially feel like my topic is being hijacked, albeit unintentionally and with the best of intentions.
Eirik Schwenke
Hash: SHA1
Ariel Balter skrev 04. juni 2009 19:49:
> Eirik Schwenke wrote:
>> Christian Boos skrev 03. juni 2009 23:37:
>>>> yoheeb wrote:
>>>> One of the things I've found very useful in MoinMoin wikis (and
>>>> certainly many other wikis have this feature but Trac), is the ability
>>>> to have e-mail notifications upon changes to pages. This enables small
>>>> "expert" communities to form and aggregate around topics and so there's
>>>> a better chance that a given page will get maintained.
>>>>
>> Indeed - this is very useful -- and possible in trac:
>>
>> http://trac-hacks.org/wiki/WikiNotificationPlugin
>> http://trac-hacks.org/wiki/AnnouncerPlugin
>>
> Why is this in the Trac Recipies thread?
>
Because relates to how we can facilitate keeping pages under
trac.edgewall.org/wiki/howto/xx up-to-date and in high quality -- if we
place them in the wiki on t.e.o.
Maybe I should have included more context.
- -e
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkooDYsACgkQxUW7FIqjOSygrQCgsA6oNg/FY5/FiMnbNjT1HmSw
rOUAn0+ambbAUKRils6rB9qY4gSz1wjk
=h0Tq
-----END PGP SIGNATURE-----
yoheeb
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Christian Boos skrev 03. juni 2009 23:37:
>
> > yoheeb wrote:
> > One of the things I've found very useful in MoinMoin wikis (and
> > certainly many other wikis have this feature but Trac), is the ability
what I meant, but it does sound rather insightful... :D I have been
misquoted! oh no, it's on the internet, it must be true!
As an observation, here's is what I think seems to of washed out of
this hijacked thread so far in terms of intent....
maybe we should have an "adopt-a-wiki-page" type thing, similar to
adopt-a-hack on track hacks. "someone" can adopt a page, and either
be notified of changes by one of the notify type plugins, and have the
chance to "moderate" the changes. Or be given "exclusive" (by that, I
mean, in addition to all the people that actually maintain trac) to
edit that page specifically, and the edgewall site could create
"components" for each of the top level wiki pages (or a "suggest a new
top level topic" as well) for the purpose of people to suggest updates
to topic X, with topic "x" automatically getting a CC and choosing to
"close" the ticket. If a topic doesn't have an owner, the top guys
can make the stub, update the ticket so the post has the option to
adopt it, or someone else can adopt it.
Also, we could, for example, "standardize" on a convention for recipe
naming:
SomeWikiTopic/Recipes/HowtoDoSomethingCool
SomeWikiTopic/Recipes/HowtoDoSomethingMoreCool
SomeOtherTopic/Recipes/HowtoDoSomethingLame
so each topic could have a topic specific "Recipies" TitleIndex
section in it somewhere.
Some top level page could collate all "*/Recipies/* pages
etc.
What'cha think?
[note: long winded example follows:]
The Recipe pages could also link to their parent, or EVEN have sub
recipes:
ApacheSetup/ModPython/Recipies/Windows
ApacheSetup/ModPython/Recipies/Windows/Recipes/LDAP
ApacheSetup/Recipies/ModPython/Windows
ApacheSetup/ModPython/Recipies/Ubuntu
ApacheSetup/WSGI/Recipies/VirtualServers
ApacheSetup/SubversionAuth/Recipes/httauth etc.
Now, for the sake of argument. Lets say we used the ticket idea
mentioned above. I need some information:
I find ApacheSetup
I find there is a recipe for modpython on windows
I find there is a sub-topic page on WSGI
I see there Isn't a sub-topic page on WSGI on windows, or recipe page.
I use everything I get from the main apace topic, the wsgi topic, and
the modpython recipe to get close.
I go to the usergroup, get some help to find out how to get the
details working out.
I go the the ApacheSetup/WSGI page, click the link for "request a
change or correction to this page" (I am assuming we put them on all
the pages in this model)
I get a ticket, with ApacheSetup-WSGI as the component. somewhere I
can fill in something that says RECIPE (keyword, new type, custom
field, whatever)
I "suggest" a new recipe: I wiki format an Apache/WSGI/Recipes/Windows
page, with all that I learned. The owner of the page, (if already
adopted) can moderate this info, maybe contact me, and very possibly
choose to add it to the the WSGI/Recipies/Windows page. They could
even offer to have ME become the owner, or "abandon" that particular
sub page, letting myself, or someone else adopt just that recipe.
I am on windows
Or in short form, Lets have topics be parents of recipes. If there
isn't an appropriate topic, there probably should one. ?
Eirik Schwenke
Hash: SHA1
[Snip Cookbook def - it's a collection of Howto's/recipes]
Noah Kantrowitz skrev 04. juni 2009 20:01:
> What you describe _is_ documentation. It belongs with the rest of the
> documentation. If you would like to contribute such docs, we would welcome
> it. Just type them up and put them on the wiki or in a ticket.
>
After reading this thread, and the older trac-dev sphinx thread, as well
as looking at the latest t.e.o wiki -- I'm actually still confused as to
what documentation should go where, how to best contribute, and how to
balance tickets vs wiki vs documentation sourcecode (in the repo).
I think we need to rethink (or document plainly on the wiki) the terms
"trac user" and "trac developer". "trac end user" and "trac contributor"
might be better labels, a contributor being anyone that submits code
(python, javascript, html and templates) or documentation (wiki,
newhelp) changes.
This so that the many knowledgeable trac users can help with
translating, extending and "end user proofing" the documentation.
This may be as easy as making sure that there is a natural and direct
path from the t.e.o front page to the various dev-guides *also* for
those wanting to write a howto, proof-read or translate documentation.
We need to remember that not everyone will equate "document trac-admin
in Norwegian" with "how do I check in my python patches to trac-core". I
think the developers' hearts are in the right place, but we might have a
bit of a culture gap between core devs and the growing group of trac users.
I tried to put myself in the mind of a trac user with little or no
interest/knowledge of coding, and came up with a couple of simple use-cases:
A Trac user/contributor might want to:
1) Correct spelling errors in existing documentation
2) Update a documentation section to reflect new behaviour after
a new release (eg: 0.10 -> 0.11)
3) Translate a documentation section to Japanese or Norwegian
4) Write a short hand-holding "end-user-proof" HOWTO on setting up
trac for windows 7 with plugins a b and c, for workflow X, with
users in AD.
The workflow should(?) then be:
* search to see if a ticket exists
- if not: Make ticket (eg: spelling errors OR request for
translation)
* Check out documentation tree (trunk/doc in rst/sphinx format ?)
* Update relevant section (eg: fix spelling errors,
branch-and-translate-to Japanese)
* Generate patch
* attach patch to ticket
* A developer commits patch, public documentation updated,
ticket closed
(This is http://trac.edgewall.org/wiki/HowToContribute +
http://trac.edgewall.org/wiki/TracDev/SubmittingPatches )
Or: to 4) create a new howto on installing trac on windows 7:
* search to see if a ticket exists
- if not make one
* (Write the text, take the screenshots)
* Make a page on the wiki, attach screenshots
* link from ticket to page/doc
* Someone (tm) sanitychecks, converts to rst, updates repo ?
What would be the best approach to 3) "Translate a documentation section
to Japanese" ? Where would that documentation go ? Or a Norwegian
translation ?
I guess the workflow for any Trac stuff should be:
1: Search wiki/bug db
2: Make/update ticket
3: Solve ticket (ie: apply patch)
This is more-or-less how things work now ?
Is this about right / how the devs want it ?
What do we actually want to have in the wiki vs newhelp ?
Should we have /trunk/doc/contrib/howto|coobook etc ?
I found: http://trac.edgewall.org/wiki/TranslationRu/TracAdmin, does
this mean that case 4) would involve creating /TranslationJp/xx ?
Maybe we need a short summary like the workflow above, on the trac front
page or on the "How to contribute" page ?
It's not that it's a great evil to have trac howtos on personal blogs,
other wikis, and other documentation sites -- but I believe we should
allow those willing to help, to have a clear and easy path to do so.
I know I personally quickly abandon all hope of donating free work to
projects, if I must spend half a day figuring out how to submit my changes.
I don't usually need to do that any more, as I'm aware most developers
love patches, and hate just about everything else -- but those seeing
Trac as a project management tool and a wiki need a quick up-front hint
on how to proceed.
See also my *other* thread hijack regarding ReST vs Trac wiki markup.
- -e
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkooG3QACgkQxUW7FIqjOSzRDQCgzPF1jWPSVSb4zbhkpw73uSdi
EXAAoMvesdTeGcpjgPRBqVNxvZR3fqnA
=rI1f
-----END PGP SIGNATURE-----
Eirik Schwenke
Hash: SHA1
yoheeb skrev 04. juni 2009 21:05:
> On Jun 4, 10:38 am, Eirik Schwenke <eirik.schwe...@nsd.uib.no> wrote:
>> Christian Boos skrev 03. juni 2009 23:37:
>>> yoheeb wrote:
>>> One of the things I've found very useful in MoinMoin wikis (and
>>> certainly many other wikis have this feature but Trac), is the ability
> ...for the record, I didn't write that, so no, I can't elaborate on
> what I meant, but it does sound rather insightful... :D I have been
> misquoted! oh no, it's on the internet, it must be true!
>
Apparently I (or someone before me) failed miserably when trying to
clean up attributions and quotes in the thread. My apologies.
> As an observation, here's is what I think seems to of washed out of
> this hijacked thread so far in terms of intent....
>
> maybe we should have an "adopt-a-wiki-page" type thing, similar to
> adopt-a-hack on track hacks.
(...)
>
> Also, we could, for example, "standardize" on a convention for recipe
> naming:
> SomeWikiTopic/Recipes/HowtoDoSomethingCool
> SomeWikiTopic/Recipes/HowtoDoSomethingMoreCool
> SomeOtherTopic/Recipes/HowtoDoSomethingLame
(...)
> What'cha think?
This is one approach. I think it is sound -- but see my other post on
what we want where wrt documentation -- and also how we deal (or if we
should attempt to deal) with translations and the possibility of
different versions of a documentation-section for different releases of
trac.
Maybe enhancing your naming scheme to:
<ReleaseOrTag>/SomeWikiTopic/Recipes/HowtoDoSomethingCool
and/or:
<2LetterLanguageCode>/<ReleaseOrTag>/SomeWikiTopic/Recipes/HowtoDoSomethingCool
Eg:
no/0.11/SomeWikiTopic/Recipes/HowtoCoolness
en/0.11/SomeWikiTopic/Recipes/HowtoCoolness
/0.11/SomeWikiTopic/Recipes/HowtoCoolness (maps to defined default
language, eg "en" or
"no" ?)
en/trunk/SomeWikiTopic/Recipes/HowtoCoolness
There's still a question of resources and links from these pages to the
sourcecode repository (images, code), eg make sure links form the
/wiki/trunk goes to /svn/trunk, and /wiki/0.10/ goes to the right
versions... Maybe "simple" mapping would be enough.
These are old arguments/questions that led in the direction of the
newhelp branch (as far as I remember, can tell from a bit of googling).
However: We do *have* a wiki -- presumably we want something in it.
Possibly more than discussions... I don't think we need a
black-and-white test for what goes in the wiki and what goes in the
"proper" version controlled documentation -- but clearly the current
state of the wiki has severe limitations as a document management system.
That might be a design decision (or perhaps non-decision).
Maybe this is actually a "new" / distinct feature, and the direction
forward should be that a trac project has:
tickets (in db)
source code (in vcs)
documentation (in vcs with possibility of web editing/wiki)
tests (via bitten)
discussion (wiki/mailinglist/usenet news/irc)
The point being that source code and documentation might not be well
served by viewing them as the same.
I'm not sure what seeing wiki as a vehicle for discussion actually
implies. But it is an interesting observation if we take it seriously,
and at face value.
Again see the google wave presentation (wave.google.com) for some ideas
on this. I don't think we want to abandon http/svn for a jabber based
protocol (certainly not for 0.12!) -- but there are some ideas there
that are interesting.
- -e
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkooIGkACgkQxUW7FIqjOSwcJACfUEARQHroN++uHHOQ3IZRHvOA
hYkAnjzWijZXQ3iYg00Iy6xHOQ1GSy8x
=qHDC
-----END PGP SIGNATURE-----
Eirik Schwenke
Hash: SHA1
Christian Boos skrev 03. juni 2009 23:37:
> yoheeb wrote:
>> Although, I must ask: Why is the Trac Documentation in .rst format,
>> instead of trac wiki markup,
>
> It's not. Some people thought it would be a good idea to restart the
> documentation from scratch in .rst, targeting the use of Sphinx, but
> that effort has stagnated and others (me being in the front line) are
> quite skeptical to the very idea of using anything else than Trac's own
> wiki markup for the purpose of writing the Trac admin and user
> documentation. The Trac developer guide is another story and for that
> purpose, Sphinx seems to be perfectly suited.
>
>> OR, why doesn't trac drop it's wiki
>> format for straight .rst format, instead of having to use a markup
>> block? yes, maybe some of the docs existed before the tool...etc.
>> Just a thought.
>>
>
> Because the barrier to entry is much lower for the Trac wiki markup, the
> likeliness is really low that a Trac user will learn yet another markup
> language (and .rst is not the most intuitive one) just for contributing
> a bit of her knowledge to the Trac knowledge base.
Why not use restructured text ? It supports direct generation of
latex/pdf/s5 slides, has a well defined design for extension, and IMNHO
is quite readable.
I would contend that those not able to read rst would be better served
by a WYSIWYG editor anyway ?
I really don't mean this in a negative way, but do you think:
http://trac.edgewall.org/wiki/WikiFormatting
is significantly easier on the eye, or more intuitive than:
http://docutils.sourceforge.net/docs/user/rst/quickref.html ?
(See also: [RstQuickRef]_).
If so, I would appreciate you taking the time to elaborate. Perhaps
because Trac's markup is closer to other wikis ? I realize that we now
have a lot of "legacy" users (me included:) -- so a change is ill
advised without good reason.
Personally I find that '''bold''' and ''italic'' is a) wrong (not what
you *mean* but what you see, and b) rather visually meaningless in the
text editor (contrast: *emphasis* **strong emphasis** with ''emphasis''
(or is it a quotation) and '''strong emphasis''' (looks a bit like a
block-quote?)).
RST has less special characters in the markup, which is great for those
of us not using a US layout --
ctrl-altgr/meta-7,ctrl-altgr/meta-7,ctrl-altgr/meta-7 for a
codeblock/monospace (or shift-next_to_backspace-space for backtick)
isnt't all that easy -- and reading the source document, a simple:
.. code-block:: python
:linenos:
#Some python code -- but just a comment for this example
#it will be printed with line numbers (:linenos: directive).
The above code is a block, by virtue of it's indentation. The markup
arguably works in a plain-text print-out.
{{{
#!python
#This also works. Explicit termination of blocks, rather than
#python-like indentation can be a benefit -- but it doesn't look very
#pretty -- or intutitive -- again IMNHO
}}}
I know these are small details -- but I'm trying (actually, not
rhetorically) to see how the trac wiki markup can be considered
better, even for use in the wiki.
The syntax styles are not radically different -- but I feel that Rst is
better suited to evolving texts (full pages, rather than short
snippets). It's easier to work with the "source" document, and more
usable in a version controlled environment.
RST has some serious limitations, eg: limited autonumbering of lists,
underscore for linking (not very wiki-like). Rst also has rather limited
support for mulitple levels of headings -- while I think the 6 headings
for html is a bit overkill, Rsts "two-and-a-half" (=/- look different
enough and make sense -- but the tilde ("~") is a poor choice for third
level down IMNHO).
Rst also uses the backtick, wich isn't a very good idea -- the number of
non-printing characters that make sense in a multilingual and
multiscript (eg: Japanese and Chinese kanji) environment is
very limited. Dash "-", underscore "_", equal "=", colon/semicolon as
well as single and double quotes is about the limit.
Due to the popularity of email/it's use in URIs the @-sign is also a
good canditate. In general regular punctation used in English and basic
math (Now I know curly-braces are set-markers, but set theory
unfortunately does not fall under what most people consider "basic"
math).
So it is quite possible that it *is* a poor candidate for default wiki
markup. I'd like to hear some more opinions though.
In theory it feels like it should be easy to write a small plugin or two
to extend the rst parser, and make it a little more wiki-like.
One certainly gets a whole lot "for free" with rst, see for example the
Grok/zope3 documentation tutorial [GrokTut]_.
In the previous discussion of Sphinx [SphinxThread]_, it's pointed out
that Moinmoin is looking at moving to a mercurial backend, that work
appears to be complete: [MoinBackend]_. So a wiki with revision
controlled backend is certainly feasable.
I have yet to use it though -- I don't know how well the web/wiki
interface plays along with checking out the code, doing some changes
with a real text editor and checking them in -- it *seems* perfectly
feasible.
Christian also says that:
"The second argument is that if the TracTeam (tm) doesn't use its own
wiki formatting and rendering chain, why should others trust it for
writing their own documentation?
If there are problems with that formatting or the rendering chain
which makes it a sub-optimal solution compared to other tools (in the
same category), then our "job" would be to fix it. Otherwise by
the same kind of argument we could have switched to say, Roundup for
our bug tracking needs, if some had considered it would have been
better than Trac in this respect."
Noah points to earlier discussion, which concluded with wikis being good
for discussion, but not documentation -- but I still think this is a
vital discussion; what roles should the wiki-part of trac fill ? Should
it be better integrated in trac (eg: wikipages in rst, in it's own repo,
or its own subfolder of a repo) ? The latter would place strong
emphasis on a "one right way to use trac" -- which is generally against
the open spirit of Trac.
Still, *not* having some features (eg: rendering pdfs with figures from
the wiki) is a serious problem. We really should have a system that
allows us to integrate tabular data, graphs, diagrams and bitmap
graphics into the stuff that is truly collaboratively edited.
This is *not* an easy problem though -- note that wikipedia, google wave
among others still have *not* got this right. Collaborative editing of
non-textual data isn't easy.
For some inspiration on what is possible with regards to
richer-than-text data, have a look at http://dabbledb.com , the google
chart api and the Inkscape whiteboard extention (the latter uses xmpp,
just as google wave does).
LaTeX ofcourse the canoical example of how to design a documentation
framework. It's not perfect, but it's solid enough that one needs a
good reason to do something differently from LaTeX (eg: I don't
particularily like aestetics of the TeX/LaTeX markup -- but then I don't
really enjoy writing ((ht)|s|x)ml by hand either).
Christian also states, somewhat out-of-context:
"I think it will eventually be possible to bridge this gap by having
Trac generate .rst markup from wiki markup"
Which is proably true (in general mapping from one in-memory document
tree to another shouldn't be all that hard). But this might not be the
best way to go forward.
I actually think that if we want to keep the Trac markup as primary,
mapping to docutils should be done on the document-tree level. That is
we parse TracMarkup -> DocumentGraph, then map that to the internal RST
representation of a document (this is my impression from looking briefly
into how docutils/rst is extended using plugins, and how rst generates
documents).
Phew,
apologies for the thread-hijacks today -- but I think the original
question has formed an interesting catalyst for discussing trac
documentation, and contribution guidelines.
Also of interest regarding reStrcuturedText and documentation:
Footnotes:
.. [RstQuickRef]
http://docutils.sourceforge.net/docs/user/rst/quickstart.html
.. [SphinxThread]
http://groups.google.com/group/trac-dev/browse_thread/thread/f79a1cbb894fe079/22740041300c5873#22740041300c5873
.. [MoinBackend]
http://moinmo.in/ChristopherDenter/HelpOnStorageConfiguration
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkooJmMACgkQxUW7FIqjOSzg7ACeM7eWWD+IBdwmQOY03SpOunM2
MvQAnRTD0dNgbglb6QivA/3gD1Yf2fqw
=Yz86
-----END PGP SIGNATURE-----
Lance Hendrix
1. Write content once (render many or as needed)
2. Maintain as few copies as possible (preferable only one master copy)
Otherwise, I could care less (mostly) where or how (wiki or Rst). If
you asked me, out of context of Trac, I would suggest DocBook (it's what
I decided on when evaluating what to write content for my personal
web-site with), but I don't think it makes sense in the context of
Trac. My only fear is of having to maintain or create the documentation
in both Rst and (Trac) wiki. Disclaimer - I *mostly* work with US
character sets and keyboard layouts, so I don't have experience with
issues surrounding multi-lingual or non-en-US layouts.
My $0.02 US
Lance
Noah Kantrowitz
--Noah
> -----Original Message-----
> From: trac-...@googlegroups.com [mailto:trac-...@googlegroups.com]
> On Behalf Of Eirik Schwenke
> Sent: Thursday, June 04, 2009 12:54 PM
> To: trac-...@googlegroups.com
Olemis Lang
Tracky poems covered by the finest cheeze ever made (include zome
cheezburgerz pleaze ;), I want them to be inside a box, I want you to
put me inside that box too, and maintain it closed ... until my
triumph be announced in Trac-land.
XD
On Thu, Jun 4, 2009 at 2:07 PM, Eirik Schwenke
<eirik.s...@nsd.uib.no> wrote:
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> [Snip Cookbook def - it's a collection of Howto's/recipes]
>
> Noah Kantrowitz skrev 04. juni 2009 20:01:
>> What you describe _is_ documentation. It belongs with the rest of the
>> documentation. If you would like to contribute such docs, we would welcome
>> it. Just type them up and put them on the wiki or in a ticket.
>
> After reading this thread, and the older trac-dev sphinx thread, as well
> as looking at the latest t.e.o wiki -- I'm actually still confused as to
> what documentation should go where, how to best contribute, and how to
> balance tickets vs wiki vs documentation sourcecode (in the repo).
>
Well it seems it's more complex than I though.
> I think we need to rethink (or document plainly on the wiki) the terms
> "trac user" and "trac developer". "trac end user" and "trac contributor"
> might be better labels, a contributor being anyone that submits code
> (python, javascript, html and templates) or documentation (wiki,
> newhelp) changes.
>
Let me see if I get the idea :
- Contributor : a contributor being anyone that submits code
(python, javascript, html and templates) or documentation (wiki, newhelp)
changes. (This one seems to be ok for me)
- Trac developer : What's the difference between a Trac dev and a contributor
that submits code ( checkin permissions ?)
- trac user" : ¿?
- trac end user: ¿? What's the difference
Look, two hints (I dont know if somebody has mentionned this before) :
- Roles should be determined considering the different user profiles (e.g. Trac
admin (and | or) Server admin, plugin dev, core dev, Trac user, ...)
- I forgot the second. I'm getting old damn it ! grgrggrggrggrrrrr
- There should be a reference, a user guide, and a cookbook (perhaps this ìs
obvious but anyway)
- Participation should be more open (e.g. plugin ownership)
all this is IMHO and I'm not a Trac dev ;)
>
> A Trac user/contributor might want to:
>
> 1) Correct spelling errors in existing documentation
>
> 2) Update a documentation section to reflect new behaviour after
> a new release (eg: 0.10 -> 0.11)
>
> 3) Translate a documentation section to Japanese or Norwegian
>
> 4) Write a short hand-holding "end-user-proof" HOWTO on setting up
> trac for windows 7 with plugins a b and c, for workflow X, with
> users in AD.
>
And something similar happens with plugins in isolation.
> I found: http://trac.edgewall.org/wiki/TranslationRu/TracAdmin, does
> this mean that case 4) would involve creating /TranslationJp/xx ?
>
What about using Wiki Negotiation plugin ?
> Maybe we need a short summary like the workflow above, on the trac front
> page or on the "How to contribute" page ?
>
> It's not that it's a great evil to have trac howtos on personal blogs,
> other wikis, and other documentation sites -- but I believe we should
> allow those willing to help, to have a clear and easy path to do so.
>
and I also believe that is far more easy to have everything in a
single place and not being lost in a mountain of search results in
order to "config Apache + Trac + SVN with Active Directory" for
instance
> I know I personally quickly abandon all hope of donating free work to
> projects, if I must spend half a day figuring out how to submit my changes.
>
Oh ! yes ...
--
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
Ariel Balter
I happen to have just created the page [wiki:TracCookbook/About] at trac.edgewall.com. I am still in the middle of composing the page offline. That doesn't have to be how/where it goes, I just really wanted to get started.
I really like the idea of "adopters". Another idea crossed my mind yesterday on the way home from work. I was trying to think of a completely "open" way of making the cookbook. Here's what crossed my mind:
Anyone can post any recipe. There can be multiple recipes. However, these get "reviewed" or "voted" on in some way. Perhaps some number of +'s if they work (depending on how well or easy to use) and some number of -'s (depending on how badly they fail or screw things up for you). Bad recipes will get low numbers of +'s or even -'s if they are wrong or break things. Some sort of faceted browsing can allow users to search for only recipes with at least some number of +'s or at least no -'s.
That was just an idea, and would need some sort of additional plugin or back-end structure to work.
Thanks, Ariel
P.S. to Noah -- If the cookbook is going to be part of the Trac documentation, great. But I still think it is worthwhile having different words for the kind of documentation that "documents" the features and the kind the gives recipes. Regards, AB
Eirik Schwenke
Hash: SHA1
[Cross-posted to trac-dev, as this thread should be moved there
please reply only to trac-dev]
Olemis Lang skrev 04. juni 2009 22:29:
> On Thu, Jun 4, 2009 at 2:07 PM, Eirik Schwenke
> <eirik.s...@nsd.uib.no> wrote:
>>
>> I think we need to rethink (or document plainly on the wiki) the terms
>> "trac user" and "trac developer". "trac end user" and "trac contributor"
>> might be better labels, a contributor being anyone that submits code
>> (python, javascript, html and templates) or documentation (wiki,
>> newhelp) changes.
>>
>
> Let me see if I get the idea :
>
> - Contributor : a contributor being anyone that submits code
> (python, javascript, html and templates) or documentation (wiki, newhelp)
> changes. (This one seems to be ok for me)
> - Trac developer : What's the difference between a Trac dev and a contributor
> that submits code ( checkin permissions ?)
Yes, my thinking was that trac-dev would be someone with commit access.
Apparently there should be no such thing as a trac dev, only trac
commiters ...
> - trac user" : ¿?
> - trac end user: ¿? What's the difference
No difference, "trac user" and "trac dev" are the only "old"/legacy
terms that I've seen used before -- and my point was that those terms
weren't all that helpful for discussion.
As a side note, the term "trac dev" might be relevant as in: "trac-dev:
someone that has a working knowledge of the internals of trac".
These are all small details - I believe my original comments had
something to do with defining the workflow, and the notion that not all
contributors (eg: doc writers) are / should be trac devs.
(...)
>> I found: http://trac.edgewall.org/wiki/TranslationRu/TracAdmin, does
>> this mean that case 4) would involve creating /TranslationJp/xx ?
>>
>
> What about using Wiki Negotiation plugin ?
Is that plugin alive/working ? I had forgotten all about it -- I assume
you refer to: http://trac-hacks.org/wiki/TracWikiNegotiatorPlugin
The example site appears to be down -- but that doesn't mean the plugin
is dead.
There's still a question of managing all this stuff, which is somewhat
related to tagging/branching of documentation -- and possibly suggests
some changes to the wiki in future releases of trac.
An interesting project I worked with at the University of Trondheim had
some useful features for managing documentation:
a) each article is contained in an xml-file (analogous to a wiki page)
b) each has an author/owner
c) the system sends out mail to each owner after x months, asking them
to verify that the article is still relevant, and either:
1) sign off (click "ok")
2) update and sign off (ie: edit, sign off)
3) delete it
This is mostly workflow related, and could probably be implemented on
top of either rest/sphinx and/or the wiki.
The system is open, and has some multilingual content:
http://infoweb.ntnu.no/about+infoweb/help/about.html
(unfortunately it appears development is better maintainted
than documentation, as can be seen from the warning on top of
the following page):
http://infoweb.ntnu.no/about+infoweb/info/technical.html
- -e
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkos+7sACgkQxUW7FIqjOSxJ+gCgoCXQ0gjIfkF04aVx1ciLP2SI
7WwAn3dH104+1Z2HEgkKM01heVodO2KU
=cIT9
-----END PGP SIGNATURE-----
Eirik Schwenke
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.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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-----
Jeff Hammel
>
> -----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 ?
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.
>
> 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.
Jeff
Eirik Schwenke
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.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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-----
Jeff Hammel
<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
Olemis Lang
> 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
Ethan Jucovy
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
Eirik Schwenke
Hash: SHA1
Olemis Lang skrev 08. juni 2009 15:24:
> On Mon, Jun 8, 2009 at 7:46 AM, Jeff Hammel<jha...@openplans.org> wrote:
>> On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote:
(...)
>
> (Besides) IMHO I also like Trac syntax because :
>
> - It's extensible (macros + processors)
So is ReST, FYI. However, along with your next point:
> - It's more close to what humans have in mind when they
> write something (yes ! the users mental model do care :))
> e.g. TracLinks
This would (indeed, I belive it is, in the case of trac) have to be
implemented as extention to ReST. This isn't a bad thing, as long as the
design of ReST allows does this do be done in a "reasonable" manner --
ie: all (correct) ReST processors still works on custom markup.
(...)
>
> 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 ?
Just curios.
Best regards,
- --
.---. Eirik Schwenke <eirik.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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
iEYEARECAAYFAkotF3MACgkQxUW7FIqjOSyL5QCfUDOokNGLDtXgbi4bwp9OHhUb
TRIAoKPuUE6zNvdAk9jZdIKLYc2swhok
=iV/M
-----END PGP SIGNATURE-----
Roger Oberholtzer
> 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
Christian Boos
> 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
Olemis Lang
> Olemis Lang skrev 08. juni 2009 15:24:
>> On Mon, Jun 8, 2009 at 7:46 AM, Jeff Hammel<jha...@openplans.org> wrote:
>>> On Mon, Jun 08, 2009 at 02:36:49PM +0200, Eirik Schwenke wrote:
> (...)
>>
>> 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 Balter
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
-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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....@pnl.gov www.arielbalter.com www.pnl.gov
Olemis Lang
On Mon, Jun 8, 2009 at 11:22 AM, Ariel Balter<ar...@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
Eirik Schwenke
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.s...@nsd.uib.no>
( NSD ) Harald Hårfagresgate 29 Rom 150
'---' N-5007 Bergen tlf: (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-----
Lance Hendrix
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
yoheeb
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.
Olemis Lang
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 !
Christian Boos
> 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