Subject:
(long) Using A Wiki (TWiki) at LDP (was Re: Is PHP-HOWTO some kind of joke ? (fwd))
From:
Randy Kramer ####@####.####
Date:
12 Nov 2003 19:34:39 -0000
Message-Id: <200311121445.18056.rhkramer@fast.net>
<introduction>
The following is (sort of) a response to Rodolfo (but not entirely, more
below) and something of a demonstration of the simplicity of TWiki. (I
originally wrote this as an email (draft) and planned to simply copy and
paste it to TWiki. That is essentially what I did, but because of the
intrusions of my (real life) schedule, I did a little editing on TWiki before
sending this. But, the following (except for this <introduction>) is a
verbabim copy of what I pasted into WikiLearn at
http://twiki.org/cgi-bin/view/Wikilearn/TWikiAdvocacyForTheLdpRaw. Please
take a look.
After writing this and looking back at Rodolfo's questions, I realized I
hadn't explicitly answered them (and maybe not even implicitly). Shortly
after posting this, I will start a second response focusing specifically on
his questions. (And I will be much briefer.)
I know that I suggested or supported moves toward a wiki in the past. I don't
recall very well, but I think one time at least, I didn't push the idea very
hard because Lampadas was on the horizon. We can start using a wiki this
afternoon, and if Lampadas or something similar does come to pass, we can
abandon the appropriate parts of the wiki and move them into Lampadas.
regards,
Randy Kramer
</introduction>
---++ !! Contents
%TOC%
---++ Context
On Tuesday 11 November 2003 04:57 pm, Rodolfo J. Paiz wrote:<br />
> I have no idea what a wiki is, but will it keep the portability that exists
> today, and that is so important? Will all the HOWTO's be downloadable and
> viewable in various formats, will we still be able to mirror the site,
> etc.? Will it (bluntly) reduce the wonderful ubiquity the LDP has today?
> What are the downsides?
---++ Introduction
Thanks for asking! And thanks to Martin Wheeler for providing an excellent
answer, but I'd like to go a little further. I won't do it all in this post
(or maybe I'll mention it all (or most of it) but not elaborate as much as
I'd like until later).
A wiki can be (or can be used for) many different things. I'm going to
describe it as a free-format on-line database that can be edited by anyone
via their web browser. And, although the original wiki way advocated
allowing editing by anyone, some wiki engines (notably TWiki) provide means
to restrict editing by various permissions type approaches. (Believe it or
not, there are probably over 100 different "wiki engines" (programs that make
a wiki work).)
---++ TWiki
TWiki is still my preferred wiki engine, although it has some weaknesses and
I've recently decided to spend at least a little time researching current
alternatives (which is why I posted yesterday with some questions about
WikiText).
---+++ Advantages of TWiki
Some other advantages of TWiki (sometimes with some notes comparing it to
"traditional" wikis):
* content is under RCS revision control which means that there is always a
record of who wrote (revised) what, and when, and which can be used to
recover from vandalism (by reverting to a prior revision)
* there is a lot of functionality that can be added to TWiki by plugins,
addons, or patches (I recently saw a note that TWiki now has 99 plugins and
proposing an informal contest to see who would create (and "post") the
100th):
* a built-in drawing tool that can be used via your browser (TWikiDraw)
-- a little primitive, but still quite useful -- I've also been able to do
some (drawing) editing offline using, IIRC, JHotDraw, which, IIUC, is the
tool from which TWikiDraw was derived.
* the ability to add "structured data" to any topic via the addition of
a form (IIRC "structured data" is the term I use, IIRC, they call it "form
data", but what it is is the more structured type data you might see in a
non-free-format database
* a voting plugin (I don't recall the name, and I don't think I've used
it) -- there are other simple ways of voting (with cheating possible) by
simply each person editing the page, adding their vote, and revising their
vote totals (or having them revised automatically by incorporating a
spreadsheet on the page)
* a spreadsheet plugin
* an active communtity of developers (not just a single developer as is
(was?) common for many of the other wikis I looked at (3 years ago) (still
development is not as fast as I'd like, but, the development community has
recently attempted a sort of renaissance in approach that may result in
faster progress (not to say that progress is always a good thing, but there
are changes I would like to see)
---+++ Use for Long Documents
Some people use (attempt to use?) TWiki to collaboratively write books or long
documents. (Search for Motorola, and something that might be called the
Motorola extensions, look for the search feature that presents entire (web)
pages (unfortunately called topics) in the search result (something like
"book view").
---+++ Overloaded Terminology
---++++ Template
Just as a warning, unfortunately, TWiki overloads a few terms that can lead to
confusion. IIRC, they refer to three different things by the name "template"
(the thing that creates the overall look and feel of each TWiki page (which
can also be changed by skins, of which there are several); a (content)
template to start a page with some boilerplate text (see [[Web Topic
Template]]); and, IIRC, the third has something to do with the forms system).
---++++ Web
The (an) other term that is overloaded is web. In addition to the meaning we
all know (the Internet "web"), TWiki can group pages by what they call webs.
At the operating system level (at least currently, this topic is under
occasional discussion), topics (pages) in different webs are in different
directories (folders), so I think of a web as a directory (and would prefer
that terminology be adopted).
---++++ WikiWords
There are some other things to get used to. A basic "paradigm" of wikis is
the use of WikiWords (TWiki.Words capitalized words "scrunched" together to
automatically create links to (new) pages). TWiki (like some other wikis)
provides a means to avoid that paradigm. In TWiki you can write [[Web Topic
Template]] instead of WebTopicTemplate to get a link that looks more English
like. _The "official" definition of a WikiWord for TWiki is something like
this: one or more capital letters, followed by one or more lower case
letters, followed by one or more capital letters, followed by any combination
of letters, numbers, and a (few) punctuation marks, with caveats that I won't
(can't) recite instantly._
_Unfortunately, the actual title (and displayed title) of the resulting page
is without spaces. Using underbars ("_") to separate words in the title
provides some improvement, and I am an advocate of allowing spaces in TWiki
words. (The problem is that, in the current versions of TWiki, the actual
content of a page is stored in a file with the <wikiword>.txt as the file
name. Spaces create problems (that could be overcome, AFAIK)._
---+++ Some TWiki Markup
The other thing to get used to is the difficulty ( ;-) ) of creating properly
marked up text for TWiki. Just to show how difficult it is, I'm going to
copy and paste this text (verbatim) to a WikiLearn page and ask that you go
and take a look at how ugly it is.
In fact, I'll call the page
[[http://TWiki.org/cgi-bin/view/Wikilearn/TWikiAdvocacyForTheLDP][TWiki
Advocacy For The LDP]]. (I created this link in what I'll call the long form
so you can use it (hopefully (I know)) from this email -- if not copy and
paste the URL looking part to your browser. Within TWiki, as you partially
already know, the link to the same page could also be written in any of the
following ways:
* [[TWiki Advocacy For The LDP]
Oops, I'll stop, that's going to be too much detail for now.
---++++ Tables
Let me add a table -- see what this looks like on the referenced page.
| A | simple | table |
|with |numbers or | whatever|
Many attributes of a table can be adjusted using TWiki markup, those that
can't can be adjusted by using the advanced table plug-in or adding HTML
markup.
---++++ Pictures
Many graphics can be added by just including a (valid) URL on the page -- this
should appear as the (old, but current) TWiki logo:
http://TWiki.org/p/pub/TWiki/TWikiLogos/twikiRobot46x50.gif
_You can locate the graphic more precisely by typical means (include in a
table, specify a border, etc., etc., etc. (I don't do this often, so don't
really know the details)._
---++++ Headings
The above is a Level 2 heading, I rarely use a Level 1 heading because the
font is too large for my taste. This could be corrected by the use of an
appropriate CSS stylesheet.
---++++ Table of Contents
I've already included the markup above, I'll repeat it here in "raw" form (the
<nop> keeps it from being "rendered" by the TWiki engine). _Similarly, my
occasional use of HTML entities (&lt;) is so that the relevant text is
rendered by the TWiki engine._
%<nop>TOC%
---++ A Proposal
I make this very vague proposal (intentionally so at this point). With a wiki
(TWiki) we instantly (well, more below) have a tool that can be used for any
purpose we choose:
* If one or more of us want to write HOWTOs on TWiki (WikiLearn) simply
register (so you can edit), create a page 10 seconds or less when you know
how and are at the right place -- the simplest, point your browser at (i.e.,
go to) http://TWiki.org/cgi-bin/view/Wikilearn/WebChanges, then, in the
address bar, delete "WebChanges" and replace it with the name of your desired
page (without spaces, you could include spaces in the form (IIRC), %20%, but
you'll probably cause yourself a lot of grief.
* If one or more of us want to comment on a particular HOWTO (Al Dev's),
someone can start a page with an appropriate name, and any of us can add to
it. (I could, for example, paste David Lawyer's comments about the C++
Programming HOWTO to a page named CppProgrammingHowToComments as a start.)
* If we want to keep lists of the HOWTOs and their status, simply create a
list in plain ASCII text and consider adding some markup to each line to make
it appear as a list (bulleted or numbered), table, or spreadsheet (table with
math capability, in my own words).
* If you want to pay attention to what others have recently done on the
site, view the [[http://TWiki.org/cgi-bin/view/Wikilearn/WebChanges][Web
Changes]] page (normally created per web, but a new version (I'd have to look
for it) can display the changes for multiple (or all) webs.
* Want to have a page for each HOWTO with some data and statistics, but
then summarize the data on a separate page? Use the "structured search"
capability, in combination with a form and maybe a spreadsheet. (I'm being a
little vague here, I think quite a bit can be done here, but I don't do that
much so am uncertain about the limitations. Of course, TWiki is GPLed and
written in Perl, so if we run into a restriction we can attempt to fix it or
interest one of the developers in helping us.
* More?? (Yes, I'm sure.)
---++ WikiLearn
I should say a little more about WikiLearn, from a few different angles:
* WikiLearn is a single web on TWiki's "home" website, which is (currently)
maintained on SourceForge. If we want to (experimentally) move forward on
some of these "proposals" I would propose that we do so on WikiLearn.
<blockquote>
_There are some caveats:_
* the SourceForge site is, IMHO, overloaded, and things can be slow. Peter
Thoeny (the originator and lead developer) is planning to move to another web
host "real soon now".
* WikiLearn is sort of "my" TWiki. I plan to move to my own site sometime
soon (starting from three years ago ;-). If WikiLearn was on its own site, I
would add many more webs to provide segregated spaces for different subjects,
for example, Linux, Cpp, C, Perl, whatever. A dedicated TWiki site for LDP
might (or might not) find it helpful to have separate webs for various
purposes, possibly a web for each HOWTO. _A hierarchical arrangement of webs
is possible even with TWiki as it exists today, but is not really supported,
so I wouldn't immediately recommend that. I once knew some of the gotchas
but I'd have to do quite a bit of digging to recall them._
* ???
</blockquote>
* I created, and continue to work on WikiLearn, as my "open" learning
notebook. In other words, in some sense as an alternative to the LDP. (I
could write a lot about this, and have on other public or private posts or
TWiki pages, and probably will write more as part of this or related
dicussions.) For now, one occasion for creating a WikiLearn page is when I
need (want) to learn something. I start a WikiLearn page and than start
copying and pasting in quotes (properly (or at least reasonably) attributed,
I hope), links, notes in my own words, etc. Then as I start to understand
the subject, I try (hope?) to revise the page to make more sense to me, and
hopefully, more sense to others. (See the WikiLearn page [[About These
Pages]].)
_Aside: The intended official name is WikiLearn, the domain will be
wikilearn.org, but the webname on twiki.org is Wikilearn because wikiwords as
web names create some problems, which I don't recall — but, if I was
true to the spirit of WikiLearn, if I'd search WikiLearn, I'd find a page to
refresh my memory._
_Aside: As I stated, WikiLearn is in some sense an alternative to the LDP's
HOWTOs, and is not intended to be my private or personal project. Although
WikiLearn gets some participation from others (see [[Web Statistics]]), I
welcome additional participation in any form._
---++ Closing
I won't call this the conclusion, for a variety of reasons, but I do want to
stop writing for now (partially because I have to leave now), so I'm rushing
a little.
I'm actually going to create two pages on WikiLearn to contain this content:
* http://TWiki.org/cgi-bin/view/Wikilearn/TWikiAdvocacyForTheLdpRaw (which
I might write protect, so that anyone can see exactly how this content looked
when simply pasted to TWiki)
* http://TWiki.org/cgi-bin/view/Wikilearn/TWikiAdvocacyForTheLdpRaw (in
fully editable form, so that, if anyone wants, we can continue this
discussion)
regards,
Randy Kramer
<!--
---++ PS: Write Protection
PS: The following will make the raw web page "write protected" (well,
actually, I may need to have someone test this — I don't use it often
and I may need to add something like a "deny all" line before the allow
line).
* Set ALLOWTOPICRENAME = Main.RandyKramer, Main.TWikiAdminGroup
* Set ALLOWTOPICCHANGE = Main.RandyKramer, Main.TWikiAdminGroup
Note that this is not necessarily the most foolproof security in the world.
;-)
And, I can hide this entire note on the TWiki page by enclosing it in HTML
comment tags (as I've shown here (with HTML entities, but since they are
entities, they will not take effect).
-->
---++ PPS: WebForm
When you see this on the web page, you'll see a very simple version of a web
form (only one field) below and to the left. When I edit the page, I can
select from a number of possible entries ("Scribbles", "Collecting Notes",
etc.) from a drop down menu. (The possible entries are set up when the form
is created, a somewhat cumbersome process (probably because I've only done it
once).
Oops, and finally, just to show that *bold face is easy to markup.*
