Fedora Docs Wiki-to-DocBook XML Session
The following is a slightly edited transcript of a Fedora Docs Team meeting over IRC on 24 February 2007.
It was conducted with the Fedora Docs volunteers attending FOSDEM 2007 in Brussels, Belgium.
Karsten Wade (quaid) and Paul Frields (stickster) stepped the FOSDEM group through steps needed to convert the Desktop User Guide at Docs/DesktopUserGuide to a Doc
Book XML book format.
An easier-to-read version is now at this link .
- BEGIN LOGGING AT Sat Feb 24 17:55:01 2007
Feb 24 17:55:01 * Now talking on #fedora-docs
Feb 24 17:55:01 * Topic for #fedora-docs is: Fedora Documentation Project -=- Discussions between writers, editors, translators, and developers about documentation -=- For end-user support, use #fedora -=- DocsProject-=- Interested in documentation? http://www.fedoraproject.org/wiki/DocsProject/NewWriters -=- Elections: http://fedoraproject.org/wiki/DocsProject/Policy/FDSCoElections -=- "I'm in ur docs correctin ur speling
Feb 24 17:55:01 * Topic for #fedora-docs set by quaid at Thu Feb 22 19:52:09 2007
Feb 24 17:55:05 <quaid> I want to discuss it with you and stickster in a few, let me get some coffee and oatmeal started :D
Feb 24 17:55:13 <jmbuser> Greetings and Salutations
Feb 24 17:55:35 <jmbuser> FOSDEM crowd there?
Feb 24 17:55:42 <couf> jmbuser: sure
Feb 24 17:55:54 <jmbuser> couf: hi
Feb 24 17:56:13 <jmbuser> glezos_fosdem: hi
Feb 24 17:57:06 <couf> ow right I should send a mail aswell
Feb 24 17:57:28 <stickster> quaid: Well, for someone who goes to bed about 2am, you do pretty well IMHO
Feb 24 18:00:42 <couf> heh lol
Feb 24 18:01:15 <couf> okay folks, talk's over, we're getting ready here
Feb 24 18:02:55 <glezos_fosdem> quaid, sure. what's on your mind about PDF?
Feb 24 18:05:27 <couf> ping all
Feb 24 18:05:39 <jmbuser> couf: pong
Feb 24 18:05:42 <couf> we're ready here
Feb 24 18:08:15 <glezos_fosdem> stickster, any pointers on where to start with couf for the DUG to docbook process?
Feb 24 18:08:35 <stickster> glezos_fosdem: You'll want to work on a per-chapter/page basis
Feb 24 18:08:46 <glezos_fosdem> ok
Feb 24 18:08:47 * glezos_fosdem is now known as glezos
Feb 24 18:08:57 <glezos> ok
Feb 24 18:10:51 <glezos> stickster, so we just export from the page?
Feb 24 18:10:53 <glezos> \
Feb 24 18:11:13 <stickster> I just added a directory structure in CVS for them -- desktop-user-guide/FC-6/en_US/ is where you can put the XML files
Feb 24 18:11:27 <stickster> Yes, you can just export from the page. Be aware that they won't come out perfectly, but we can fix that XML stuff after it's in CVS
Feb 24 18:11:58 <stickster> For each page, name it something that makes sense, like the "chapter" title. Don't use "dug-" or anything at the beginning, it's unnecessary. For example, you could call one chapter "multimedia.xml"
Feb 24 18:12:44 <stickster> Set your CVSROOT appropriately as detailed in our CVS guidance, and then you can "cvs co desktop-user-guide"
Feb 24 18:12:53 <stickster> It'll just be some empty directories for now
Feb 24 18:12:58 <couf> right
Feb 24 18:14:10 <couf> so right now we're just exporting to docbook and naming the files
Feb 24 18:14:16 <stickster> Yup
Feb 24 18:14:21 <couf> do we need to export the toc aswell?
Feb 24 18:14:36 <stickster> couf: No, that part will be taken care of in rendering the DocBook to HTML or other formats
Feb 24 18:14:48 <stickster> Just export each of the chapter pages individually
Feb 24 18:15:27 <glezos> stickster, any automatic way to do that?
Feb 24 18:15:31 <couf> okay
Feb 24 18:15:31 <stickster> i.e. Introduction, Login, tour...
Feb 24 18:16:18 <glezos> BTW, I tried finding a guy from the KDE Docs team here to ask him about the PDF creation, but with no luck,
Feb 24 18:16:47 <glezos> stickster, which Makefile should we use as a base?
Feb 24 18:16:49 <stickster> glezos: You could adapt the beatconvert script in the release-notes module, but it would take some (admittedly light) Python wrangling
Feb 24 18:17:08 <glezos> stickster, maybe we should move that script to docs-common?
Feb 24 18:17:36 <stickster> glezos: You can use the one in documentation-guide
Feb 24 18:17:45 <stickster> glezos: Not yet. It's tightly tailored to the relnotes.
Feb 24 18:17:59 <glezos> ok
Feb 24 18:18:03 <stickster> one thing at a time :-)
Feb 24 18:18:06 <glezos> yup
Feb 24 18:18:10 <glezos> just asking
Feb 24 18:18:34 <stickster> Eventually I can see it being useful -- but eventually I could also see it being obsolete if ReST works better for our Drafts
Feb 24 18:18:39 * quaid continues the PDF intervweaving while he checks out the new module
Feb 24 18:19:04 <stickster> glezos: Oh, wait... You know, that script is actually even *less* useful than I was thinking
Feb 24 18:19:17 <stickster> It really was to work *around* the problem of not having docbook conversion on our "real" wiki!
Feb 24 18:19:27 <stickster> So it's actually quite obsolete right now :-D
Feb 24 18:19:33 <quaid> yeah, time to automate would be longer than by hand, with the current state of Wiki -> XML
Feb 24 18:19:36 <stickster> yup
Feb 24 18:20:26 <glezos> stickster, ReST? whats up with that?
Feb 24 18:21:10 <quaid> stickster: side note on that, are you thinking we should convert Docs/Beats/ to use ReST? and if so, are we going to make it harder to edit?
Feb 24 18:22:34 <quaid> glezos: so, there are two parts to PDF production for us -- is it in our toolchain (can you do make pdf), and does it work (is the output nice, does it throw errors for now reason)
Feb 24 18:22:55 <quaid> the answer to that is, yes, we can do it with our tools, and, yes, it is often broken
Feb 24 18:23:09 <glezos> quaid, lets concentrate on the second
Feb 24 18:23:56 <stickster> quaid: I don't think it will be much harder to edit. There's a few more markup possibilities, but it's a *lot* more human-readable than XML
Feb 24 18:24:01 <couf> okay I've got all the XML's
Feb 24 18:24:18 <stickster> couf: OK, you have them all in d-u-g/FC-6/en_US right?
Feb 24 18:24:28 <couf> stickster: yep
Feb 24 18:24:52 <glezos> I'm adding the Makefile
Feb 24 18:24:54 <stickster> Then you can do "cvs add *.xml" and then "cvs ci -m 'Initial commit from wiki' *.xml"
Feb 24 18:25:03 <stickster> (inside that dir of course)
Feb 24 18:25:23 * stickster is going to need to run in a minute or two, for a little wihle
Feb 24 18:25:25 <quaid> glezos: ok, so the standard passivetex in Fedora is problematic; it has always had problems, as soon as one is fixed, another arises; Veillard says we should be able to file bugs and etc, but ... it's going to take some folks some concentrated effort to figure out if the passivetex could work for anything.
Feb 24 18:25:55 <couf> btw, ugly xml layout
Feb 24 18:25:57 <glezos> ok lets forget about that then for now
Feb 24 18:26:01 <quaid> glezos: the guy who does the RHEL docs toolchain tried to get passivetex to work for him for ... six months? and they kept running into the "ugly table output" and a few other things we've all seen.
Feb 24 18:26:05 * couf has comitted
Feb 24 18:26:14 <stickster> Yeah, it was pretty horrific
Feb 24 18:26:24 <quaid> glezos: so, for FOP we're waiting on the Java team; we can't make anything without them.
Feb 24 18:26:36 <quaid> so that leaves us with hacking in additional pathways into our Makefile
Feb 24 18:26:55 <glezos> quaid, dblatex?
Feb 24 18:27:10 <quaid> glezos: I haven't looked, is it packaged for Fedora?
Feb 24 18:27:12 <jmbuser> glezos: the KDE way
Feb 24 18:27:24 <couf> quaid: nope
Feb 24 18:27:45 <quaid> I think it would be great to add other methods, but I'm concerned about us chasing something that doesn't work; do the KDE folks report any problems with the usage?
Feb 24 18:27:55 <stickster> glezos: I thought there was a translation problem with the KDE way of doing things
Feb 24 18:28:00 <stickster> Am I remembering wrong?
Feb 24 18:28:09 <jmbuser> quaid: there's a modified dblatex in tar.gz package
Feb 24 18:28:17 * stickster thinks back to that URL he threw ino #f-docs like a grenade the other day
Feb 24 18:28:25 <quaid> also to note, the FOP way is aligned with the upstream DocBook people; Java is what they use for this; so we hoped to catch the "wind fills all sails" method
Feb 24 18:28:34 <quaid> stickster: yeah, jmbuser captured it into his pages
Feb 24 18:29:28 <stickster> glezos: That Makefile can go into d-u-g/FC-6/ by the way
Feb 24 18:30:01 <stickster> Oops, HunkyCaps alert
Feb 24 18:30:03 <stickster> Oh well, no biggie
Feb 24 18:30:21 <stickster> could actually work to advantage with some automated tools
Feb 24 18:30:26 <couf> stickster: what's next?
Feb 24 18:31:09 <quaid> xmlformat is next
Feb 24 18:31:18 <stickster> heh
Feb 24 18:31:21 <quaid> shall I?
Feb 24 18:31:25 <stickster> please do, sir
Feb 24 18:31:27 <quaid> or shall i teach how? :)
Feb 24 18:31:28 <stickster> both
Feb 24 18:31:34 <couf> yeah both ;-)
Feb 24 18:31:38 <quaid> ok, so the XML needs to get some indenting
Feb 24 18:31:47 <quaid> the best way is with xmlformat, which is in docs-common
Feb 24 18:31:50 <couf> heh, figured that
Feb 24 18:31:57 <quaid> so I'm going to do a quick loop and commit back, one second and I'll show you how
Feb 24 18:32:04 <glezos> ok, added a first Makefile and rpm-info.xml
Feb 24 18:32:08 <glezos> fixing the errors now
Feb 24 18:32:11 <stickster> glezos: Cool
Feb 24 18:33:36 <stickster> quaid: I'll probably throw my usual Emacs local-variables in the bottom at some point, too
Feb 24 18:33:38 * quaid still tweaking, one minute more
Feb 24 18:33:40 <stickster> np
Feb 24 18:33:45 <couf> :)
Feb 24 18:35:37 <quaid> for i in
ls *xml; do xmlformat -f ../../../docs-common/bin/xmlformat-fdp.conf $i > tmpfile; mv tmpfile $i; done
Feb 24 18:35:40 <quaid> so I did that
Feb 24 18:35:43 <stickster> The xmlformat thing quaid is doing is basically just "prettying up" the text with good indentation, etc. so it's easier to read
Feb 24 18:35:52 <quaid> now when you cvs up -d, you'll get lots of pretty XML
Feb 24 18:36:33 <quaid> the -f docs-common/bin/xmlformat-fdp.conf is the customized configuration file we have done for FDP
Feb 24 18:37:00 <quaid> it tells the formatter to e.g. ignore <screen> blocks, which are blocks of code you don't want to have the whitespacing formatted out
Feb 24 18:37:02 <stickster> OK, added the local variables at end too
Feb 24 18:37:05 <stickster> so now you can "cvs up" again
Feb 24 18:37:11 <glezos> thanks guyws
Feb 24 18:37:14 <quaid> those are usefule for Emacs users
Feb 24 18:37:28 <quaid> and keeping things consistent
Feb 24 18:37:51 <quaid> now you guys can safely open Emacs and start hacking on the XML without it being crazy
Feb 24 18:38:04 <stickster> Because as everyone knows, Emacs is the best way to do all this ;-) *snicker
Feb 24 18:38:31 <quaid> heh
Feb 24 18:38:33 <glezos> :)
Feb 24 18:38:47 <quaid> is anyone working on the parent XML file? e.g. en_US/deskto-user-guide.xml?
Feb 24 18:38:54 <stickster> Ooo, there you go
Feb 24 18:38:56 <quaid> if not, I can hack one together quickly
Feb 24 18:39:01 <stickster> Nah, let the newbies do it
Feb 24 18:39:19 <quaid> use the release-notes/devel/en_US/release-notes.xml as a starting place
Feb 24 18:39:23 <couf> right
Feb 24 18:39:52 <quaid> sorry, s/release-notes/RELEASE-NOTES/
Feb 24 18:40:43 <quaid> in that file, I recommend chopping out or just ignoring the <!ENTITY BUG-URL and TINY-BUG-URL for now
Feb 24 18:40:53 <stickster> yup
Feb 24 18:41:57 <quaid> yeah, you are right, this is a relatively easy file to modify, and it is good stuff to look at
Feb 24 18:42:49 <glezos> the list of XML files are duplicated in the Makefile and the desktop-user-guide.xml, right?
Feb 24 18:44:27 <quaid> right
Feb 24 18:44:51 <couf> so the different xml-files should get a heading right?
Feb 24 18:44:58 <quaid> the d-u-g.xml is actually pulling the files in with XIncludes, where the Makefile needs the list of files ... well, I forget why the makefile needs the list :)
Feb 24 18:45:04 <glezos> and since r.h.c is down, which package provides xmlto?
Feb 24 18:45:33 <quaid> couf: yes, each file is a full xml file, with a header that says e.g.'chapter' instead of ;book'
Feb 24 18:46:16 <quaid> rpm -q --whatprovides
Feb 24 18:46:18 <quaid> xmlto-0.0.18-13.1
Feb 24 18:47:30 <glezos> thanks
Feb 24 18:48:02 <quaid> couf: you can look at the files in release-notes/devel/en_US/ to see how each XML should be prepared.
Feb 24 18:51:21 <couf> quaid: yeah
Feb 24 18:52:23 <couf> quaid: getting error with tables-stuff, should this be changed in xml?
Feb 24 18:52:44 <couf> we're working on Communications.xml to know how everything works
Feb 24 18:53:27 <couf> exact error is:
Feb 24 18:53:33 <couf> ./Communications.xml:404: element table: validity error : Element table content does not follow the DTD, expecting ((blockinfo? , (title , titleabbrev?) , indexterm* , textobject* , (graphic+ | mediaobject+ | tgroup+)) | (caption , (col* | colgroup*) , thead? , tfoot? , (tbody+ | tr+))), got (caption tgroup para para )
Feb 24 18:55:13 * quaid looks
Feb 24 18:56:28 <quaid> ok, 404 should be the line number
Feb 24 18:57:31 <couf> yeah, we're getting some of those error's
Feb 24 18:57:31 <quaid> can you check in this version of Communications.xml so I can see it?
Feb 24 18:57:43 <glezos> quaid, its checked in
Feb 24 18:59:01 <quaid> with the DOCTYPE header included?
Feb 24 18:59:53 <couf> quaid: not yet, hang on
Feb 24 18:59:56 <couf> different version
Feb 24 19:00:01 <quaid> k
Feb 24 19:01:16 <couf> now it should be
Feb 24 19:02:56 <quaid> ok, good, now I'm looking at the same line numbering
Feb 24 19:03:02 <glezos> quaid, this cool guy sitting next to me hacking on the DUG is *also* documenting each step for future reference.. how cool is that.
Feb 24 19:03:32 <jmbuser> thanks, cool guy!
Feb 24 19:03:33 <quaid> http://www.docbook.org/tdg/en/html/table.html is where I'm looking
Feb 24 19:03:41 <quaid> glezos: :D
Feb 24 19:04:25 <quaid> ah, the admonition problem!
Feb 24 19:04:38 <quaid> ok, so here's one of the problems we currently have with wiki => XML
Feb 24 19:04:45 * stickster gets back from furniture moving
Feb 24 19:04:58 <quaid> there is no sense of an admonition in the Wiki
Feb 24 19:05:08 <quaid> we use a e.g. in a table, but that is a visual formatting
Feb 24 19:05:23 <quaid> so, the table that is erroring here needs to be replaced with a proper admonition
Feb 24 19:05:34 <quaid> in fact, you'll probably find that _all_ tables in the XML are in fact admonitions
Feb 24 19:05:36 * stickster hacks a couple things in d-u-g.xml
Feb 24 19:05:59 <quaid> does that make sense or should I update this XML to how what I mean?
Feb 24 19:07:06 <couf> quaid: it makes some sense, but do show us
Feb 24 19:08:23 <quaid> ok, fix checked in
Feb 24 19:08:27 * glezos feels that these non-automatic procedures take the Handbook off the table completely... :(
Feb 24 19:08:35 <quaid> that is, not sure it will make the doc build stop breaking, but it should help :)
Feb 24 19:08:57 <quaid> glezos: this is the broken part that we had all the GSoC coding done for ... which we are still not using
Feb 24 19:09:17 * jmbuser makes note to self to do DocBook admonitions in comments to speed things up in the future
Feb 24 19:09:18 * stickster fixes prolog in d-u-g.xml
Feb 24 19:09:19 <quaid> the "new" path is much better, for example, that's why we use the funky admonition style in the Docs/Beats/
Feb 24 19:09:39 * stickster notes that ReST has ability to do "real" admonitions
Feb 24 19:09:58 <stickster> Including all five of our types for DocBook, meaning they should come out correctly both visually and XMLish
Feb 24 19:10:33 <jmbuser> stickster: another time you'll have to explain ReST - it kinda came out of nowhere for me
Feb 24 19:10:59 <stickster> jmbuser: http://docutils.sourceforge.net/rst.html
Feb 24 19:11:17 <jmbuser> stickster: thanks
Feb 24 19:12:07 <couf> quaid: right got that, what are the possible admonittions?
Feb 24 19:12:35 <quaid> ok
Feb 24 19:12:44 * couf notes: one file to help out, the rest will be doable, I hope
Feb 24 19:13:03 * stickster adds doc-entities.xml file too
Feb 24 19:13:19 <stickster> couf: note, tip, important, caution, warning
Feb 24 19:13:33 <couf> stickster: thanks
Feb 24 19:13:37 <stickster> see also the Documentation Guide for how to use each one
Feb 24 19:13:38 <quaid> http://fedoraproject.org/wiki/WikiEditing#Admonitions
Feb 24 19:13:47 * quaid saves that
Feb 24 19:14:31 <quaid> that helps, because the wiki only shows you which was used
Feb 24 19:16:36 * stickster corrects relative path in doc-entities.xml
Feb 24 19:16:41 <stickster> Everybody make sure you cvs-up
Feb 24 19:17:51 <couf> stickster: hmm getting errors now
Feb 24 19:17:58 <stickster> couf: To be expected.
Feb 24 19:18:11 <couf> stickster: aah okay
Feb 24 19:18:12 <stickster> couf: You mean 'C'onflicts in CVS?
Feb 24 19:18:21 <stickster> Or when you do a "make validate-xml"?
Feb 24 19:18:22 <couf> stickster: no, in the make
Feb 24 19:18:27 <stickster> OK, yes, perfectly expected at this point.
Feb 24 19:18:34 <quaid> right
Feb 24 19:18:39 <stickster> There's a lot of XML still to be fixed.
Feb 24 19:18:41 <couf> right
Feb 24 19:18:52 <stickster> couf: Believe it or not, those error message *will* tell you exactly where the problem is.
Feb 24 19:18:54 <quaid> the technique is, you go through and fix all you know (such as table => admonition)
Feb 24 19:18:59 <quaid> then you build, it breaks, and you fix that
Feb 24 19:19:08 <quaid> repeat until it stops breaking
Feb 24 19:19:16 <stickster> You just need to take your time and read the error messages... believe me, it takes a *lot* of patience sometimes!!!
Feb 24 19:19:25 <quaid> one clue is ...
Feb 24 19:19:39 <quaid> it dumps all the output for you, so the error is often buried somewhere
Feb 24 19:20:05 <quaid> if you start at the bottom of the error content and work backward, you can find the spot where "warning" becomes "error"
Feb 24 19:20:15 <stickster> Ah, I also needed to commit the new Makefile stuff, sorrry
Feb 24 19:20:18 <stickster> cvs up again
Feb 24 19:20:18 <couf> aah
Feb 24 19:20:27 <stickster> Now you'll get different and all-new errors!
Feb 24 19:20:34 <couf> stickster: that's better :)
Feb 24 19:20:45 <couf> it was an error on your doc-entities, that's way I mentioned it
Feb 24 19:20:53 <couf> now gone
Feb 24 19:21:12 <stickster> Yup, my fault entirely, forgot to tell the Makefile they were there so it could build the .ent from the .xml
Feb 24 19:21:55 <couf> heh, no problem
Feb 24 19:22:24 <stickster> quaid: Are we doing this as <article> with <section>s or <book> with <chapter>s (like other guides)?
Feb 24 19:23:02 * stickster asks before we start putting prologs in all the files
Feb 24 19:23:14 <quaid> book and chapter, i thought
Feb 24 19:23:22 <stickster> cool
Feb 24 19:24:10 * stickster makes change in Communications, should be easily mergeable
Feb 24 19:24:39 <stickster> OK, committed
Feb 24 19:27:38 <couf> so I just committed the new Communications with all admonitions
Feb 24 19:27:50 <couf> stickster, quaid: could anyone just check it?
Feb 24 19:28:20 * stickster needs to correct XPointer real quick
Feb 24 19:31:40 * stickster is fixing some rpm-info problems, hang on
Feb 24 19:31:55 <stickster> rpm-info must be valid for anything else to work properly :-)
Feb 24 19:32:39 <jmbuser> (makes small talk) how did the talks go?
Feb 24 19:33:37 <stickster> OK, couf, good work, that file is valid
Feb 24 19:33:44 <stickster> cvs up to get my changes
Feb 24 19:34:18 <stickster> couf: Well, it still needs to get all the attachments added in the XML now
Feb 24 19:34:51 <glezos> stickster, you do all each time you produce the doc from the Beats?
Feb 24 19:35:03 <couf> stickster: so how do you do that
Feb 24 19:35:03 <couf> ?
Feb 24 19:35:20 <stickster> couf: Just download the attachments and "cvs add" and "cvs commit" them in en_US/figs/
Feb 24 19:35:40 <stickster> glezos: Well, it's much easier when the docs are written to specific XML porting standards... :-)
Feb 24 19:35:48 <stickster> And hopefully if we use ReST that will be even easier
Feb 24 19:36:10 <stickster> And the rpm-info and Makefile stuff gets out of the way only once per doc
Feb 24 19:36:18 <stickster> But yes, we have to do a little XML hand-cobbling anytime we do a mass import
Feb 24 19:37:04 <couf> stickster: should I keep the names?
Feb 24 19:37:45 <stickster> couf: Sure, I don't think that's a problem.
Feb 24 19:37:52 <stickster> Bits are cheap if we end up needing to change them.
Feb 24 19:38:09 <stickster> Some things that are going to need fixing throughout:
Feb 24 19:38:18 <stickster> Turn all the menu selections into <menuchoice> elements
Feb 24 19:38:33 <stickster> Make sure <ulink> elements are concise
Feb 24 19:38:49 <stickster> couf: By the way, you should make sure all the attachments are no bigger than 500px wide
Feb 24 19:39:04 <stickster> You can use ImageMagick's "mogrify" command for this
Feb 24 19:40:19 <couf> stickster: wide and/or high?
Feb 24 19:40:40 <stickster> wide
Feb 24 19:40:50 <quaid> it would be cool if it had a 'valmorify' command
Feb 24 19:40:55 <stickster> ?
Feb 24 19:41:13 <quaid> sorry, Team America reference
Feb 24 19:41:21 <stickster> heh
Feb 24 19:41:44 <quaid> they use 'valmorification' the way Calvin and Hobbes use 'transmogrify'
Feb 24 19:42:11 * stickster needs to read writers list more carefully
Feb 24 19:42:43 <couf> stickster: educate me
Feb 24 19:46:53 <couf> stickster: mogrify -geometry 500 file.png?
Feb 24 19:47:04 <stickster> couf: Yes, I believe that's right
Feb 24 19:47:39 <stickster> Or it might be 'mogrify -scale 500 file.png'
Feb 24 19:48:12 <couf> it seems to work
Feb 24 19:48:30 <stickster> OK
Feb 24 19:48:43 * stickster updates colophon in rpm-info, time to cvs up again :-)
Feb 24 19:50:37 <stickster> whoops, one more change needed there
Feb 24 19:51:59 <stickster> One more cvs up :-)
Feb 24 19:53:46 <stickster> couf: OK, now for each of those locations in the document, you'll need to have an appropriate XML element. You can find examples all over, like the Installation Guide for instance
Feb 24 19:54:17 * stickster wonders how ReST parsers might deal with this -- probably better.
Feb 24 19:54:55 <couf> stickster: I see .eps files everywhere, do these need to be created aswell?
Feb 24 19:55:17 <stickster> Those are for the print version in PDFs; you probably don't need to do anything with those for now.
Feb 24 19:56:04 <stickster> My personal opinion is anything like that should be built from the source PNGs at render time anyway.
Feb 24 19:56:20 <couf> right
Feb 24 19:56:21 <stickster> Minimize what we have to store in the SCM, in other words
Feb 24 19:57:55 <quaid> +1
Feb 24 20:00:59 <couf> stickster: I think somethings wrong with the placement of the figs
Feb 24 20:01:12 <couf> shouldn't it be FC-6/figs
Feb 24 20:01:22 <couf> in stead of FC-6/en_US/figs?
Feb 24 20:01:39 <quaid> hmm, they can be translated, right?
Feb 24 20:01:44 <quaid> theoretically, that is
Feb 24 20:01:53 <quaid> so each $LANG needs its own set? or ...?
Feb 24 20:02:26 <stickster> quaid: I believe the build tools take care of this. If they're translatable (i.e. screenshots) they should be in the $LANG directory. If no others are found, the $PRI_LANG ones get used in any $LANG in $OTHERS
Feb 24 20:02:31 <couf> in install guide it's just beneath the devel or fc-x version
Feb 24 20:02:41 <stickster> Yeah, the build tools will search in several places for these.
Feb 24 20:03:01 <stickster> The situation in the Installation Guide is simply because no one ever provides translated screen shots, and I was too lazy to move them for now.
Feb 24 20:03:04 <stickster> :-D
Feb 24 20:03:36 <couf> the makefile seems to be missing the right directory
Feb 24 20:03:41 <stickster> rrr?
Feb 24 20:04:11 <couf> it's doing: [ ! -d figs ] || copy-figs -v -f '*.png' -l en_US figs desktop-user-guide-en_US
Feb 24 20:04:18 <couf> and it isn't copying anything
Feb 24 20:04:38 <stickster> Arrrgh
Feb 24 20:05:14 * stickster fixes prologs in all XML fiels
Feb 24 20:05:14 <stickster> *files
Feb 24 20:05:26 <couf> heh
Feb 24 20:05:54 <stickster> couf: Please commit your changes to the XML file so I can test here
Feb 24 20:07:07 <couf> stickster: done
Feb 24 20:10:09 <stickster> Heh, leave it to Tommy to write shell scripts in the most arcane possible way.l
Feb 24 20:10:20 <stickster> Why use $VARNAME when you can use $c ?
Feb 24 20:11:17 <stickster> OK... let's see if we can fix this
Feb 24 20:13:06 <couf> so okay, just to clearify, if I copy the figs directory one up, it works
Feb 24 20:13:33 <quaid> yes
Feb 24 20:14:00 <couf> so should I move the dir on cvs or not?
Feb 24 20:14:04 <stickster> couf: Right
Feb 24 20:14:14 <stickster> I'm taking care of it, making it a little more obvious they're to be translated
Feb 24 20:14:20 <couf> stickster: okay
Feb 24 20:14:52 <stickster> Why does my po dir keep disappearing? OH well
Feb 24 20:18:11 <stickster> OK, they're in the right place now
Feb 24 20:18:18 <stickster> cvs up and so forth :-)
Feb 24 20:20:43 <stickster> Oh crap, that is going to suck now.
Feb 24 20:21:00 <couf> okay works
Feb 24 20:21:03 <stickster> OK, our whole copy-figs thing is completely fux0r3d.
Feb 24 20:21:22 <stickster> couf: Well, it copies, but the sucky part is that now the lang codes are going to interfere with the L10N work
Feb 24 20:21:50 <couf> yeah, will be a problem for a bit later
Feb 24 20:21:57 <stickster> Because I gave them names with a L10n code, it means the XML has to point to that file name. When a translator translates, they may not get the chance to change that file name.
Feb 24 20:21:58 <couf> let's first get the full xml
Feb 24 20:22:01 <stickster> Thus the suck.
Feb 24 20:22:08 <stickster> Sure
Feb 24 20:22:09 <couf> right
Feb 24 20:22:23 <stickster> couf: All right, what else do you need to keep going?
Feb 24 20:22:34 <stickster> I need to get some lunch and a bunch of other things done here today
Feb 24 20:22:47 <couf> not much I think, I'll do a recap of what I know now
Feb 24 20:23:02 <couf> 1) check header of each xml-doc + add to parent file
Feb 24 20:23:11 <couf> 2) change admonition stuff
Feb 24 20:23:14 <couf> 3) figures
Feb 24 20:23:19 <couf> right?
Feb 24 20:23:37 <stickster> that will be a great start, also 1a) make sure the top-level element of each file is a <chapter> and not a <section> or <article>
Feb 24 20:23:44 <stickster> (close the tag at the end too)
Feb 24 20:23:54 <couf> right
Feb 24 20:24:07 <stickster> cool then, don't worry about validation problems -- do your best and I will be happy to help house-clean later
Feb 24 20:24:14 <couf> okay
Feb 24 20:24:31 <stickster> We'll also need to figure out this stupid figs deal.
Feb 24 20:24:45 <stickster> It could be my lack of clue about the copy-figs script, I'll re-read when I'm not starving :-D
Feb 24 20:26:17 <couf> all righty, gonna try to get the most done as long as time permits it here
Feb 24 20:26:23 <couf> the rest'll be for tomorrow
Feb 24 20:28:27 <jmbuser> couf: I tried to pay careful attention to what you guys were doing, but i got interrupted several times by phone calls - and my brain is tired from a full day's work.
Feb 24 20:29:07 <couf> jmbuser: I'm trying to keep a list of what we've done, I'll pass it on to you, once it's got some cleanup doneµ
Feb 24 20:29:10 <jmbuser> couf: Therefore, any notes you have - and I am saving this chat transcript as well - will be helpful.
Feb 24 20:29:58 * jmbuser changes subject
Feb 24 20:30:10 <jmbuser> couf: so, how's FOSDEM?
Feb 24 20:30:31 <couf> it's good, a lot of people around
Feb 24 20:30:39 <couf> fedora seems to be very active here in Europe
Feb 24 20:30:47 <glezos> back from Django
Feb 24 20:30:49 <couf> got to meet some nice people, like the guy next to me
Feb 24 20:31:00 <couf> s/guy/guys
Feb 24 20:31:29 <glezos> ok, I was convinced today that it would be impossible to produce a Handbook from the wiki.
Feb 24 20:35:11 <jmbuser> glezos: "rest" sounds interesting, once I figure it out
Feb 24 20:35:28 * ajaaya has joined #fedora-docs
Feb 24 20:36:36 <jmbuser> couf: Thanks in advance
Feb 24 20:36:54 <glezos> jmbuser, docutils?
Feb 24 20:37:37 <jmbuser> glezos: yes, although I could use a rest :-)
Feb 24 20:38:12 <glezos> :)
Feb 24 20:38:37 <couf> jmbuser: np
Feb 24 20:39:47 <ajaaya> #fedora-docs: hello
Feb 24 20:40:07 <jmbuser> ajaaya: hi
Feb 24 20:40:32 <ajaaya> jmbuser: did I miss the DUG to XML conversation?
Feb 24 20:41:22 <jmbuser> ajaaya: yes, but I am logging the session and our guys at FOSDEM are producing notes
Feb 24 20:41:42 <ajaaya> jmbuser: thanks mate
Feb 24 20:43:46 <jmbuser> ajaaya: I will put the log under my (not so) private wiki sandbox as JohnBabich/FosdemDocs in a few hours
Feb 24 20:44:33 <couf> lol
Feb 24 20:44:39 <ajaaya> jmbuser: kewl
End of Transcript