I started this page to advocate the use of a wiki (specifically TWiki) by the LDP
for a variety of purposes. In other words, to suggest some possibilities and/or features, let them recognize the flexibility, and then use it to advantage.
After writing a first draft, I felt it was one of my better efforts at trying to explain and advocate TWiki, so I decided to preserve, refine, and expand it.
Maybe I want to mention something about my writing / learning philosophy, and try to assert a claim that I can write reasonably well (despite some of the writing that I know is bad on Wikilearn) — to hit some of the high spots, you have to know your subject well to write well, and (since Wikilearn is a learning notebook) I don't always know the topics I try to write about very well, at least when I start writing. My hope / intent is to come back and rewrite them after I've learned more, but I have to admit that hasn't always happened (and I'd add a "yet" since I'm not dead yet). And I was, and still am, hoping to get more people interested in this effort, maybe someone can learn something a little faster because of my really poor notes, and improve those notes as they recognize shortcomings while trying to use them.
It is currently in an unfinished, intermediate condition. I've started (but not finished) a list / outline of things that I think I need to address, and started to address some of those.
Intro to this Revision
I wrote this rather quickly to provide an introduction to TWiki for "members" of the LDP in an effort to advocate the use of a TWiki. There were quite a few things I didn't cover, and, for a few reasons I feel the need to either revise this document to be more complete and correct, or provide links to sources of more complete and correct information. These reasons include:
- this seems like one of my better starts in explaining / advocating TWiki, so I don't want to waste it
- I don't want to leave the LDP with the wrong (or incomplete) impressions I might have created with the first version of this document.
Before I make changes, I'll start an outline (i.e., bulleted list) of some of the things I think I should cover.
Outline of Desirable Changes / Additions
ok, there are probably other things, but I'm going to start making some changes, starting by "normalizing" this page to include Wikilearn's WebTopicEditTemplate.
Hmm, will I scare people away with the template and all these possibilities? Maybe — remind them:
- discuss the 60 minute lockout, and some consequences (including its effect on revisions and how to "force" a revision)
- links to some pages that include TWikiDrawings (some "real" and some sample for testing) — mention the Sandbox web
- (direct) links to other pages with (rather than "indirect" via about these pages:
- explanations of the wiki way, etiquette, and ethics (?)
- more complete lists and explanations of the TWiki markup, including
- WikiLearn's Web Topic Edit Template and Web Topic Edit Templates (including the thing that prevents automatic linking (requires the double square bracket markup)
- Finish the allowable variations of a TWiki link (started in the original document "too much detail")
- Email notification of changes
- At least mention some of the other things that exist but which I may not use, like:
- RSS (?) feeds
- TWiki "applications" like bug tracking, to do lists, ???
- Provide a link to (some) pages about the Motorola (IIRC) book writing stuff
- The list quirks (multiple bullets on a line, loss of numbering continuity) and the workaround(s?) <br />
- No universal wiki markup (mention my problem with TWiki heading syntax (for Nedit folding)
- Codev.WikiText => DocBook (and the wish for vice versa)
- Offline editing and (my ) NmTWikiFold macros for Nedit
- Wikilearn's WebTopicEditTemplate, identify features and reasons
- the noautolink (??)
- resource section
- email markup
- this revision (future modification to WebChanges) (revision comments?)
- robots and Google??
- demonstrate diffs and ">" — have the reader try these out (as well as more and view raw text, maybe others)
- You can simply copy and paste plain (ASCII) text to a TWiki page, leaving a blank line between paragraphs and get reasonable results. (And, in the wiki way, someone can come along later and, just like they might fix a grammo or typo, add something you overlooked, fix a mistake, clarify something, they might also improve the markup. Next time you view / edit the page, you'll learn something by "osmosis" (i.e., painlessly).
- Let them start a (Sandbox) page (on this web) so they see the WebTopicEditTemplate helping them (I hope )
Snippets of Text to Add
60 Minute Lockout
Twiki has a few features and (intentional) quirks related to editing and revision control, some of which result in some unexpected quirks. (And some of which can be adjusted by setup "controls" accessible to the TWiki administrator.)
Although there are some workarounds, and the administrator has a choice in setup, I prefer to have TWiki configured so that you must register to edit. (And, on twiki.org, Main.PeterThoeny (oops, there's (see the raw text) a quirk I should discuss), prefers that people register with their real name or a reasonable variation thereof (rather than a possibly "wierd" handle. (Oops, time to leave)
On Tuesday 11 November 2003 04:57 pm, Rodolfo J. Paiz wrote:
> 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?
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 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").
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).
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).
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 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.
Let me add a table -- see what this looks like on the referenced page.
|| numbers or
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.
Many graphics can be added by just including a (valid) URL on the page -- this should appear as the (old, but current) TWiki logo:
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).
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 (<) is so that the relevant text is rendered by the TWiki engine.
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 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.
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.
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.
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.
- 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.)
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:
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).
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.
- () Main.RandyKramer - 12 Nov 2003
- If you edit this page: add your name here; move this to the next line; and if you've used a comment marker (your initials in parenthesis), include it before your TWiki.WikiName.