Munch 'N' Learn - 2006-12-09

[Paul W. Frields]

Here's the raw log from Saturday's session.  It was a trickle-in
attendance for a variety of good reasons, so we didn't get to cover as
much as we hoped.  I would like to do another one soon -- votes for date
and time accepted!

= = =
<stickster> OK, on to XML... Have you both seen HTML, for example, by
using Ctrl-U (view source) in Firefox?
<jmbuser> yes
<stickster> XML is just another markup language, and in fact it looks
remarkably similar
<dtypos> yes
<stickster> XML itself doesn't tell you what kind of tags (like <this>
or <that>) you can use -- HTML is actually more specific, because it's a
document type unto itself
<jmbuser> ok
<stickster> XML is just a specification for marking up things.  DocBook
XML is a specific document type -- like HTML -- that is VERY widely used
in the Linux world for documentation
<jmbuser> That is certainly true
<stickster> This is because it is plum full of incredibly useful ways to
mark up your writing, so that you can tell a command-line instruction
from an application name, or a procedure from an itemized list
<stickster> It was an XML document type written specifically for
producing technical documentation
<stickster> If you want to write in XML -- ANY XML document type -- you
should try to use an XML-aware editor
<jmbuser> ok
<stickster> There are many available, like Kate and Quanta for KDE,
Conglomerate for GNOME, jEdit... many others.
<stickster> Many long-time command-line junkies use a text terminal
style editor; Karsten and I both prefer Emacs, and Tommy and some other
folks prefer vi
<stickster> It's a purely personal choice
<stickster> But using an XML-aware editor makes writing in DocBook (or
any) XML *much, much easier.*
<stickster> Let's do a quick tutorial on some easy editing in Emacs as
an example.  Would that be OK?
<jmbuser> sure
<dtypos> +1
<stickster> OK, if you don't have it installed, get it with the
Add/Remove Software tool.  Otherwise, just start it up from your GUI
menu, or type "emacs" at a terminal.
<stickster> Oh crap
<stickster> I forgot one other thing
<stickster> Quit emacs, sorry about that
<jmbuser> ok
<stickster> Do this:   su -c 'yum install psgml'
<stickster> That's a great add-on package that's highly recommended for
this next part! :-)
<stickster> Let me know when you're ready
<stickster> Once it's installed, just fire up Emacs again
<jmbuser> i'm running rpm -qa | grep psgml to see if it's installed
<stickster> jmbuser: You can actually just do "rpm -q psgml" which is
usually faster
<dtypos> it was already installed for me
<jmbuser> I'm installing it now,,,
<stickster> OK
<stickster> Obviously I can't teach all of Emacs in the time we have
today, but I will teach you some "survival skills" with the
understanding that we are focusing on the XML and not Emacs
<jmbuser> working...
<stickster> A very important key in Emacs is Ctrl-G (usually abbreviated
as C-g in Emacs documentation)
<stickster> If you're stuck at a prompt and you don't know what to do,
C-g will abort it
<stickster> The next most important keystroke is how to get out of
Emacs, which is C-x C-c
<stickster> OK, everybody ready to start a document?
<dtypos> yes
<jmbuser> sorry for my sloooowww connection - proceed and I'll catch
up :-)
<dtypos> no problem for me waiting a bit
<jmbuser> almost there
<stickster> jmbuser: It's OK, catch-up will be fast once you have the
package
<stickster> Emacs (and most other editors like vi and such) are VERY
customizable
<stickster> We haven't done any of that, so we'll manually tell Emacs
that we are going to be writing an XML file
<stickster> First, hit Ctrl-x, Ctrl-f (C-x C-f), which means "open a
file"
<stickster> The prompt at the bottom starts you off at your home
directory "~/"
<stickster> Add to that a file name; in this case let's use
"docbook-test.xml"
<stickster> Note that on the status bar, one line above the bottom, the
new mode "SGML Fill" appears
<vnk_fd> 1Q2w3e
<vnk_fd> oops
10:39  * stickster hates it when he types passwords in IRC buffers too
<jmbuser> john looks away hurriedly
<vnk_fd> \sorry I'm late guys
<vnk_fd> had to go out
<jmbuser> installed psgml!
<stickster> Emacs has many "modes," which basically are ways of mapping
keystrokes and other behavior in a special way for each type of file
<jmbuser> applications > programming emacs text editor
<stickster> jmbuser: +1
<stickster> So for example, there's a C/C++ mode, a Python mode, etc....
<stickster> vnk_fd: Make sure you have emacs and psgml packages
installed, then open a file with Ctrl-x Ctrl-f
<stickster> Call the file "~/docbook-test.xml" and you'll be caught up
<stickster> SGML mode is... OK, but it's not exactly what we want
<stickster> Let's just tell Emacs that we want XML mode in particular
<jmbuser> sorry c-f, c-c gives me find file
<stickster> jmbuser: Ctrl-x, Ctrl-f
<stickster> Read carefully :-)
<stickster> Find file: is the right prompt though
<stickster> Just enter a new file's name and that is what opens
<jmbuser> that's what i meant
<stickster> Ah, very good then
<jmbuser> ok
<stickster> Hit Alt-x  (which is abbreviated M-x in Emacs docs, the M
stands for "Meta")
<stickster> M-x means "run this Emacs command"
<vnk_fd> ok, done
<stickster> For the command, type "xml-mode" and hit Enter
<vnk_fd> xml-mode
<stickster> Note that the mode has changed to the proper "XML Fill" mode
<jmbuser> ok
<stickster> Now, normally all this would be in a startup config file,
and you wouldn't have to do it. But we're starting very fresh :-)
<stickster> So, for the first line of the document, type (or copy and
paste) this:
<stickster> <?xml version="1.0" encoding="UTF-8"?>
<jmbuser> ok
<stickster> That's a very standard XML declaration that appears at the
top of most XML files.  It's like a "magic string" that tells lots of
XML-aware programs and shell utilities what the file content is.
<stickster> Now, add this next line:
<stickster> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML
V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd">
<stickster> (Copy and paste is a good idea) :-)
<jmbuser> works for me
<stickster> Once you hit "Enter" after the second line, some stuff may
happen in Emacs, yes?  A "Parsing prolog" prompt, probably
<jmbuser> wow
<stickster> I don't know if you'll see color, but I do here, maybe
because of my particular configuration
<jmbuser> ended with fontifying done
<stickster> Disco
<dtypos> +1
<stickster> Let me tell you about a reference for you to read after
we're done...
<jmbuser> red & green
<jmbuser> ok
<dtypos> ok
<stickster>
http://cvs.fedora.redhat.com/viewcvs/example-tutorial/en_US/example-tutorial2.xml?root=docs&rev=1.1&view=markup
<stickster> That's the start of a self-documenting DocBook XML file.  If
you read it later, it will likely answer a lot of beginner questions
about why things look the way they do in a DocBook XML file.
<jmbuser> ok
<stickster> For now, let's just start our own document
<stickster> (Sorry, I keep getting phone calls)
<stickster> To insert an element, hit C-c C-e
<stickster> Notice that Emacs already knows the top-level element is an
<article>
<stickster> Because we told it so in the DOCTYPE declaration
<stickster> Just hit Enter to confirm
<stickster> Notice that a big comment block appears, telling you all the
things that are legal to use here
<jmbuser> yeah!
<stickster> There may be an even faster way to do this, but what I do is
hit the following keys:  Home, C-k
<stickster> C-k "kills" to the end of the current line, so it gets rid
of that whole comment
<stickster> Don't worry, I'll show you how to get that list back in a
more useful way
<jmbuser> done
<stickster> Hit C-c C-e again to "insert element"
<dtypos> ok
<stickster> Now you get a prompt with nothing filled in, because there
are many choices you can use
<stickster> If you hit the Tab key, you'll see a list
<stickster> Keep hitting Tab to scroll the list -- when you reach the
end and keep hitting Tab, it starts over again at the top
<stickster> Once you see what you want, you can type the first few
letters and hit Tab again for auto-completion
<stickster> Let's insert a title.  Type "tit" and then hit Tab to
complete
<jmbuser> works
<stickster> Notice logically what we are doing -- declaring a title for
our article.  Makes sense, right?
<jmbuser> sure
<stickster> Note that the cursor magically puts itself right where you
need to type
<stickster> "My Test Article"
<stickster> (Without the quotes, sorry)
<stickster> Now hit the End key to move to the end of the line, and hit
C-c C-e again to insert another element
<stickster> Tab will get you that magical list
<stickster> Let's just put in a paragraph, so type "para" (or "pa", Tab)
to insert it
<jmbuser> ok
<stickster> Now type some stuff in the middle.  Don't worry about
anything except typing.  Emacs will take care of wrapping and everything
else for you.
<glezos> hi all. sorry for being late.
<stickster> glezos: np, but I am almost out of time
<glezos> stickster, if I can be of any help, just tell me.
<stickster> OK, does everyone have some information in their <para>
element now?
<jmbuser> yes
<dtypos> ok
<vnk_fd> ok
<stickster> To save and exit, you can either use the GUI menu if you're
a loser (HAH! jk), or the following keys:  C-x C-s  to save the document
<stickster> And then (remember?) C-x C-c to quit Emacs
<stickster> Congratulations, you just wrote your first DocBook XML
document!
<jmbuser> done
<jmbuser> cool
<dtypos> fine
<stickster> Now, here's some stuff you can do to check your work.
(Normally, you would do this inside Emacs, but we're trying to keep it
simple for now.)
<stickster> Open a terminal
<stickster> We're going to "validate" our document -- that is, check
that not only have we written correct XML (where every open <tag> has a
closing </tag>), but that it follows the DocBook specification properly
<stickster> We can use the xmllint command for this
<stickster> Type this command:
<stickster> xmllint --noout --valid docbook-test.xml
<stickster> You should get no output, which means your document is
valid!
<jmbuser> yessiree
<vnk_fd> valid here
<stickster> xmllint's normal method is to output the r"
<stickster> oops
<jmbuser> oops?
<stickster> xmllint's normal method is to output the result tree, i.e.
your parsed document, but we don't want to see all that, just to know
that it's valid
<jmbuser> got it
<dtypos> valid
<dtypos> (no outpout)
<stickster> Now let's turn that DocBook into HTML -- use this command:
<stickster> xmlto html docbook-test.xml
<stickster> You should get the following output: "Writing index.html for
article"
<stickster> Then fire up your Web browser and point it at
file:///home/<username>/index.html
<jmbuser> true
<stickster> (substitute your username)
<vnk_fd> done
<dtypos> nice
<stickster> Lookee there, we just built HTML out of our DocBook article!
<vnk_fd> that's default docbook style?
<jmbuser> It's alive!
<stickster> The ONLY difference between what we all just did, and what
FDP does with its toolchain, is a matter of document length, some
stylesheets, and automation.  The concepts are exactly the same.
<stickster> vnk_fd: correct
<jmbuser> ahhh
<vnk_fd> ah get it - our styles are in docs-common in cvs?
<stickster> vnk_fd: Exactly!!!
<stickster> That's where all the pieces that do our specific building
are
<vnk_fd> too easy, just to learn tags, then
<stickster> Including XSL (XML Stylesheet Language) templates that alter
the XML a bit on their way through the transformation process
<jmbuser> templates, you say?
<stickster> vnk_fd: That's all you have to do -- and most people only
learn the 15-20 elements/tags they use all the time
<stickster> jmbuser: Yeah, XSL is cool but unfortunately I'm out of time
for today
<jmbuser> stickster: thanks for the tutorial
<stickster> The reason we like XML so much over the wiki is that the
wiki only has, what? like, ten or so tags you can use, total
<dtypos> thanks very interesting lesson indeed
<stickster> DocBook has over a hundred, I think
<jmbuser> true
<vnk_fd> stickster: as we go, should we send questions directly to you
or to the list?
<stickster> vnk_fd: To the list, please
<jmbuser> ok
<vnk_fd> ok
<stickster> vnk_fd: I will definitely answer anything I can, and it will
help other people too
<dtypos> o
<dtypos> ..k
<vnk_fd> all right
<jmbuser> sounds good
<stickster> Don't worry if you don't like or get the hang of Emacs...
feel free to use what you want.  I think Emacs rocks, but to each his
own
<dtypos> thanks again
<stickster> Use what makes you happy
<stickster> But definitely use DocBook! :-)
<stickster> All right, ciao everyone
= = =


-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
       Fedora Project Board: http://fedoraproject.org/wiki/Board
    Fedora Docs Project:  http://fedoraproject.org/wiki/DocsProject
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20061210/3b774304/attachment.sig>