Improve yelp index layout

Subcribing Don Scorgie so that he can have a look at this patch sometime.

At the moment I think the help isn't extensive enough to need a "Common questions" section -- pretty much any likely question will be only two clicks from the front page. So that dependency wouldn't be necessary.

While testing this patch further I've noticed another issue with it - the material in the right hand column needs to show up only on the page "x-yelp-toc:" but not on the page "#ApplicationsMultimedia"... this is a problem where I run out of knowledge, and Don steps in, I hope!

An interesting problem you've got yourself there. I've played around with the patch a little, however I don't have Feisty.

A couple of questions first:
* IIRC, the manuals on the front page were going to include links to other TOC pages, is that still correct?

* Is the left sidebar supposed to look like that on every page, or only on the front one (reverting back to the other, older style on other TOC pages)?

I'll also note a couple of points:
* Mixing the html links with the normal help links seems like a bad idea (to me). There are no distinguishing between them atm. (and adding code to distinguish is pretty horrific)

* The bullet point style is to do with the CSS and is more a trial-and-error than anything else (at least, for me it is).

* Translating the XSLT is pretty evil (I think). Instead, somehow managing to get the stuff into the data/toc.xml.in file would be better (as all the translation structure in the code can handle it there).

Other than that, I think I need to play around with it somewhat more and see what's what.

\o/ welcome back Don!

On Thu, January 25, 2007 5:34 pm, Don Scorgie wrote:
> An interesting problem you've got yourself there. I've played around
> with the patch a little, however I don't have Feisty.
>
> A couple of questions first:
> * IIRC, the manuals on the front page were going to include links to other
> TOC pages, is that still correct?

Yes, that's correct.

> * Is the left sidebar supposed to look like that on every page, or only
> on the front one (reverting back to the other, older style on other TOC
> pages)?

I think probably the left sidebar would only be present on the front page.
Other TOC pages would not have a sidebar at all, ideally.

> I'll also note a couple of points:
> * Mixing the html links with the normal help links seems like a bad idea
> (to me). There are no distinguishing between them atm. (and adding code
> to distinguish is pretty horrific)

Which links are you talking about? Aren't links to http always the same as
internal links in Yelp?

> * The bullet point style is to do with the CSS and is more a trial-and-
> error than anything else (at least, for me it is).

Ok, I'm sure we can sort that out.

> * Translating the XSLT is pretty evil (I think). Instead, somehow
> managing to get the stuff into the data/toc.xml.in file would be better
> (as all the translation structure in the code can handle it there).

I've included it as html, rather than XSLT. However, potentially we can
certainly move it elsewhere, maybe even into the ubuntu-docs package.
Could it be done in xml?

Matt

Results can be seen at http://scorgie.org/UHC-Feisty.png

Its pretty messy. The XSLT section to look at is in the <otherwise> block in stylesheets/toc.xsl. All the strings are in data/toc.xml.in (translatable).

You'll get the idea for adding more topics and questions (don't forget to add them to src/yelp-toc-pager.c as xml_trim_title). The formatting will need playing around with a bit. I haven't fixed the FAQ alignment.

Other TOC pages lose the left sidebar. Not sure about the hit in terms of speed to load the front page, but my brain says it shouldn't be a huge hit (I won't go into details of the twisted workings of my mind).

The docs that used to be on the front page are in a new TOC section (OldFront), if needed (GNOME User Guide, A11y guide and sys admin guide).

The patch probably conflicts with other Ubuntu patches (sorry, didn't really check this), so may need some careful surgery to make them all work together harmoniously.

With the (hopeful) introduction of Spoon next cycle, this work should be easier. I think (and hope).

Don: thanks a LOT for this!

Seb: are you able to help with merging this patch with the existing Ubuntu patches or removing conflicts?

Once we have a working patch uploaded, then I can adjust it as needed to add all the topics which we envisage and then we can tinker with the layout.

The patch conflicts with 06_ubuntu_index.patch, it is supposed to be used instead of that one?

... and here's where the delicate surgery possibly comes in (sorry!). The current 06 patch has various things in it to reorder the front page (in yelp-toc-pager.c). Not sure if these docs will be visible anywhere in the new TOC structure (Matt?).

Other than that, the patch should replace the 06 patch, though there are a few nice descriptions in the current patch that maybe should be used in the new one.

Having said that, I think it might be better to get the links in the patch working properly first. Right now, they all point to "placeholder" which will break things nicely.

Also, another comment: If the links are pointing to ghelp uris, they don't need to be translated as yelp will take care of them. This means they can be removed from toc.xml.in and hard-coded into the XSLT. This saves confusing translators and cuts down on potential translation errors. I'll try and update the patch somewhat today.

On Thu, February 1, 2007 2:40 pm, Don Scorgie wrote:
> ... and here's where the delicate surgery possibly comes in (sorry!).
> The current 06 patch has various things in it to reorder the front page
> (in yelp-toc-pager.c). Not sure if these docs will be visible anywhere
> in the new TOC structure (Matt?).

Well, I'm slightly lost, but if you're referring to the documents which
will appear in the "Topics" in the left hand column, then yes, we'll wish
to retain the ability to customise the order in which these appear.
However, this can be done later. The yelp which is currently in feisty has
not yet been updated with the new order of documents/topics.

> Having said that, I think it might be better to get the links in the
> patch working properly first. Right now, they all point to
> "placeholder" which will break things nicely.
>
> Also, another comment: If the links are pointing to ghelp uris, they
> don't need to be translated as yelp will take care of them. This means
> they can be removed from toc.xml.in and hard-coded into the XSLT. This
> saves confusing translators and cuts down on potential translation
> errors. I'll try and update the patch somewhat today.

What are you referring to here by "links"? We'll probably want to retain
the ability for translators to localise links to support resources on the
internet, where for example their community provides free support for that
language.

Matt
--
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Ok, I've had a look at the patch. Since it seems that you're not using scrollkeeper at all for the topic list (yay!), so I think that the 06 patch we have can be removed.

I think it's fine for now to have placeholder links. When we have the patch in yelp that I can easily edit, then I should be able to submit some updates to the patch which will replace the placeholders.

So, in sum - I think the only thing I'd change about the patch would be to make the link in the "Can't find the answer" section localisable. In the future we will probably want to split that section into a couple of different links to embellish better on the free/commercial support options.

Matt

Updated slightly. Moves the "Can't find the answer" link to be localisable. Cleans up the XSLT somewhat. Moves the ghelp uris to XSLT.

> Well, I'm slightly lost, but if you're referring to the documents which
> will appear in the "Topics" in the left hand column, then yes, we'll wish
> to retain the ability to customise the order in which these appear.
> However, this can be done later. The yelp which is currently in feisty has
> not yet been updated with the new order of documents/topics.

The topics are all hand-crafted in the data file. They can go in any order. I was referring to the current Ubuntu docs patch that puts the user-guide at the top in the right hand side of the current index.

> What are you referring to here by "links"? We'll probably want to retain
> the ability for translators to localise links to support resources on the
> internet, where for example their community provides free support for that
> language.

Links pointing to internet resources can (and should) remain where they are. However, local links (pointing to docbook files) are referenced using ghelp:foo#bar. In that case, yelp does some magic to choose the correct language to display these in [1]. They don't need to be localised. Its a little more pain when making changes (as 2 files need to be edited), but saves other errors occurring. Anyway, I've made the changes to do that in this patch, so you can see how it works.

Don

I've played with the patch and made some updates to it to ensure that it doesn't have broken links.

Don - the slight concern I have about this is that the list of topics depends on editing the patch, rather than on documents provided by ubuntu-docs (via scrollkeeper) as with the previous patch. That leads to the following questions:

1. Will yelp work ok without ubuntu-docs installed? What does yelp do if the documents are not installed?
2. Will derivative versions of Ubuntu be able to customise the list of topics by shipping ubuntu-docs *and* other documents to appear in the list of topics?

Matt

patch and panel changes uploaded for feature freeze, Matthew that would be nice to update the patch next to have correct "Common Questions" listed by example

Thanks for the upload. I'm attaching an updated patch to fix broken links and add the remaining topics for the documentation.

At the moment we don't have a final "Common Questions" list, but I've included one correct link and a placeholder to make it clear that this will change. We can appeal to the community for ideas about which questions to include.

Patch update uploaded, thank you for the work on that!

Seb - I'm attaching a new patch on this. It does the following things, I hope:

1. Turns the links under "Can't find the answer" into two separate links, one for free support and one for commercial support.
2. Removes "about-ubuntu" from the list of topics (we will still ship this document, linked from the menu, but it doesn't appear in yelp because it doesn't count as "help".

I'll try and do a further patch later to update the "Common Questions" section.

Btw, please test it works - I can't seem to build yelp myself because I don't know how to workaround this error:

dpkg-source: error: Version number suggests Ubuntu changes, but Maintainer: does not have Ubuntu address

Argh, I did the diff the wrong way around - hopefully this one works now!

New revision with the patch update:

 yelp (2.16.2-1ubuntu5) feisty; urgency=low
 .
   * debian/control.in:
     - Ubuntu Desktop Team maintainer
   * debian/patches/06_new_ubuntu_layout.patch:
     - patch update from Matthew East

Thanks Seb.

Here is another patch, which:

1) tidies up the linking on the "Getting More Help" section; and
2) adds some links to the "Common Questions" section.

I've tested the patch (thanks for fixing the maintainer!).

Matt

Thanks Seb.

Here is another patch, which:

1) tidies up the linking on the "Getting More Help" section; and
2) adds some links to the "Common Questions" section.

I've tested the patch (thanks for fixing the maintainer!).

Matt

Gah. Please use the latest comment :)

I forgot to tick the "patch" box on the attachment.

New patch uploaded:

 yelp (2.16.2-1ubuntu6) feisty; urgency=low
 .
   * debian/patches/06_new_ubuntu_layout.patch:
     - patch update from Matthew East

Thanks again Seb!

I've got one more patch, just to clarify some language in the previous one before the string freeze!

I'll attach it.

No problem, new update uploaded:

 yelp (2.16.2-1ubuntu7) feisty; urgency=low
 .
   * debian/patches/06_new_ubuntu_layout.patch:
     - patch update from Matthew East

Seb - thanks again for all the uploads!

I've discussed with Don some improvements we can make to the current patch, and he's redone the original patch to make the list of topics depend on scrollkeeper rather than being hardcoded. This is better because it means that if a user has ubuntu-docs uninstalled then the links don't appear, and derivatives can add documents as optional (edubuntu is keen to do this).

I've done a debdiff with changelog entry, which I'll attach to the bug. I've tested it, it works well!!

New version uploaded:

 yelp (2.16.2-1ubuntu8) feisty; urgency=low
 .
   [ Matthew East ]
   * Using scrollkeeper to determine topics rather than hardcoded:
     - work from Don Scorgie

Seb - one more patch on this. It is to allow edubuntu to use the new features as well for their handbook. It doesn't add any strings and I've tested it.

 yelp (2.18.0-0ubuntu3) feisty; urgency=low
 .
   * debian/patches/06_new_ubuntu_layout.patch:
     - patch update from Matthew East

This patch is currently not working in gutsy due to the changes in Yelp in the 2.20 release. I'm attaching a revised patch for Don which should fix this. Seb, can you take a look? Once it's uploaded, I'll attach a revised patch with a few minor modifications to the document structure that we've worked on in ubuntu-docs this release cycle.

yelp (2.19.90-0ubuntu3) gutsy; urgency=low

  * debian/06_new_ubuntu_layout.patch,debian/patches/06_new_ubuntu_layout.patch:
    - use ubuntu layout again, thanks Matthew East for the patch update
      (LP: #76944)

 -- Sebastien Bacher <email address hidden> Fri, 07 Sep 2007 13:39:12 +0200

On 07/09/2007, Sebastien Bacher <email address hidden> wrote:
> yelp (2.19.90-0ubuntu3) gutsy; urgency=low

Thanks for doing that so quickly! Extra incentive for me to upgrade to
gutsy now and check things out.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Another updated patch from Don, this fixes the topics being distributed in random order and gives them an order based on weighting (attachment coming)

Here is a consolidated patch which takes the last patch posted and:

1. Adds a topic for the accessibility guide in the front page; and
2. Includes the change in bug 144780 to fix the broken link described therein.

Please take a look.

your patch update doesn't work,

"patching file src/yelp-toc.c
patch: **** malformed patch at line 78: + tmp = g_strdup_printf ("%d", weight);"

On 01/10/2007, Sebastien Bacher <email address hidden> wrote:
> your patch update doesn't work,

Thanks for letting me know - I will try and find out why, but if you
have any idea, that would be helpful. It may be because I edited the
patch by hand rather than using diff.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

right, it's easy to break the diff format by editing it by hand (you can't add a new line there without changing the context number for example), I would recommend doing your changes again and generating a patch using diff then

Ok, here is an updated patch - it's a patch on the Ubuntu source package. I've successfully built a package and tested the fixes.

Sorry for the muddle.

yelp (2.20.0-0ubuntu2) gutsy; urgency=low

  * debian/patches/06_new_ubuntu_layout.patch:
    - patch update from Matthew East, fixes the "Connecting to the Internet"
      (LP: #76944, #144780)
  * debian/patches/07_rosetta_translations_update.patch:
    - updated

yelp (2.20.0-0ubuntu1) gutsy; urgency=low

  * New upstream version:
    - Jump to anchors in pages again (LP: #138777)
    - Respect theme settings on TOC again
    - Set automatic IDs on all divisions and respect chunk depth
    - Various minor fixes and crashers
    - New tangoified icon on TOC
    - Fix broken figures in docbooks
    - Better colour theming and icon support
  * debian/patches/04_text_color.patch:
    - dropped, deprecated by new upstream changes
  * debian/patches/06_new_ubuntu_layout.patch:
    - patch update from Don Scorgie
  * debian/patches/07_rosetta_translations_update.patch:
    - updated translations from rosetta

 -- Sebastien Bacher <email address hidden> Mon, 01 Oct 2007 18:11:06 +0200

Seb pointed out to me that the patch is broken on Ubuntu Hardy. Here's the proposed solution:

19:39:21 < DonS> mdke: the line in the patch: "if (!strncmp (cat, "General|Linux|Distributions|Other")) {"
19:39:37 < DonS> change that to "if (!strncmp (cat, "Core")) {" and all should be good again ;)

Has this change been made? I've been told that the customised layout is not currently working in Hardy.

There were a couple of other improvements / changes. Attached is the same patch, ported to 2.22. Not sure if the omf series' need updated or not.

I'll try to have a look at that patch, since I am packaging yelp right now. And I'll let you know.

Hi,

On Mon, Mar 10, 2008 at 8:16 PM, Don Scorgie <email address hidden> wrote:
> There were a couple of other improvements / changes. Attached is the
> same patch, ported to 2.22. Not sure if the omf series' need updated or
> not.

No, the omf series are all the same as before.

THANKS!

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Christophe - any problems with this?

Sorry Matthew for not keeping you informed...

Absolutly no problem at all. The patch has been incorporated in 2.22.0-0ubuntu1 version (and thus in the 2.22.0-0ubuntu2 which is the current version in hardy).

Thanks !

Right - marking as fix released.