JohnBabich/FosdemDocs

= 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 ; do xmlformat -f ../../../docs-common/bin/xmlformat-fdp.conf $i > tmpfile; mv tmpfile $i; done

Feb 24 18:35:40 	so I did that

Feb 24 18:35:43 	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 	now when you cvs up -d, you'll get lots of pretty XML

Feb 24 18:36:33 	the -f docs-common/bin/xmlformat-fdp.conf is the customized configuration file we have done for FDP

Feb 24 18:37:00 	it tells the formatter to e.g. ignore blocks, which are blocks of code you don't want to have the whitespacing formatted out

Feb 24 18:37:02 	OK, added the local variables at end too

Feb 24 18:37:05 	so now you can "cvs up" again

Feb 24 18:37:11 	thanks guyws

Feb 24 18:37:14 	those are usefule for Emacs users

Feb 24 18:37:28 	and keeping things consistent

Feb 24 18:37:51 	now you guys can safely open Emacs and start hacking on the XML without it being crazy

Feb 24 18:38:04 	Because as everyone knows, Emacs is the best way to do all this ;-) *snicker

Feb 24 18:38:31 	heh

Feb 24 18:38:33 	:)

Feb 24 18:38:47 	is anyone working on the parent XML file? e.g. en_US/deskto-user-guide.xml?

Feb 24 18:38:54 	Ooo, there you go

Feb 24 18:38:56 	if not, I can hack one together quickly

Feb 24 18:39:01 	Nah, let the newbies do it

Feb 24 18:39:19 	use the release-notes/devel/en_US/release-notes.xml as a starting place

Feb 24 18:39:23 	right

Feb 24 18:39:52 	sorry, s/release-notes/RELEASE-NOTES/

Feb 24 18:40:43 	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 	yup

Feb 24 18:41:57 	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 	the list of XML files are duplicated in the Makefile and the desktop-user-guide.xml, right?

Feb 24 18:44:27 	right

Feb 24 18:44:51 	so the different xml-files should get a heading right?

Feb 24 18:44:58 	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 	and since r.h.c is down, which package provides xmlto?

Feb 24 18:45:33 	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 	rpm -q --whatprovides

Feb 24 18:46:18 	xmlto-0.0.18-13.1

Feb 24 18:47:30 	thanks

Feb 24 18:48:02 	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 	quaid: yeah

Feb 24 18:52:23 	quaid: getting error with tables-stuff, should this be changed in xml?

Feb 24 18:52:44 	we're working on Communications.xml to know how everything works

Feb 24 18:53:27 	exact error is:

Feb 24 18:53:33 	./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 	ok, 404 should be the line number

Feb 24 18:57:31 	yeah, we're getting some of those error's

Feb 24 18:57:31 	can you check in this version of Communications.xml so I can see it?

Feb 24 18:57:43 	quaid, its checked in

Feb 24 18:59:01 	with the DOCTYPE header included?

Feb 24 18:59:53 	quaid: not yet, hang on

Feb 24 18:59:56 	different version

Feb 24 19:00:01 	k

Feb 24 19:01:16 	now it should be

Feb 24 19:02:56 	ok, good, now I'm looking at the same line numbering

Feb 24 19:03:02 	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 	thanks, cool guy!

Feb 24 19:03:33 	http://www.docbook.org/tdg/en/html/table.html is where I'm looking

Feb 24 19:03:41 	glezos: :D

Feb 24 19:04:25 	ah, the admonition problem!

Feb 24 19:04:38 	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 	there is no sense of an admonition in the Wiki

Feb 24 19:05:08 	we use a e.g.  in a table, but that is a visual formatting

Feb 24 19:05:23 	so, the table that is erroring here needs to be replaced with a proper admonition

Feb 24 19:05:34 	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 	does that make sense or should I update this XML to how what I mean?

Feb 24 19:07:06 	quaid: it makes some sense, but do show us

Feb 24 19:08:23 	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 	that is, not sure it will make the doc build stop breaking, but it should help :)

Feb 24 19:08:57 	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 	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 	Including all five of our types for DocBook, meaning they should come out correctly both visually and XMLish

Feb 24 19:10:33 	stickster: another time you'll have to explain ReST - it kinda came out of nowhere for me

Feb 24 19:10:59 	jmbuser: http://docutils.sourceforge.net/rst.html

Feb 24 19:11:17 	stickster: thanks

Feb 24 19:12:07 	quaid: right got that, what are the possible admonittions?

Feb 24 19:12:35 	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 	couf: note, tip, important, caution, warning

Feb 24 19:13:33 	stickster: thanks

Feb 24 19:13:37 	see also the Documentation Guide for how to use each one

Feb 24 19:13:38 	http://fedoraproject.org/wiki/WikiEditing#Admonitions

Feb 24 19:13:47 *	quaid saves that

Feb 24 19:14:31 	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 	Everybody make sure you cvs-up

Feb 24 19:17:51 	stickster: hmm getting errors now

Feb 24 19:17:58 	couf: To be expected.

Feb 24 19:18:11 	stickster: aah okay

Feb 24 19:18:12 	couf: You mean 'C'onflicts in CVS?

Feb 24 19:18:21 	Or when you do a "make validate-xml"?

Feb 24 19:18:22 	stickster: no, in the make

Feb 24 19:18:27 	OK, yes, perfectly expected at this point.

Feb 24 19:18:34 	right

Feb 24 19:18:39 	There's a lot of XML still to be fixed.

Feb 24 19:18:41 	right

Feb 24 19:18:52 	couf: Believe it or not, those error message *will* tell you exactly where the problem is.

Feb 24 19:18:54 	the technique is, you go through and fix all you know (such as table => admonition)

Feb 24 19:18:59 	then you build, it breaks, and you fix that

Feb 24 19:19:08 	repeat until it stops breaking

Feb 24 19:19:16 	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 	one clue is ...

Feb 24 19:19:39 	it dumps all the output for you, so the error is often buried somewhere

Feb 24 19:20:05 	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 	Ah, I also needed to commit the new Makefile stuff, sorrry

Feb 24 19:20:18 	cvs up again

Feb 24 19:20:18 	aah

Feb 24 19:20:27 	Now you'll get different and all-new errors!

Feb 24 19:20:34 	stickster: that's better :)

Feb 24 19:20:45 	it was an error on your doc-entities, that's way I mentioned it

Feb 24 19:20:53 	now gone

Feb 24 19:21:12 	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 	heh, no problem

Feb 24 19:22:24 	quaid: Are we doing this as with s or with 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 	book and chapter, i thought

Feb 24 19:23:22 	cool

Feb 24 19:24:10 *	stickster makes change in Communications, should be easily mergeable

Feb 24 19:24:39 	OK, committed

Feb 24 19:27:38 	so I just committed the new Communications with all admonitions

Feb 24 19:27:50 	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 	rpm-info must be valid for anything else to work properly :-)

Feb 24 19:32:39 	(makes small talk) how did the talks go?

Feb 24 19:33:37 	OK, couf, good work, that file is valid

Feb 24 19:33:44 	cvs up to get my changes

Feb 24 19:34:18 	couf: Well, it still needs to get all the attachments added in the XML now

Feb 24 19:34:51 	stickster, you do all each time you produce the doc from the Beats?

Feb 24 19:35:03 	stickster: so how do you do that

Feb 24 19:35:03 	?

Feb 24 19:35:20 	couf: Just download the attachments and "cvs add" and "cvs commit" them in en_US/figs/

Feb 24 19:35:40 	glezos: Well, it's much easier when the docs are written to specific XML porting standards... :-)

Feb 24 19:35:48 	And hopefully if we use ReST that will be even easier

Feb 24 19:36:10 	And the rpm-info and Makefile stuff gets out of the way only once per doc

Feb 24 19:36:18 	But yes, we have to do a little XML hand-cobbling anytime we do a mass import

Feb 24 19:37:04 	stickster: should I keep the names?

Feb 24 19:37:45 	couf: Sure, I don't think that's a problem.

Feb 24 19:37:52 	Bits are cheap if we end up needing to change them.

Feb 24 19:38:09 	Some things that are going to need fixing throughout:

Feb 24 19:38:18 	Turn all the menu selections into elements

Feb 24 19:38:33 	Make sure elements are concise

Feb 24 19:38:49 	couf: By the way, you should make sure all the attachments are no bigger than 500px wide

Feb 24 19:39:04 	You can use ImageMagick's "mogrify" command for this

Feb 24 19:40:19 	stickster: wide and/or high?

Feb 24 19:40:40 	wide

Feb 24 19:40:50 	it would be cool if it had a 'valmorify' command

Feb 24 19:40:55 	?

Feb 24 19:41:13 	sorry, Team America reference

Feb 24 19:41:21 	heh

Feb 24 19:41:44 	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 	stickster: educate me

Feb 24 19:46:53 	stickster: mogrify -geometry 500 file.png?

Feb 24 19:47:04 	couf: Yes, I believe that's right

Feb 24 19:47:39 	Or it might be 'mogrify -scale 500 file.png'

Feb 24 19:48:12 	it seems to work

Feb 24 19:48:30 	OK

Feb 24 19:48:43 *	stickster updates colophon in rpm-info, time to cvs up again :-)

Feb 24 19:50:37 	whoops, one more change needed there

Feb 24 19:51:59 	One more cvs up :-)

Feb 24 19:53:46 	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 	stickster: I see .eps files everywhere, do these need to be created aswell?

Feb 24 19:55:17 	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 	My personal opinion is anything like that should be built from the source PNGs at render time anyway.

Feb 24 19:56:20 	right

Feb 24 19:56:21 	Minimize what we have to store in the SCM, in other words

Feb 24 19:57:55 	+1

Feb 24 20:00:59 	stickster: I think somethings wrong with the placement of the figs

Feb 24 20:01:12 	shouldn't it be FC-6/figs

Feb 24 20:01:22 	in stead of FC-6/en_US/figs?

Feb 24 20:01:39 	hmm, they can be translated, right?

Feb 24 20:01:44 	theoretically, that is

Feb 24 20:01:53 	so each $LANG needs its own set? or ...?

Feb 24 20:02:26 	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 	in install guide it's just beneath the devel or fc-x version

Feb 24 20:02:41 	Yeah, the build tools will search in several places for these.

Feb 24 20:03:01 	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 	:-D

Feb 24 20:03:36 	the makefile seems to be missing the right directory

Feb 24 20:03:41 	rrr?

Feb 24 20:04:11 	it's doing: [ ! -d figs ] || copy-figs -v -f '*.png' -l en_US figs desktop-user-guide-en_US

Feb 24 20:04:18 	and it isn't copying anything

Feb 24 20:04:38 	Arrrgh

Feb 24 20:05:14 *	stickster fixes prologs in all XML fiels

Feb 24 20:05:14 	*files

Feb 24 20:05:26 	heh

Feb 24 20:05:54 	couf: Please commit your changes to the XML file so I can test here

Feb 24 20:07:07 	stickster: done

Feb 24 20:10:09 	Heh, leave it to Tommy to write shell scripts in the most arcane possible way.l

Feb 24 20:10:20 	Why use $VARNAME when you can use $c ?

Feb 24 20:11:17 	OK... let's see if we can fix this

Feb 24 20:13:06 	so okay, just to clearify, if I copy the figs directory one up, it works

Feb 24 20:13:33 	yes

Feb 24 20:14:00 	so should I move the dir on cvs or not?

Feb 24 20:14:04 	couf: Right

Feb 24 20:14:14 	I'm taking care of it, making it a little more obvious they're to be translated

Feb 24 20:14:20 	stickster: okay

Feb 24 20:14:52 	Why does my po dir keep disappearing? OH well

Feb 24 20:18:11 	OK, they're in the right place now

Feb 24 20:18:18 	cvs up and so forth :-)

Feb 24 20:20:43 	Oh crap, that is going to suck now.

Feb 24 20:21:00 	okay works

Feb 24 20:21:03 	OK, our whole copy-figs thing is completely fux0r3d.

Feb 24 20:21:22 	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 	yeah, will be a problem for a bit later

Feb 24 20:21:57 	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 	let's first get the full xml

Feb 24 20:22:01 	Thus the suck.

Feb 24 20:22:08 	Sure

Feb 24 20:22:09 	right

Feb 24 20:22:23 	couf: All right, what else do you need to keep going?

Feb 24 20:22:34 	I need to get some lunch and a bunch of other things done here today

Feb 24 20:22:47 	not much I think, I'll do a recap of what I know now

Feb 24 20:23:02 	1) check header of each xml-doc + add to parent file

Feb 24 20:23:11 	2) change admonition stuff

Feb 24 20:23:14 	3) figures

Feb 24 20:23:19 	right?

Feb 24 20:23:37 	that will be a great start, also 1a) make sure the top-level element of each file is a and not a or

Feb 24 20:23:44 	(close the tag at the end too)

Feb 24 20:23:54 	right

Feb 24 20:24:07 	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 	okay

Feb 24 20:24:31 	We'll also need to figure out this stupid figs deal.

Feb 24 20:24:45 	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 	all righty, gonna try to get the most done as long as time permits it here

Feb 24 20:26:23 	the rest'll be for tomorrow

Feb 24 20:28:27 	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 	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 	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 	couf: so, how's FOSDEM?

Feb 24 20:30:31 	it's good, a lot of people around

Feb 24 20:30:39 	fedora seems to be very active here in Europe

Feb 24 20:30:47 	back from Django

Feb 24 20:30:49 	got to meet some nice people, like the guy next to me

Feb 24 20:31:00 	s/guy/guys

Feb 24 20:31:29 	ok, I was convinced today that it would be impossible to produce a Handbook from the wiki.

Feb 24 20:35:11 	glezos: "rest" sounds interesting, once I figure it out

Feb 24 20:35:28 *	ajaaya has joined #fedora-docs

Feb 24 20:36:36 	couf: Thanks in advance

Feb 24 20:36:54 	jmbuser, docutils?

Feb 24 20:37:37 	glezos: yes, although I could use a rest :-)

Feb 24 20:38:12 	:)

Feb 24 20:38:37 	jmbuser: np

Feb 24 20:39:47 	#fedora-docs: hello

Feb 24 20:40:07 	ajaaya: hi

Feb 24 20:40:32 	jmbuser: did I miss the DUG to XML conversation?

Feb 24 20:41:22 	ajaaya: yes, but I am logging the session and our guys at FOSDEM are producing notes

Feb 24 20:41:42 	jmbuser: thanks mate

Feb 24 20:43:46 	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 	lol

Feb 24 20:44:39 	jmbuser: kewl

End of Transcript