[Trac] Re: Trac Recipies
-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 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: http://wave.google.com/ 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.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 iEYEARECAAYFAkon6nYACgkQxUW7FIqjOSxzsQCfTA4ozWA06ldceRLepO2nZwnd MCIAoIVWsxggakIT6LrzRzVOKFtYurhM =IT7Q -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 Recipies
Why is this in the Trac Recipies thread? Eirik Schwenke wrote: -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 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: http://wave.google.com/ 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.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 iEYEARECAAYFAkon6nYACgkQxUW7FIqjOSxzsQCfTA4ozWA06ldceRLepO2nZwnd MCIAoIVWsxggakIT6LrzRzVOKFtYurhM =IT7Q -END PGP SIGNATURE- -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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 Recipies
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-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Ariel Balter Sent: Wednesday, June 03, 2009 2:07 PM To: trac-users@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. 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 Remy Blank wrote: Noah Kantrowitz wrote: Converting Trac wiki markup to ReST
[Trac] Re: Trac Recipies
-BEGIN PGP SIGNED MESSAGE- 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.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 iEYEARECAAYFAkooDYsACgkQxUW7FIqjOSygrQCgsA6oNg/FY5/FiMnbNjT1HmSw rOUAn0+ambbAUKRils6rB9qY4gSz1wjk =h0Tq -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 Recipies
On Jun 4, 10:38 am, Eirik Schwenke eirik.schwe...@nsd.uib.no wrote: -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 ...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! 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. ? --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
What documentiondto we want, were do we put it and how do we maintain it [Was: Re: [Trac] Re: Trac Recipies]
-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). 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.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 iEYEARECAAYFAkooG3QACgkQxUW7FIqjOSzRDQCgzPF1jWPSVSb4zbhkpw73uSdi EXAAoMvesdTeGcpjgPRBqVNxvZR3fqnA =rI1f -END PGP SIGNATURE- --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users
[Trac] Re: Trac Recipies
-BEGIN PGP SIGNED MESSAGE- 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.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 iEYEARECAAYFAkooIGkACgkQxUW7FIqjOSwcJACfUEARQHroN++uHHOQ3IZRHvOA hYkAnjzWijZXQ3iYg00Iy6xHOQ1GSy8x =qHDC -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 wiki markup vs ReST [Was: Re: [Trac] Re: Trac Recipies]
-BEGIN PGP SIGNED MESSAGE-
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
Re: Trac wiki markup vs ReST [Was: Re: [Trac] Re: Trac Recipies]
As a (potential) contributor, I would say that I only have two requirements:
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
Eirik Schwenke wrote:
-BEGIN PGP SIGNED MESSAGE-
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
RE: Trac wiki markup vs ReST [Was: Re: [Trac] Re: Trac Recipies]
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
-Original Message-
From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com]
On Behalf Of Eirik Schwenke
Sent: Thursday, June 04, 2009 12:54 PM
To: trac-users@googlegroups.com
Subject: Trac wiki markup vs ReST [Was: Re: [Trac] Re: Trac Recipies]
-BEGIN PGP SIGNED MESSAGE-
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
[Trac] Re: Trac Recipies
Wow! Thanks! That is a practical and detailed description of what I have in mind. I'm so glad to see that some are at least getting the picture of where this could go, how it could be useful, and how it could be done. 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 yoheeb wrote: On Jun 4, 10:38 am, Eirik Schwenke eirik.schwe...@nsd.uib.no wrote: -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 ...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! 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
Re: What documentiondto we want, were do we put it and how do we maintain it [Was: Re: [Trac] Re: Trac Recipies]
Well, I want two tons of docs and an special edition containing all my 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.schwe...@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 ! grgrggrggrggr - 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 --~--~-~--~~~---~--~~ 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 Recipies
Trac-hacks is that site. --Noah -Original Message- From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of abalter Sent: Wednesday, June 03, 2009 10:52 AM To: Trac Users Subject: [Trac] Trac Recipies I would like to help put together a site of recipes for using Trac. 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 --~--~-~--~~~---~--~~ 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 Recipies
abalter wrote: ... Perhaps the folks that run Trac-hacks would be willing to give me some space. ... 1. Register @ TH 2. Create a wiki page --~--~-~--~~~---~--~~ 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 Recipies
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. From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Ariel Balter Sent: Wednesday, June 03, 2009 12:59 PM To: trac-users@googlegroups.com Subject: [Trac] Re: Trac Recipies I disagree. Noah Kantrowitz wrote: Trac-hacks is that site. --Noah -Original Message- From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of abalter Sent: Wednesday, June 03, 2009 10:52 AM To: Trac Users Subject: [Trac] Trac Recipies I would like to help put together a site of recipes for using Trac. 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 -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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 -~--~~~~--~~--~--~---
[Trac] Re: Trac Recipies
What do you mean by recipes? I've been working on Trac project templates with TracLegos (http://trac-hacks.org/wiki/TracLegosScript). Its far from being what it needs to be, but for a mostly in my free time project, its not bad. 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 On Wed, Jun 03, 2009 at 10:52:29AM -0700, abalter wrote: I would like to help put together a site of recipes for using Trac. 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 --~--~-~--~~~---~--~~ 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 Recipies
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...) 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 **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. *From:* trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] *On Behalf Of *Ariel Balter *Sent:* Wednesday, June 03, 2009 12:59 PM *To:* trac-users@googlegroups.com *Subject:* [Trac] Re: Trac Recipies I disagree. Noah Kantrowitz wrote: Trac-hacks is that site. --Noah -Original Message- From: trac-users@googlegroups.com mailto:trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of abalter Sent: Wednesday, June 03, 2009 10:52 AM To: Trac Users Subject: [Trac] Trac Recipies I would like to help put together a site of recipes for using Trac. 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 -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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 mailto:ariel.bal...@pnl.gov www.arielbalter.com http://www.arielbalter.com www.pnl.gov http://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 -~--~~~~--~~--~--~---
[Trac] Re: Trac Recipies
BTW, I didn't mean to hijack your thread with my previous note. I think 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 abalter wrote: I would like to help put together a site of recipes for using Trac. 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 --~--~-~--~~~---~--~~ 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 Recipies
Lance Hendrix wrote: 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. --~--~-~--~~~---~--~~ 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 Recipies
One thing I especially had trouble with was understanding what the 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-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Lance Hendrix Sent: Wednesday, June 03, 2009 1:28 PM To: trac-users@googlegroups.com Subject: [Trac] Re: Trac Recipies 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...) 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 **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. *From:* trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] *On Behalf Of *Ariel Balter *Sent:* Wednesday, June 03, 2009 12:59 PM *To:* trac-users@googlegroups.com *Subject:* [Trac] Re: Trac Recipies I disagree. Noah Kantrowitz wrote: Trac-hacks is that site. --Noah -Original Message- From: trac-users@googlegroups.com mailto:trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of abalter Sent: Wednesday, June 03, 2009 10:52 AM To: Trac Users Subject: [Trac] Trac Recipies I would like to help put together a site of recipes for using Trac. There is a ton of great information in this email list and forums and out
[Trac] Re: Trac Recipies
Lance Hendrix wrote: 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 signature.asc Description: OpenPGP digital signature
[Trac] Re: Trac Recipies
I'm glad to see I've already been quoted on this page: 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 Remy Blank wrote: Lance Hendrix wrote: 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 -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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 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? 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-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Remy Blank Sent: Wednesday, June 03, 2009 2:30 PM To: trac-users@googlegroups.com Subject: [Trac] Re: Trac Recipies Lance Hendrix wrote: 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 --~--~-~--~~~---~--~~ 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 Recipies
-Original Message- From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Dan Winslow Sent: Wednesday, June 03, 2009 12:41 PM To: trac-users@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? 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 --~--~-~--~~~---~--~~ 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 Recipies
Dan Winslow wrote: 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 signature.asc Description: OpenPGP digital signature
[Trac] Re: Trac Recipies
-Original Message- From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Remy Blank Sent: Wednesday, June 03, 2009 1:02 PM To: trac-users@googlegroups.com Subject: [Trac] Re: Trac Recipies Dan Winslow wrote: 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 --~--~-~--~~~---~--~~ 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 Recipies
Noah Kantrowitz wrote: 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 signature.asc Description: OpenPGP digital signature
[Trac] Re: Trac Recipies
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 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 TracOnWindowsand 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. --~--~-~--~~~---~--~~ 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 Recipies
-Original Message- From: trac-users@googlegroups.com [mailto:trac-us...@googlegroups.com] On Behalf Of Remy Blank Sent: Wednesday, June 03, 2009 1:20 PM To: trac-users@googlegroups.com Subject: [Trac] Re: Trac Recipies Noah Kantrowitz wrote: 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 --~--~-~--~~~---~--~~ 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 Recipies
Noah Kantrowitz wrote: 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 signature.asc Description: OpenPGP digital signature
[Trac] Re: Trac Recipies
yoheeb wrote: 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 signature.asc Description: OpenPGP digital signature
[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. 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 Remy Blank wrote: Noah Kantrowitz wrote: 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
[Trac] Re: Trac Recipies
yoheeb wrote: 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 TracOnWindowsand 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 --~--~-~--~~~---~--~~ 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 -~--~~~~--~~--~--~---
