8:14 p.m.
On Fri, 2009-12-11 at 10:06 -0500, John J. McDonough wrote:
Shaun,
Thanks for the excellent summary ...
(lotsa clips below)
On Thu, 2009-12-10 at 22:01 -0600, Shaun McCance wrote:
> The front page of Yelp will be the Desktop Help ("User Guide"),
> which will be a Mallard document. Mallard is a new format for
Oh goodie, yet another format
Yes, the previous wheel wasn't round enough for my liking. ;-)
> 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.
> Yelp is moving away from the focus on all installed documents,
I guess I don't totally understand what this means
Some particular consequences of this design:
* Yelp 2 shows the listing of all installed documents as the
default front page. Yelp 3 shows the Desktop Help. You can
get to the listing, but it's not the first thing you see.
* In Yelp 2, search searches all installed documents. In 3,
it searches the document you're looking at by default. You
can then broaden your search if you like.
* In Yelp 3, there will be a single primary window associated
with each document. You can open more explicitly, but they're
secondary. When an application requests a page in a document
to be shown, it will do it in the primary window. This helps
alleviate the "cat standing on the F1 key" problem.
* Bookmarks will be grouped by document. Bookmarks for the
current document are shown right in the Bookmarks menu, while
bookmarks for other documents are available from submenus.
> There are no real size limitations, except possibly the
recursion
> limits in libxml2, although I doubt you're hitting those. This
> is probably just a symptom of the speed issue below.
Yelp has some very strange behaviors. It takes a while for the window
to appear,
That's because of Rarian. When I took Yelp over years ago,
I put a lot of work into making sure startup didn't block
on a bunch of I/O. That got lost. I'll fix it.
and another while to open a document. However, after a
document appears to open, the CPU stays pinned for quite some time.
So the way it currently processes DocBook documents is that
it has a single long-running XSLT thread that generates all
the chunks. It can display a chunk as soon as its ready, so
chunks that are early in the document can display early.
I'm going to try doing each page in its own XSLT processing
run as it's requested. I think that will produce better
results.
There is, however, still the general penalty of having to
read and parse the entire XML file before anything else can
be done.
> * 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.
> * 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.)
--
Shaun