CVS + XML Munch 'N' Learn, 2006-12-04

[Paul W. Frields]

This is the raw IRC log from our learning session last Monday.  Just as
a (very late) reminder, we're having another session today at 1500 UTC
(10:00 a.m. US-Eastern).

= = =

<stickster> For anyone who wants to join in -- you may benefit from
doing the following, if you haven't already:
<stickster> su -c 'yum groupinstall "Authoring and Publishing"'
<stickster> su -c 'yum install gobby cvs'
<stickster> Give me 60 sec here..
<stickster> OK
<stickster> Anyone within the sound of my voice... :-)
<horadrim> installing the Authoring group, gobby and cvs are already
there
<stickster> OK... Run gobby and connect to the following host:
marilyn.frields.org
<BobJensen> stickster: How long are you thinking this will be?
<BobJensen> stickster: I want to take part but not sure if my wife has
other plans for my time
<stickster> ~55 min.
<stickster> I have to be done by then for dinner :-)
<BobJensen> OK
<stickster> All righty then, horadrim, are you good to go?
<stickster> CVS is for revision control. Much like a public library,
many people can check out, examine, play with, and check in materials.
<horadrim> still running the yum update but should be ok 5-10 minutes
for it to finish
<stickster> horadrim: OK, that shouldn't be a problem
<stickster> The normal cycle for CVS is this:
<stickster> 1.  Check out one or more "modules" of
{code,content,whatever}
<stickster> 2.  Make changes in the local copy (on your computer)
<stickster> 3.  Test changes (!!!)
<stickster> 4.  Update to make sure your local copy is fresh
<stickster> 5.  Commit changes to the repository
<stickster> If anyone has questions, just shout them out at any time
<stickster> A checkout is where you take a copy of what's in the
repository onto a locally accessible disk (usually your hard disk)
<stickster> You can do whatever you want to this copy, and nothing
changes in the remote repository until you "commit" those changes
<stickster> When you do an "update," you are asking the remote
repository to send down any changes that may have happened since the
last time you did an update
<stickster> In MOST cases, the changes are simply patched in to your
local copy
<stickster> If the change is unresolvable -- for example, if you made a
local change that is in conflict with an update from the repository, you
get a warning from CVS
<stickster> During an update, you'll see letter codes next to each file
that was changed -- a common code is "U" for something that has been
successfully updated
<stickster> or "P" for something that has been updated with a simple
patch
<stickster> But if you have an unresolvable conflict, you'll see the
letter "C," which means you'll need to visit the file to see what
happened.
<stickster> The changes that couldn't be resolved are bracketed by very
visible <<<<<<< and >>>>>>>> lines
<stickster> I don't want to go too much further until we do a checkout
<stickster> BobJensen, horadrim: Does this make sense so far?
<BobJensen> yes
<horadrim> yes
<stickster> Cool!
<stickster> Since everyone presumably has CVS installed, let's do a
test.
<stickster> Run the following commands:    cd && mkdir -p fedora/docs/
<stickster> And:    cd ~/fedora/docs/
<stickster> Then do this:  cvs
-d :pserver:anonymous at cvs.fedoraproject.org:/cvs/docs co docs-common
mirror-tutorial
<stickster> (that's one line, I don't know if the buffers handle it
right) :-)
<horadrim> it's ok
<stickster> It may take a little while for your system to download
everything
<horadrim> done here
<stickster> Excellent
<stickster> The "-d :pserver:...(blah)..." option is a method of
connecting to the CVS server -- in this case, using an anonymous login.
<stickster> This connection method means you won't be able to commit any
changes -- which is fine for now.
<stickster> The "co" is the CVS command we're running, short for
"checkout"
<stickster> That's followed by the two modules we were choosing.
<stickster> If you didn't know what modules to use, you could try this:
<stickster> cvs -d :pserver:anonymous at cvs.fedoraproject.org:/cvs/docs co
-c
<stickster> That would give you a list of all modules.  It's actually in
a tabular form -- the left-most entry is a module name, and following
that is a list of any alias content.
<stickster> That's not very important, other than to note that it's
possible for a CVS repository to give users a "shorthand" that allows
them to check out a whole bunch of directories at once with a single
module name
<stickster> *: Make sense so far?
<horadrim> yup
<stickster> OK... let's look at the content of a module.  Don't worry
about "docs-common" for right now, although it's full of interesting
things... for later :-)
<stickster> So do:   cd ~/fedora/docs/mirror-tutorial
<stickster> horadrim: Did gobby finish installing?
<horadrim> yes
<stickster> OK, go ahead and run it, and connect to hostname:
marilyn.frields.org
<stickster> The default port should be correct
<stickster> Cool
<stickster> All right, I'm going to load up some documents in there as
we go along.  You'll have copies on your drive now for later reference.
<stickster> OK, I just loaded the "Makefile" file.
<stickster> There are only a couple things you need to write a new
document from scratch -- this Makefile is one of them.  If you decide to
start working with DocBook in CVS, you can copy this file from an
existing module and just make some minor changes.  Everything will then
work auto-magically :-)
<stickster> Everything behind a # is a comment, of course :-)
<stickster> Let's look at the important lines.  They declare some
settings, or variables, for use by the make command.
<stickster> (Oops, I should have made sure people installed "make" with
yum, too.  Well, do it now if you have time.)
<stickster> OK, back to the Makefile.
<stickster> The first variable, "DOCBASE", is the name for the parent
(or main) XML file for your document.  It's considered the Right Thing
To Do to name your DOCBASE, your main XML file, and your module the same
thing when possible
<stickster> Although you'll find a couple places where we've broken that
rule :-)
<stickster> So here, what I'm telling our build tools is that my main
XML document is called "mirror-tutorial.xml".  You just leave off the
".xml" part.
<stickster> The next line "PRI_LANG" declares the _primary language_ for
the document
<stickster> It's usually "en_US" for US English, but that is not a
requirement
<stickster> *: OK so far?
<horadrim> yes
<stickster> BobJensen is busy so I'll assume he's logging :-)
<stickster> OK, next line, "OTHERS", is where we define any other
languages for this document that are to be built.
<horadrim> i'll save the transcript ain any case
<stickster> horadrim: Thanks, I'll be posting it to f-docs-l as well
<stickster> Note that translations for these OTHERS don't happen
magically -- translators have to come in and build "PO" files, which
contain translations for all the strings (text) in the original XML
document(s).
<stickster> So for a document that you're starting from scratch, this
may well be blank, i.e. "OTHERS = "
<horadrim> i know too well the L1ON world
<stickster> very good :-)  I won't belabor that point then :-D
<stickster> OK, the next line, "DOC_ENTITIES" is where you note the name
of any document-specific entity file.
<stickster> An "entity
<stickster> Oops
<stickster> An "entity" is basically somewhat like a "macro" in XML.
It's a way of using a shorthand abbreviation where you mean some larger
bit of text that you don't want to have to keep typing (or risk
misspelling) over and over
<stickster> There are a few different kinds of entities, but the ones we
use a lot look like this:  &FED;
<stickster> They have an ampersand '&' in front and a semicolon ';' at
the end
<stickster> They don't have to have an all-caps name, but it helps
because it will be easy to see in the middle of other text
<stickster> In this example, &FED; is our entity that resolves to the
word "Fedora"
<stickster> Similarly, &FC; ==> "Fedora Core"
<horadrim> ok
<stickster> OK, so the point of all that is you can have entities that
are very specific to your document, and keep them in a file whose name
you put on this line, "DOC_ENTITIES"
<stickster> As you can see, I have such a file,
"doc-entities.xml" (Again, leave out the ".xml" part)
<horadrim> here DOC_ENTITIES just states doc-entities so should it be
smtg like &FED;
<stickster> horadrim: It's a filename, so it means that I have a
document-specific entities file called "doc-entities.xml"
<horadrim> ok just populate a file and reference said file in there
<stickster> horadrim: Exactly
<stickster> We'll look at the file later
<stickster> Next is a part that looks a little scary, but it's not as
bad as it seems
<stickster> All you need to do is add lines to the "XMLFILES-${1}"
definition for any DocBook files which make up your document
<stickster> In this case I have only one.
<stickster> The ${1} is the scary looking part -- to make a long story
short, it just means "insert language (directory) name here"
<stickster> Since this document's primary language is en_US, this means
that the XML file list is only one file, "en_US/mirror-tutorial.xml"
<stickster> Note that ${1} == en_US , and ${DOCBASE} == mirror-tutorial
<stickster> You don't have to use the ${DOCBASE} variable here, you
could just do this:
<stickster> (watch gobby)
<horadrim> ok
<stickster> Using DOCBASE means that someone can copy this Makefile for
any module with only one XML file named after the module, and it will
Just Work(tm) :-)
<horadrim> pretty regular use of a $VARIABLE
<stickster> Exactly
<stickster> So, the whole thing's in a template, which is why we're
using ${1} -- it's a Makefile parameter that is used during build,
meaning "insert language here"
<stickster> Finally, we have an "include" statement to grab all the
goodies from our (much longer and more complicated) Makefile.common,
which includes all the rules for building HTML, validation, etc....
<stickster>  On to the document, then, OK?
<horadrim> indeed
<stickster> OK, how familiar are you with XML in general?
<stickster> (zero is a perfectly acceptable answer)
<horadrim> generic idea...i also read the fedora mag extracts
<stickster> Awesome
<horadrim> i am somwhat familiar with markup languages
<stickster> That's great... you'll find this pretty easy then
<horadrim> i think i can pretty much go through easily
<stickster> OK, here's the 10,000m fly-over then :-)
<horadrim> i'm sad i work with PErforce (SCM) and document management
software
<stickster> The "rpm-info.xml" file is a requirement.  It follows a DTD
(you'll see the definition at the top of the file we have open) that's
in the docs-common module you checked out
<stickster> If you're going to edit XML, you'll want to use an XML-aware
editor -- there are many of them, some GUI, some text
<stickster> I prefer Emacs, as does Karsten (quaid); some prefer vi/Vim
<horadrim> i tend to use Vi
<stickster> Others like Kate, or quanta, or...... etc
<stickster> Great
<horadrim> as long as it does the job...
<stickster> actly.  
<stickster> Oops... exactly.
<stickster> The thing about these editors is, they are XML-aware and
will "validate" your entry
<horadrim> fair enough
<stickster> They understand DTD's and if you use the appropriate
keystrokes, they will make sure you don't put an illegal or invalid tag
in your document in the wrong place
<stickster> This makes writing any XML file with a DTD much easier --
you don't really need to learn more than a few tags, because if you ever
need another one, your editor will tell you what's legal to use in your
current context
<stickster> The rpm-info.xml file is a good example.  You don't really
want to memorize the DTD; just use your editor, copy the first couple of
lines from an existing rpm-info.xml file, and then let your editor do
the hard work.
<horadrim> don't worry...no intention of re-inventing the wheel
<stickster> OK, so this file is required.
<stickster> Notice I also opened the "doc-entities.xml" file, which is
only required because my Makefile says I'm using it
<stickster> I think this should make a little sense... note for example,
the definition for the &DOCDATE; entity
<stickster> In this case, it's defined as "2006-08-07"
<horadrim> was indeed looking at this
<stickster> Note also the &DOCID; entity definition, which uses other
entities we've defined here
<stickster> And keep in mind that we have a <group> element to group
entities together, but it's really up to you how you want to do that; we
don't have rules, although I like to see the "Revision markings" in one
group
<stickster> All right, moving on...
<stickster> The actual DocBook XML file (finally!) is in
"mirror-tutorial.xml"
<stickster> You'll probably end up just copy/pasting the first 10 lines
from an existing document, which is a perfect way to start
<stickster> And then, as we discussed earlier, let your editor do the
hard work
<stickster> If you get lost while doing any of this, just shoot a
question to the list or here in IRC
<horadrim> makes sense...so you keep track of version/subversion by
manually modifying the doc_entities then....then
<stickster> horadrim: Ah, that's the rub.  There's actually two places
we keep track of it -- which, yes, is stupid and we will try to change
this
<stickster> You put it in the doc-entities.xml for use in the document
itself, and also in the rpm-info.xml file in the <changelog> section
 * stickster thinks we will need to cover the XML content in a second
tutorial next week, if that's OK
<stickster> Don't feel you need to understand all of this yet
<horadrim> yup it's fine
<quaid> stickster: we could make a regular tutorial time/place, rotate
who is giving it, and dump the whole log to the world for edification :)
<stickster> quaid: nod I'll be posting this log to f-docs-l again like
last time
 * quaid supposes we can recycle topics, too
<stickster> absolutely
 * quaid goes quiet again :)
<quaid> stop ruining the log
<stickster> horadrim: So, what I've given you was part CVS and part
organization of a module you checked out
<horadrim> do you have a mcro that makes sure doc_entitities and
rpm_info are in sync  re version/subver at build time?
<stickster> Good question!
<stickster> I don't think we do, but I know how to do it with some XSLT
<stickster> That's a great to-do item
<horadrim> we probably need some kind of automated sanity check for
this?
<stickster> Would you mind putting it in Bugzilla for me?  You can log
it to Product "Fedora Documentation", component "toolchain-devel"
<horadrim> ok
<stickster> horadrim: Absolutely
<stickster> In fact, it would probably be best if we only tracked this
in one place, come to think of it
<stickster> I think that's do-able, actually
<horadrim> shame there is no auto-increment...
<stickster> Feel free to make that a wish list in your Bugzilla entry,
it will help remind me
<horadrim> lol deal!
<stickster> Actually, I have a "make clog" that will update
rpm-info.xml, but it won't do anything useful to doc-entities.xml
<stickster> Oh, I remember why!
<stickster> It's because my documents are using a special
&BUG-REPORTING; entity that fills in this information -- it's not
technically required so that's why there's no automated tool to tie the
two revision number tracking pieces together
<stickster> But that doesn't mean this doesn't merit a second look, so
do file that BZ
<horadrim> a sanity-check like that could probably mitigate the risk of
human error...a simple warning would probably do
<stickster> Definitely
<stickster> horadrim: OK, so if you want to forge ahead, and you're
sitting in ~/fedora/docs/mirror-tutorial, you can run "make help" to see
some of the targets available
<stickster> There's a lot of them, and only some will work in this case
<stickster> The main ones are "make validate-xml" and "make html" if you
want to see a couple things in action
<stickster> At this point, my advice is for you just to look at the XML
files and try to understand small parts at a time
<stickster> Ask plenty of questions on the list, it will help everyone
who lurks :-)
<horadrim> don't worry, i'll have a play
 * stickster has to run to dinner
<stickster> Thanks for being a willing audience
<horadrim> enjoy! and thanks for the tutorial
<horadrim> it's kind of fun
<stickster> Looks like quaid is around, and he taught me most of what I
know, so feel free to shoot him questions too
 * stickster bolts


-- 
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/20061209/32722d6d/attachment.sig>