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
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
