JohnBabich/FosdemDocs

From FedoraProject

Jump to: navigation, search

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 DocBook XML book format.


Idea.png 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 -=- http://fedoraproject.org/wiki/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 <code>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 which xmlto

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. Stop (medium size).png 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 Note.png 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