-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ 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
1. Register @ TH
2. Create a wiki page
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.
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
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.
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
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 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
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
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
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
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
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
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
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 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
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
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 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
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.
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-----
[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-----
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-----
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-----
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
[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-----
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 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-----
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
(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
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.
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-----
> 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
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
Well I'll tell you about my blog (other people could tell you about
other things too ;) and mainly about a specific entry [1]_
- I use Dojo ...
- I use Trac CSS ...
- I use div macro for the collapsible panel stuff. The benefits are
- Users only read a summary of the article
- If they want to they read the full article
- without navigating to a different page
- I'm focused on writing my article and not on seting up the html + js
code needed for that.
- *DONT LIKE BLOGGER EDITOR*. Even if there's a lot of effort in
there, it doesnt
help me much (too many clicks or otherwise pure HTML). Wiki is just
fast & great ...
- I use syntax highlighting (processors) for code snippets.
- I dont use ImageMacro because I dont know URLs to images beforehand, but I
could ;)
- I use TracLinks for definitions and more
- I use iGoogleGadget macro (TracGViz plugin [2]_) for including
Gadgets in posts.
(not in the article I mention :-/)
- I plan to implement more specific stuff to do many other things fast as hell.
- Header & linking of course ;)
- The `span + icon` thing for links (fast as hell as compared with plain HTML)
... but these days I've not much time :(
and all this is tremendously non-std, but is useful & that's what
matters for me .
> Just curios.
>
Dont if it helps and if it's related with the main subject; but u just
asked for it ;)
BE CAREFUL ! If you use all these ideas you'll be violating my
copyrights ... c'u in court >(
XD
.. [1] PyUMLGraph : Otra manera de contemplar el código
(http://simelo-es.blogspot.com/2009/06/pyumlgraph-mirando-al-codigo-de-python.html)
.. [2] TracGViz plugin
(https://opensvn.csie.org/traccgi/swlcu/wiki/En/Devel/TracGViz)
-- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ Ariel I Balter, Ph.D. Postdoc Biological Monitoring/Modeling Fundamental and Computational Sciences Directorate Pacific Northwest National Laboratory Mail: PO Box 999, MS P7-58,Richland, WA 99352 Shipping: 790 6th Street, MS P7-58, Richland, WA 99354 Tel: 509-376-7605 Cell: 509-713-0087 ariel....@pnl.gov www.arielbalter.com www.pnl.gov
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
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-----
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 !
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