On Sun, Dec 13, 2009 at 08:14:21PM -0600, Shaun McCance wrote:
On Fri, 2009-12-11 at 10:06 -0500, John J. McDonough wrote:
> On Thu, 2009-12-10 at 22:01 -0600, Shaun McCance wrote:
> > the primary selling point is that
> > it's designed around the idea that downstream distributors will
> > extend and modify upstream documents.
>
> Now this sounds like a good idea
So I understand the reluctance to deal with yet another format.
There certainly are more than enough of them out there. But I
think it's important to stress that Mallard is in a different
class than any other format you're using. The only other open
format that's doing similar things is DITA.
Aside from the point that Mallard is much easier to deal with,
its primary strength over DITA is that guides ("topic maps" in
DITA lingo) are dynamic, responding to what's installed.
This was an intentional design goal from the outset to help us
finally solve two related cases: distro additions to upstream
documents and plugin documentation.
From the standpoint of the casual user, the Mallard based docs are
more functional and usable because they respond to natural questions:
"How do I do <X>?" instead of the old-style
"Intro/Topic1/Topic2..."
organization which often requires the user to browse for longer to get
the answer to a question.
[...snip...]
> > * All languages are installed, whether or not needed. The
installed
> > size in all languages for our longer documents is hundreds of megabytes.
> >
> > I don't see how this has anything to do with Yelp. This
> > is a matter of how you package your files. Are those pesky
> > OMF files keeping you from doing language packs properly?
> > I'm fairly certain there's nothing in the 3.0 designs that
> > will force this. The Ubuntu team is also interested in
> > doing language packs for documentation, so I want to get
> > this right.
>
> Clearly it doesn't have anything to do with Yelp. This has to do with
> decisions about how we want to trade off disk footprint for user
> flexibility. There are limitations to RPM that constrain us here, and I
> don't see APT as being any different. Indeed, this is a place where
> Yelp might have a leg up over HTML.
So it seems to me (said naively) that if one knows certain things
about the packages one is installing, one can build an installer
that's a bit smarter and more user-friendly. Overcome limitations
in the package system with package name conventions or some such.
Perhaps somebody could build a specialized Fedora documentation
viewer using libyelp and PackageKit that can find an install
documentation for the user. Or maybe we can build that into
Yelp. Any UX people around that could create some work flows
or mockups? I think this would be interesting to look into.
Perhaps this could be done by having documentation RPMs advertise a
capability, which PackageKit could then locate and install in a manner
similar to codecs and fonts.
> > * Packages for larger documents may be hundreds of
megabytes. Each
> > language may (should) have localised images. Images can take up
> > substantial space. Limiting images is not an option as images are
> > useful for various aspects of learning and documentation.
> >
> > Right, so this is the language pack thing again. I will say
> > that one of the nice things in Yelp 3.0 is that it looks up
> > everything according to a path, and can fall back to content
> > elsewhere in the path. This includes images. So if you have
> > both a "C" version and a localized version of a document, and
> > you have non-localized images (common for including icons in
> > documentation), you don't need to install those images with
> > the localized document.
>
> Isn't this pretty close to where it is now? Cant we just add a doc,
> then add an OMF, and away we go? Am I forgetting something?
Yelp 2 can find the right document for your language based on
a path. But once it finds it, it's stuck in that directory.
In Yelp 3, subresources (like images) are located according
to this path as well. (This was a pretty critical feature
for getting Mallard right.)
So images and other common bits could still be located based on a
relative path, correct? Such as "../../../images/foobar.png"?
--
Paul W. Frields
http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - -
http://pfrields.fedorapeople.org/
irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug