Subject:
Re: Cheat sheet
From:
Randy Kramer ####@####.####
Date:
10 Apr 2001 23:25:46 -0000
Message-Id: <3AD3961D.4F77@fast.net>
I suspect Gary will respond to you and answer particularly for the wiki
software he is using. I thought I'd answer partially about the wiki
software I plan to use, TWiki.
Nik Clayton wrote:
> 1. How easy is it do revision control, see diffs between pages,
> branches, and named tags?
>
> This is *especially* important if you have translation efforts, who
> need to easily be able to see what's changed between revisions to
> make translating easier.
>
Many wiki engines, including both TWiki and the wiki engine that Gary
uses can display a diff between the current revision and the previous
revision. Some go further back. TWiki keeps a copy of each revision
(stored in RCS) and can display sort of a diff history -- the diffs to
the previous version, then the diffs to the next version back, then the
next version back, and so forth. Gary's wiki numbers the revisions, so
it might keep the total history. Some wikis allow you to request a diff
between two arbitrary versions.
All of the preceding is based on the wiki page keeping the same name.
If they change names, things become a little more difficult.
TWiki stores the current page as a plain text file, one file per wiki
page. The revisions are in RCS. Someone with administrative access to
the TWiki can do fancier things using RCS and the plain text files.
> 2. How easy is it to produce multiple output formats from your data:
> HTML, Postscript, PDF, and so forth. I expect this to be the sort
> of information that people will want to review without being in
> front of the computer. Relying on printing web pages isn't
> suitable.
The first answer is not easily -- they don't have anything built in like
the DocBook stuff or anything like that. TWiki does have, in one of its
versions, a template with a print button to print a "printer friendly"
version of what is displayed on the web (it may be in one of the alpha
versions, the next production release is planned for early May).
I think the big advantage of a wiki is the collaboration that is
inspired. I start a wiki page on some subject, you look at that page
and realize I've made an error. You don't send me an email, you click
on edit and fix my mistake. I won't go into a discussion here about
thread mode vs. <the other mode?>, but, if the page gets messy because
of serial editing, hopefully someone takes it upon themself to edit the
page and make it neater, more correct, easier to read, whatever.
I would suggest that the wiki be used until the information is fairly
stable. Then, if appropriate, move it into DocBook or something similar
to create multiple output formats.
Waiting for the information to be fairly stable is not intended to be a
criticism of someone that makes the first draft. Instead it should be
an encouragement to anyone to jump in and make that first draft.
What you wrote in your first email would be a very acceptable first
draft to put on a wiki page:
NFS
To configure a host as an NFS server:
RedHat Linux: Do foo, bar, baz.
Debian Linux: Do bar, baz, foo.
FreeBSD: Add 'nfs_server_enable="YES"' to /etc/rc.conf
To configure the list of exported filesystems:
Linux: Edit /etc/mumble, see mumble(5) for details.
FreeBSD: Edit /etc/exports, see exports(5) for details.
and so on and so forth. Very short, simple answers, with pointers to
more information as necessary.
I might come along and say this looks good, but under RedHad Linux the
steps really are: <whatever> (because maybe I know RedHat Linux). Maybe
I think we also need the procedure to configure a Samba server, so maybe
I add lines like:
Configure a Samba server:
RedHat Linux: ???
Debian Linux: ???
Best Linux: Do bar, foo, baz
(Because maybe I know how to do it in Best Linux, but not in anything
else.)
When enough people have contributed, most of the blanks are gone, and
there is reasonable certaintly that most of the words are correct.
Sometimes it's not just correctness, but how to say something for
easiest understanding. Maybe I can explain how to do something in four
paragraphs (because I just barely know how to do it, or just barely
understand it). Someone else comes along and realizes that I could have
said the entire second paragraph in one four word phrase. They fix it.
Sometime after this has occurred, it's time to think about "publishing"
the information.
>
> 3. Is it possible to do editing offline, and then sync up changes
> when you get online. Not everyone has a permanent Internet
> connection (or a cheap dial-up), and I do some of my best work sat
> in airport departure lounges.
Yes, the ease of doing so depends on the wiki. Cutting and pasting is
possible but an ugly solution. With TWiki I know that I can copy the
plain text files and edit them off line, and then replace the on line
text files. I don't immediately know how that will affect the RCS
archive. TWiki is planning on providing mechanisms to take copies of a
TWiki for offline viewing and editing. I don't have any idea what the
schedule is for this, but I'll try to dig into this over the next
several days.
>
> 4. Is it possible to maintain local a mirror of the wiki content, and
> sync up to it in an efficient manner?
Yes. Much of the answer is similar to the previous answer. Some wikis
are mirrored. I'm not too familiar with these and don't think they've
worked out a good solution for syncing. A simple minded approach is to
make the mirrors read only, and force (or request) editors to edit the
original. Then there is the issue of the time lag until the mirror
again matches the original.
>
> 5. Is it possible to 'tag' the content in some way so that different
> views of the same data are possible? For example, someone with
> Debian and FreeBSD boxes in their datacentre will only want to see
> the entries relevant to these two systems. Someone else with
> NetBSD, RedHat, and Solaris will have different requirements.
I don't know of a "built in" facility for this purpose. There should be
some creative solutions that can address this. Maybe a page to list the
question, separate pages to list the answer for each system, and the
reader then calls up pages relevant to his system only? It probably
sounds cumbersome, and it would be somewhat cumbersome, but wiki pages
are generally very lightweight, usually (but not always) text only.
Hope this helps,
Randy Kramer
