319 lines
13 KiB
Plaintext
319 lines
13 KiB
Plaintext
|
LDP WikiText Editing HOWTO
|
|||
|
|
|||
|
David Merrill
|
|||
|
|
|||
|
david<EFBFBD>-AT-<2D>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:
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>one
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>two
|
|||
|
|
|||
|
<EFBFBD><EFBFBD>*<2A>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.
|