Toolchain meeting 2008-05-22 IRC log

[Paul W. Frields]

[22 May 21:05] * stickster here
[22 May 21:05] <jsmith> 
[22 May 21:05] * jsmith here
[22 May 21:05] <jfearn> jfearn, here
[22 May 21:05] <mdious> jsmith: MOIN!
[22 May 21:06] <jsmith> Howdy mdious
[22 May 21:06] <jsmith> Howdy jfearn
[22 May 21:06] <asgeirf> hello folks :)
[22 May 21:07] <jmtaylor> 
[22 May 21:07] * jmtaylor waves and sits back down
[22 May 21:07] <Tsagadai> morning
[22 May 21:07] <jfearn> jsmith, g'day :0
[22 May 21:07] <stickster> All righty, no quaid I guess
[22 May 21:08] <stickster> He was having some router problems earlier
today, maybe he took the hammer to it.
[22 May 21:08] <stickster> What we want to do here is figure out where
to go with the docs toolchain.
[22 May 21:09] <stickster> The whole Fedora Docs Project is being
revamped to an extent
[22 May 21:09] <stickster> And what we were going to try to do is move
any large docs people want to maintain out into their own hosted
projects.
[22 May 21:10] <stickster> That way a community can gather around them
independently of the CVS and toolchain we've loped along with for years.
[22 May 21:10] <stickster> The question remains, what in our toolchain
is worth keeping?
[22 May 21:11] <stickster> i.e., things where we can just plug in
publican, for example
[22 May 21:11] <jsmith> Well, I think (from my own experience) that
there's probably a lot worth keeping (or incorporating into Publican)...
I just don't know it as well as I do Publican
[22 May 21:11] <jsmith> Last I heard from quaid, he was worried about
the translation stuff
[22 May 21:11] <stickster> There's a few clever bits in it, I'm pretty
sure, thanks to people who worked on it in the past
[22 May 21:11] <mdious> I think the release notes wiki/xml scripts are
worth keeping around....
[22 May 21:12] <stickster> So our toolchain is basically bound up in the
docs-common module in our CVS right now.
[22 May 21:13] <Tsagadai> moving away from wiki is a good thing.
publican is certainly easier for i18n
[22 May 21:14] <stickster> Tsagadai: Well, I'm not sure we're looking at
moving away from the wiki for things like the release notes
[22 May 21:14] <stickster> In fact, we're looking at extending MediaWiki
i18n
[22 May 21:14] <stickster> (not Docs, but the Websites guys)
[22 May 21:14] <Tsagadai> I like your idea of individual docs projects,
stickster. guides are quite different from release notes
[22 May 21:15] <asgeirf> publican is easier for translation from the
aspect of checking out the whole project from VCS. the current toolchain
integrates better with the current translation statistics/transifex
system. The transifex developers are working on addressing the issue :)
[22 May 21:15] <stickster> The release notes, as I see it, are sort of
an animal on their own.
[22 May 21:15] <mdious> opensuse wiki is fully localized - very hawt
hawt hawt: http://www.opensuse.org/
[22 May 21:15] <stickster> mdious: Actually, if you look at their
process -- it's all manual!
[22 May 21:15] <stickster> We want to find a way to do MediaWiki in an
i18n-friendly way
[22 May 21:16] <ryanlerch> individual docs projects might be less
daunting for new contributors...
[22 May 21:16] <stickster> I think we might try to get OpenSuSE to put
some muscle into it too
[22 May 21:16] <stickster> ryanlerch: I agree.
[22 May 21:16] <stickster> So each of these "book" (or sizable
"article") projects could be a fedorahosted.org project.
[22 May 21:17] <stickster> Then the *Fedora installable part* could be
in the regular Fedora source code management, the same way any other
package is.
[22 May 21:18] <stickster> A spec file, BuildRequires: publican, etc.,
and it can be maintained, built, and shipped in Fedora.
[22 May 21:18] <stickster> The "upstream" for that package would be at
fedorahosted.org
[22 May 21:18] <jfearn> publican can spit out spec and srpms based on
the docbook
[22 May 21:19] <mdious> ryanlerch: you're such a publican and graphics
ninja, when will you be sitting next to me at work...
[22 May 21:19] <stickster> We could check that out with the package
maintainer folks
[22 May 21:20] <stickster> I have a feeling that for consistency,
anything we want to roll in the distro would need to have a specfile
sitting in the Packages CVS 
[22 May 21:20] <stickster> (which hopefully will be replaced some day
not too far off with a better SCM)
[22 May 21:20] <jfearn> stickster, sure, but you create it from you book
source and check it in to the CVS repo for building
[22 May 21:21] <stickster> jfearn: Exactly what I was thinking
[22 May 21:21] <stickster> And I suppose there's no harm in it being
duplicated in the fedorahosted tree because other downstreams (like
opensuse) could use it if desired.
[22 May 21:21] <stickster> sorry, "it" == "spec file"
[22 May 21:22] <stickster> The point being, we really need to decouple
our toolchain from the docs themselves.
[22 May 21:22] <jsmith> Exactly...
[22 May 21:22] <stickster> What I think we need help with is going
through the stuff in docs-common, characterizing it, and finding out
where there are potential things we could RFE into publican
[22 May 21:23] <stickster> If someone wants to spin off some other
toolchain, the more the merrier
[22 May 21:23] <mdious> andyfitz was saying
http://scenari-platform.org/projects/scenari/en/pres/co/ this is
good....
[22 May 21:23] <mdious>
(http://scenari-platform.org/trac/scenari/wiki/SCENARIbuilder)
[22 May 21:24] <jfearn> that scenari looks rockin for interactive stuff
[22 May 21:25] <stickster> Is that open source?
[22 May 21:25] <jfearn> stickster, yeah, gpl
[22 May 21:25] * stickster having a hard time digging through the flashy
site :-D
[22 May 21:25] <jmtaylor> french only though atm?
[22 May 21:26] <stickster> Um... holy crap
[22 May 21:26] <mdious> jmtaylor: the error messages are a bit hard to
decode...
[22 May 21:26] <stickster> that's pretty wild
[22 May 21:26] <jmtaylor> mdious: I bet :)
[22 May 21:26] <andyfitz> the up to date content is in french
[22 May 21:26] *** You disconnected
[22 May 21:26] *** You connected
[22 May 21:26] <mdious> I think if you want to try it, go for
http://scenari-platform.org/projects/scenari/files/SCENARIchain/lin/latestStable/ ;)
[22 May 21:27] <andyfitz> and their upstream format is not exactly
docbook
[22 May 21:27] <andyfitz> but their editor is what im keen on
[22 May 21:27] <andyfitz> its xul
[22 May 21:27] <stickster> Whoops
[22 May 21:27] <jmtaylor> definately neat
[22 May 21:27] <andyfitz> is a _good_ visual editor
[22 May 21:27] <jfearn> I could imagine a whole website dedicated to
interactive walk throughs based on that
[22 May 21:28] <stickster> The interactive training bit seems pretty
interesting to me
[22 May 21:28] <stickster> All right, well back to the agenda here
[22 May 21:29] <stickster> So some of the things that we might want to
capture from the existing toolchain are... (anyone pitch in as desired)
[22 May 21:29] <stickster> jfearn: How does publican handle OMF
creation?
[22 May 21:30] * stickster will continue asking dummy questions, be
warned...
[22 May 21:30] <jfearn> stickster, it has a stub atm, not well tested
[22 May 21:31] <stickster> We create OMF's using just some XSLT IIRC
[22 May 21:31] <jsmith> 
[22 May 21:31] * jsmith wishes Conglomerate were a bit more robust
[22 May 21:32] * stickster hands jsmith a long, white beard.
[22 May 21:32] <andyfitz> conglomerate is the biggest tease to every
technical writer... hence my interest in the senari designer
[22 May 21:32] <jsmith> OMF?
[22 May 21:33] <jfearn> stickster, we switched to html-single for
desktop docs, the OMF stuff would be easy to fix if you want xml on the
gnome desktop
[22 May 21:33] <jsmith> 
[22 May 21:33] * jsmith can't remember what OMF stands for
[22 May 21:33] <stickster> Object Metadata Framework?
[22 May 21:33] * stickster digs back into cobwebs of brain
[22 May 21:33] <stickster> It's basically a metadata container about
another data file
[22 May 21:34] <stickster> In this case, scrollkeeper uses OMF to record
documentation available on your system
[22 May 21:34] <stickster> GNOME Help Viewer (yelp) scans these to
present docs in the Help browser
[22 May 21:34] <jsmith> Ah, gotcha
[22 May 21:35] <jsmith> I knew I'd heard the acronym before
[22 May 21:35] <stickster> jfearn: Something else that might be useful
is the SVG idea for logos or such
[22 May 21:35] <stickster> We have some bits in docs-common/images/ that
we used for the watermarks
[22 May 21:36] <stickster> A possible application might be SVG based
diagrams that you want to include in a document but still have it
translated
[22 May 21:37] <stickster> There might be some hurdles there but it's a
thought
[22 May 21:37] <jfearn> stickster, publican handles per-brand and
per-language image files
[22 May 21:37] <andyfitz> not many,  gnome doc utils makes translating
svg easy
[22 May 21:37] <stickster> jfearn: How are those image files created?
[22 May 21:38] <andyfitz> inkscape
[22 May 21:38] <jfearn> stickster, by andyfitz ;)
[22 May 21:38] <stickster> haha
[22 May 21:38] <stickster> So they're stored with a publican doc
as .svg?
[22 May 21:39] <jfearn> stickster, yeah
[22 May 21:39] <stickster> awesome
[22 May 21:39] * stickster continues asking more Publican 101 questions.
[22 May 21:40] <stickster> jfearn: Is publican pretty much DocBook
version-agnostic at this point?
[22 May 21:40] <andyfitz> in a typical pulican workflow, content is
docbook xml and images are svg xml..  both can be translated and
rendered to different formats together or apart
[22 May 21:40] <mdious> 
[22 May 21:40] * mdious glares at Red Hat campers
[22 May 21:40] <stickster> andyfitz: Exactly what I was hoping for,
cool.
[22 May 21:40] <jfearn> stickster, yes, but it deafults to 4.5
[22 May 21:40] <stickster> Cool, so XInclude support is there.
[22 May 21:41] <jfearn> stickster, oh yeah
[22 May 21:42] <stickster> jsmith: What were some of the things you saw
in the current F-Docs toolchain that we would want to capture?
[22 May 21:45] <stickster> jfearn: Seems to me we could continue to
build HTML copies, apply CSS, and publish as needed, just as you guys do
I'm sure
[22 May 21:45] <jfearn> stickster, you just set your barnd to fedora and
you have the whole payload
[22 May 21:45] <jfearn> brand
[22 May 21:45] <stickster> Here's what I'm thinking... maybe we should
try doing this with the documentation-guide as a test doc.
[22 May 21:46] <stickster> I think the release notes are pretty much the
oddball when it comes to our documentation modules, overall.
[22 May 21:46] <stickster> Oh wait.
[22 May 21:46] <stickster> What I just said makes absolutely no sense.
[22 May 21:46] <stickster> Because the whole guide will essentially be
wrong as soon as we start in on it!
[22 May 21:47] <stickster> Maybe instead we could try something like the
rpm guide.
[22 May 21:47] <stickster> AHA!
[22 May 21:47] <jfearn> stickster, I already did the rpm guide, so that
is a good choice :P
[22 May 21:47] <stickster> Well, phooey.
[22 May 21:47] <stickster> Oh, you mean you tested on it?
[22 May 21:47] * stickster thought for a minute it was already out there
in fedorahosted land and he misse dit
[22 May 21:48] <jfearn> stickster, I ported it to publican, but it
doesn't have any translations so it's easy
[22 May 21:48] <quaid> 
[22 May 21:48] * quaid stumbles in after beating his network into
submission
[22 May 21:48] <stickster> jfearn: So we should go to Phase II, which is
moving that puppy to fedorahosted.org.
[22 May 21:48] <quaid> sorry, 'twas unavoidable
[22 May 21:48] <stickster> quaid: np, there's a big buffer waiting for
you though :-D
[22 May 21:49] <stickster> jfearn: we could put it in git! w00t
[22 May 21:49] <stickster> Anyhow, once we have that set up, we could do
a standard package review bug entry in bugzilla, get the package
approved, and try this out.
[22 May 21:49] <jfearn> stickster, lol, yeah we could
[22 May 21:50] <stickster> The fedorahosted site would include
instructions for how to download and contribute to the doc, with a few
easy commands.
[22 May 21:51] <stickster> Bingo, spread the docs work out to the
community.
[22 May 21:51] <jfearn> stickster, git might be a big step for some
contributers
[22 May 21:51] <stickster> Yeah, I was kinda joking ;-)
[22 May 21:51] <stickster> SVN though. Please for the love of all that's
holy, no CVS.
[22 May 21:52] <jfearn> yeah, SVN is the ... comfortable choice
[22 May 21:52] <mdious> jfearn: maybe you could open source the svn
tutorial we have here :P
[22 May 21:52] <mdious> and build it with publican
[22 May 21:52] <stickster> I've been getting to know git, and if you're
just doing work like you would in SVN, there's really no more of a bar
there.
[22 May 21:52] <stickster> But that's a sidebar... SVN is peachy for me.
[22 May 21:53] <stickster> (weeds)
[22 May 21:53] <stickster> OK, so what're our next actions then?
[22 May 21:54] <quaid> 
[22 May 21:54] * quaid is all caught up on buffer
[22 May 21:54] <stickster> 1. Get a fedorahosted project for rpm-guide
(SVN preferably)
[22 May 21:54] <stickster> 2. Enter the doc there
[22 May 21:54] <stickster> & make sure it builds as needed
[22 May 21:55] <jfearn> 0. find a _writer_ to own the package, since we
want to test how it works for the target audience
[22 May 21:55] <stickster> jfearn: Ah, thank you, that's right -- we no
longer have that maintainer around these parts.
[22 May 21:56] <quaid> maybe we need an active doc then
[22 May 21:56] <quaid> software management guide, for example
[22 May 21:56] <jfearn> does it have translations?
[22 May 21:56] <stickster> I believe so
[22 May 21:56] <jfearn> rock
[22 May 21:57] <jfearn> brb
[22 May 21:58] <quaid> also, don't we want a new fh.o project for
docs-common?
[22 May 21:58] <quaid> give it a new name and start tearing it apart
[22 May 21:58] <quaid> or are you thinking we won't need a wrapper
toolchain
[22 May 21:58] <stickster> quaid: You know, I've been looking at it on
and off for the past few hours
[22 May 21:58] <quaid> and push RFEs into publican?
[22 May 21:58] <stickster> quaid: And I think most of it, honestly? is
"file 13" fodder.
[22 May 21:59] <stickster> And that's tough to say, seeing how many
hours of my life I spent figuring it out and then trying to keep it
working over the past two+ years.
[22 May 21:59] <stickster> But hey! It was a great learning
experience. :-D
[22 May 21:59] <quaid> oh, sure, everything from the garden
[22 May 21:59] <quaid> turns into compost
[22 May 21:59] <quaid> or
[22 May 22:00] <mdious> quaid: wrapper toolchain?
[22 May 22:00] <quaid> oh, wait,
[22 May 22:00] <quaid> is this a mixed channel?
[22 May 22:00] <quaid> 
[22 May 22:00] * quaid won't say what else the garden turns into then
[22 May 22:00] <jfearn> it would probably be a good idea to spin
publican-fedora in to a seperate project and hand that over to the
fedora docs team
[22 May 22:00] <quaid> -1
[22 May 22:00] <stickster> Yeah, sounds forky to me
[22 May 22:00] <quaid> we can't maintain an upstream like that
[22 May 22:01] <jfearn> OK, but that is the equiv of docs-common in
publican
[22 May 22:01] <stickster> Why wouldn't we want to have a joint upstream
project like a freeIPA or whatever?
[22 May 22:01] <stickster> This doesn't have to turn into, for example,
"Dump bugs on jfearn, woohoo"
[22 May 22:02] <jfearn> stickster, well publican-fedora is the fedora
specifc branding of publican output
[22 May 22:02] <quaid> right, we have resources to help with upstream
[22 May 22:02] <quaid> that is the Fedora way, not to own the upsteam
(per se), but to work there actively.
[22 May 22:03] <stickster> Yeah, I think we should definitely provide
resources to participate
[22 May 22:04] <jfearn> no problem, it's just that a seperate
docs-common package is basically what publican-fedora is :)
[22 May 22:04] <stickster> Yeah
[22 May 22:04] <stickster> I think what I'm saying is, I'm at a point
where I want to "call it a day" with the old docs-common
[22 May 22:04] <jfearn> 
[22 May 22:04] * jfearn fetches the shovel
[22 May 22:04] <quaid> right O
[22 May 22:05] <quaid> compost and ... other stuff
[22 May 22:05] <stickster> I still think that relying on the
kdesdk-utils is a much heavier footprint for this stuff, but meh.
[22 May 22:05] <stickster> If someone *really* cares about it, let them
port it or whatever.
[22 May 22:05] <jfearn> stickster, there is a bug opened to split out
the two binaries we use from that
[22 May 22:06] <stickster> jfearn: Actually, that's done
[22 May 22:06] <jfearn> stickster, yay!
[22 May 22:06] <stickster> kdesdk-utils now exists, only contains those
two
[22 May 22:06] <stickster> That's why I was trying to rebuild publican
here -- testing a specfile patch
[22 May 22:06] <jfearn> stickster, it shouldn't need a pacth since it
requires the files not a package
[22 May 22:07] <stickster> jfearn: Did I forget to update?
[22 May 22:07] <jfearn> my typing is extra lysdexic today :/
[22 May 22:07] <stickster> jfearn: Hm, in the F-9 branch it's still
'Requires: kdesdk'
[22 May 22:07] <jfearn> stickster, ahh no, it's fixed in the new version
in SVN
[22 May 22:07] <stickster> Aha
[22 May 22:08] <stickster> jfearn: So what I did was basically just to
make that 'kdesdk-utils' and move on
[22 May 22:08] <jfearn> fixed: upstream :P
[22 May 22:08] <jfearn> stickster, yeah
[22 May 22:09] <jfearn> although the build is busted in F9 for some
reason :/
[22 May 22:09] <stickster> jfearn: That's what I was encountering, I'm
pretty sure ;-)
[22 May 22:09] <mdious> mmm, these cornflakes are super good today
[22 May 22:10] * stickster throws ice cream at mdious
[22 May 22:10] <jfearn> stickster, funny it built in dvel before the cvs
update
[22 May 22:10] <mdious> nom nom nom
[22 May 22:10] <stickster> So quaid -- maybe that is a list topic then
-- who will own the SMG in fedorahosted?
[22 May 22:10] <stickster> jsmith did the new porting of content
[22 May 22:11] <Tsagadai> mdious don't make me tell susan :D
[22 May 22:11] <stickster> but he's awful busy these days.
[22 May 22:11] <mdious> Tsagadai: just don't tell her I have banana on
them too....
[22 May 22:12] <stickster> quaid: We need someone who's capable of
recording the tasks of putting a doc into fedorahosted, I suppose --
that would be something we'd want to have in our process doc.
[22 May 22:12] <jmtaylor> stickster: if jsmith is too busy I would be
willing
[22 May 22:12] <stickster> jmtaylor: ^^^
[22 May 22:13] <stickster> jmtaylor: So you'd approach this from the
standpoint of, "I'm a new writer, how do I put a doc I've made (publican
or otherwise) somewhere the community can work on it with me?"
[22 May 22:13] <stickster> And as questions arise, we all help find the
answers and you scribble them down for later use by every other guy who
comes after :-D
[22 May 22:14] <stickster> That becomes the basis for new content in the
Documentation Guide.
[22 May 22:14] <stickster> Get it?
[22 May 22:14] <jmtaylor> stickster: since we are at ground zero, makes
sense to me
[22 May 22:14] <stickster> :-)

-------------- 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/20080522/10053870/attachment.sig>