Re: Tetravex Help

[Mario Blättermann <mariobl gnome org>]

Am Samstag, den 26.12.2009, 21:22 +0100 schrieb Milo Casagrande: 
> I managed to expand and fix up a little bit Tetravex help, and I
> pushed also the video, so you'll find it in the repo [1].
> Please, if somebody has some spare time, give it a read and post comments here.

I've converted the files into HTML with Shaun's Makefile. The Video
doesn't work, neither in Epiphany (gecko) nor in Yelp. There's no
clickable link to it. I've tried to feed my help browser directly with
the *.page file, but Yelp cannot handle it. That's a step back in
comparison with Yelp's ability to parse and handle XML (DocBook) files
directly. Well, Yelp cannot handle DocBook really, but it starts the
appropriate conversion in the background, without any arguments, just
typing "yelp db_file.xml".

Here's something from the created HTML:

----------------------------------------------------------------------
<div class="section" id="usage-video">
<div class="header"><h2 class="title">Video demonstration</h2></div>
<div class="contents">
<p class="p first-child">
      This small video shows how the game works, and what are the
possible movements.
    </p>
<p class="p">
      
        Simple demonstration of a game
      
    </p>
</div>
</div>
---------------------------------------------------------------------

As you can see, the link from the *.page file will not be converted to a
real HTML link. And another question: Once it works, does Yelp have to
start an embedded video player to play it, or could Yelp play it
directly? I mean, Yelp have either to be able to call a browser plugin
(based on Totem, MPlayer...) or it should include its own player
feature. What's the current solution here?

In general, I think it's a good idea to let appear a small video
wherever needed, especially for applications which needs time-critical
control, such as games. Your video is good, in any case videos should be
kept short. But it is some irritant, that it doesn't show a mouse
cursor.

There is another problem. The mail adress to this list (in winning.page)
is not formatted as a mail adress in the created HTML code, look here:

------------------------------------------------------------------------
<div class="section" id="winning-share">
<div class="header"><h2 class="title">Have a tip to share?</h2></div>
<div class="contents"><p class="p first-child">
      If you have a tip to share about <span
xmlns:e="http://projectmallard.org/experimental/"; class=" app">GNOME
Tetravex</span>, or any other
      GNOME games, write us at <span
xmlns:e="http://projectmallard.org/experimental/"; class="
email">gnome-doc-list gnome org</span>. We will add
      them here!
    </p></div>
</div>
------------------------------------------------------------------------

FYI: Currently I'm using g-d-u v0.18.0.

> Mario, do you think we can import it into the real GNOME repo? Apart
> for the license that we need to find a general solution, and the video
> section that if it doesn't work with Yelp we can't import that.

In my mind, it would be better to have it available in the real GNOME
Git repo. There's some time left before 2.30 will be released. Should be
possible to get it really working within some months.

But we have to find a valid solution for including the license stuff
before. OK, I agree, we don't have to display the program's license
within the docs. But we should include the doc license itself. A good
way to do so would be a "See also" link in the index.page which links to
a short version of the CC-BY. Have a look at the Kupfer docs to see what
I mean [1]. In fact, we have such a license.page (or license.xml?) in
the Empathy manual, which is the one and only real example for an
aims-to-complete Mallard doc. And I repeat my question another one: Why
it is shipped with, but doesn't appear anywhere?

[1]
http://git.gnome.org/browse/kupfer/tree/help/C/license.page?h=mallard-documentation

Cheers,
Mario