LDP WikiText Editing HOWTO

David Merrill

david -AT- lupercalia.net

2002-01-28
Revision History                                                             
Revision 1.1           2002-01-28            Revised by: dcm                 
Added QandASet section, had to tweak the grammar for filename markup.        
Revision 1.0           2002-01-23            Revised by: dcm                 
Initial release.                                                             


This HOWTO explains how to use the LDP WikiText editing format to create
DocBook documents for the LDP.

-----------------------------------------------------------------------------
Table of Contents
1. Legalities
2. Introduction
3. What Is a Wiki?
4. Why Would I Want to Use One?
5. How Does It Work?
    5.1. Sections
    5.2. Lists
    5.3. Links
    5.4. Filenames
    5.5. Emphasis
    5.6. QandASets
    5.7. Fancy Stuff
   
   
6. But What About the Meta-Data?
7. Where Is It? Can I Get Access?
8. Conclusion

1. Legalities

This document is copyright &copy; 2002, David Merrill, and is available under
the term of the GNU Free Documentation License, with no invariant sections,
no front-cover matter and no back-cover matter.
-----------------------------------------------------------------------------

2. Introduction

The LDP uses DocBook format for our new documents, and we are trying to get
our older documents also converted into DocBook. Unfortunately, DocBook is a
very large and complex DTD, so it can be difficult for people to use. We are
always looking for ways to make it easier, so more people can help the LDP.

The solution we came upon was inspired by the WikiWikiWeb, thanks to a great
suggestion from LDP author Martin Wheeler. I call it WikiText, because it
isn't a true Wiki, but it has some of the best features of a true Wiki.
-----------------------------------------------------------------------------

3. What Is a Wiki?

A Wiki is a kind of a website, where anyone who is reading the site can also
edit it. While the LDP isn't going to implement that kind of permissive
editing, we do really like the way the Wiki editing works. Instead of having
to learn html tags, you enter your information in plain text. The Wiki
software takes that plain text, and converts it into html to display it.

In our case, we convert not into html, but into DocBook. Then that DocBook
gets fed into our regular publication systems just as if you had written it
in DocBook originally.

If you've never used a WikiWikiWeb, see http://www.wikipedia.com for a good
example of a thriving Wiki.

Common functions like creating a link, a bulleted list, a numbered list, and
section headings are made quick and easy. We wanted to provide that same
level of ease for LDP authors, so I wrote a utility that would take a text
format similar to the one used in Wikis (we call it WikiText), and combine it
with the meta-data in the LDP Database to generate DocBook.
-----------------------------------------------------------------------------

4. Why Would I Want to Use One?

Here are some reasons:

 1. It's quick and easy. No fancy tags to learn, only a few simple text
    "hints".
   
 2. It's powerful. While you can edit WikiText without using any DocBook at
    all, you can also use any DocBook tag inside it.
   
 3. It versions. A complete version history of your edits is maintained in
    the database. You can revert to a prior version if you didn't like
    something you did. You can do this also with cvs, but it is much easier
    in the online system.
   
 4. It shares documents. Authors who work on documents with other authors can
    collaborate through the WikiText. Yes, cvs also does this, but again
    WikiText is simpler.
   
 5. It's accessible. All you need is any web browser and an LDP Database
    account.
   
 6. It's WYSIWYG. There's a "Preview" feature, so you can click the "Preview"
    button and see how your document will look on the LDP site. There are no
    utilities to run, nothing to learn, no DTDs to install or catalog files
    to munge with. If you've ever tried to get a working DocBook system on
    your machine, you will appreciate this! :-)
   

-----------------------------------------------------------------------------
5. How Does It Work?

We tried to use the same text hints that are used on the Wikipedia, which
came from UseModWiki. There are some differences between different Wiki
systems, but most of them are quite similar to this one, and it has proved
itself through use.

A blank line separates paragraphs, and there are other hints for making
sections, bulleted lists, links, filenames, etc.
-----------------------------------------------------------------------------

5.1. Sections

=Introduction|intro=                                                         

creates a new top level section. See the pipe character followed by "intro"?
Many hints provide for an "id", and this is how you supply it. For sections,
the id will become the output filename (intro.html, in the first example), or
the html "tag" used for intradocument linking.
==How Does It Work?|how-does-it-work==                                       

creates a second-level section, and
===Why Would I Use It?|why?===                                               

creates a third level section.
-----------------------------------------------------------------------------

5.2. Lists

5.2.1. Numbered Lists

#one                                                                         
#two                                                                         
#three                                                                       
/#                                                                           

The "#" prefix says to make a numbered list. The numbered list continues
until the end of the current section, or until it hits a line with only "/#",
which closes the list. After opening another "#" list, the numbering will
begin over again at "1".

Here is how the above block will appear in the final document:

 1. one
   
 2. two
   
 3. three
   

-----------------------------------------------------------------------------
5.2.2. Bulleted Lists

Bulleted lists work almost the same, except you use the "*" hint, and you
don't have to worry about renumbering issues:
*one                                                                         
*two                                                                         
*three                                                                       
/*                                                                           

Here's how the above block will appear in the final document:

  * one
   
  * two
   
  * three
   

-----------------------------------------------------------------------------
5.3. Links

Use the square brackets to identify links, like this:
[[http://www.linuxdoc.org|Linux Documentation Project]]                      

In this case, the text after the pipe character isn't an id, but the "title"
of the link.

There are two special namespaces that you can use besides the standard "http:
" and "mailto:" namespaces that you are probably famliar with. The first is
the "ldp:" namespace. Look at the following link:
[[ldp:Distributions-HOWTO]]                                                  

When you use the "ldp:" namespace, WikiText will look up the document that
you named in the LDP database, and generate a link to it.

Note: we're still working on entering the correct "name" in all of our
database records, so only a few are working. But don't worry. Just let us
know if you need to use a link that isn't correct yet and we'll fix it right
away.

The second special namespace is the "wiki:" namespace. It will generate a
link to the article on the Wikipedia, an open source encyclopedia project. We
hope to mirror some of the most appropriate articles from the Wikipedia right
on the LDP. Wikipedia has many great articles on computer related topics that
aren't the kind of information we do at the LDP, but which would complement
our documents very well. For instance, there are articles on virtual memory,
operating systems, and so on. For now, your link will go to the live
Wikipedia site. Eventually, it will go to a mirror on our site, but with a
link to the "real" site.

The following links go to articles called "Operating system" and "Linux
kernel" on the Wikipedia:
[[wiki:Operating system]]                                                    
[[wiki:Linux kernel]]                                                        

Wikipedia is a great resource for all Netizens. Both the software they use
and their content are open source.
-----------------------------------------------------------------------------

5.4. Filenames

You can indicate filenames by wrapping them with double brackets, just like
http and other links. Or, you can specify the "file" namespace:
[[/etc/apache/httpd.conf]]                                                   
[[file:/etc/apache/httpd.conf]]                                              

Either way, it will render as /etc/apache/httpd.conf.
-----------------------------------------------------------------------------

5.5. Emphasis

You can make certain words emphasized by wrapping them with three (3)
single-quotes, like this:
'''Wow!'''                                                                   

That will render like: Wow!
-----------------------------------------------------------------------------

5.6. QandASets

You can create question and answer sets if you're writing a FAQ, or if you
have a FAQ section in your document. Just make "Q:" and "A:" the first
characters on a new line, and the QandASet tags will automatically be
created.
Q: What if you want to do DocBook that isn't supported by WikiText?          
                                                                             
A: Mu.                                                                       

And this is how the example renders. Notice that a list of questions appears
right before the first question. This looks a bit silly in this example,
since there is only one question and it just gets repeated twice. If you're
working on the Linux-FAQ, though, it's really nice.

Q: What if you want to do DocBook that isn't supported by WikiText?

Q: What if you want to do DocBook that isn't supported by WikiText?

A: Mu. See the next section.
-----------------------------------------------------------------------------

5.7. Fancy Stuff

There is no DocBook structure that is not supported by WikiText. Why? Because
if there is no WikiText for it, you can just put the tags you need directly
into the document, and they will work.

There are a few "special" tags that are not inline DocBook, but section
structures, among them the "programlisting" and "screen" tags. You should
keep in mind that none of the WikiText functions will work inside these tags.
You don't want commented lines in your code sample converted into numbered
lists, do you?
# this is a comment                                                          
# it is NOT a numbered list!                                                 
-----------------------------------------------------------------------------

6. But What About the Meta-Data?

You do not need to enter any articleheader or articleinfo information into
your document. That information is pulled directly from the database itself.
Go to your document's edit page, and enter the appropriate information there.
-----------------------------------------------------------------------------

7. Where Is It? Can I Get Access?

Any LDP author is welcome to use the WikiText. It is on the LDP database, 
http://db.linuxdoc.org. You will need to have an account on the database. If
you don't have one yet, you can request one from me by email. Send me your
full name (as it appears on your documents), username and password, and I
will set it up for you, probably the same day.

Once you're logged onto the database, click "My Documents". If you don't see
a list of your own documents (only), I messed up. :-)

Click the document you want to edit. You will see a page that shows the
meta-data we have for the document. Also on that page is a link to WikiEdit.
Click it, and you're on your way.

Click "Preview" to see how your document will appear on the LDP (except that
it will be rendered in a single page).

Click "DocBook" to see the raw DocBook that WikiText generated from your
text.

Click "Save" to save your changes to the database. You can also add a
"comment" to it, for future reference.

Click "Version History" to see a record of all the changes you've made to the
document.
-----------------------------------------------------------------------------

8. Conclusion

We hope that you will find the WikiText helps make your life as an author
easier, so you can concentrate on writing the best documentation possible and
spend less time fudging with your tools and learning arcane syntax.

I would very much appreciate any feedback or suggestions from you, whether
positive or negative (as long as it's constructive, of course). You can write
me at david -AT- lupercalia.net.
