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
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
