319 lines
13 KiB
Plaintext
319 lines
13 KiB
Plaintext
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 © 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.
|