Re: How to integrate local help topics in system wide help?



On 11 May 2013 08:11, Jiro Matsuzawa <jmatsuzawa gnome org> wrote:

Hi Luc,

Hi Jiro,



I think you need to install your help into $XDG_DATA_HOME/help. If the
environment variable, XDG_DATA_HOME, is not set, it means $HOME/.local/share.
The directory layout for your help would be:
$HOME/.local/share/help/LANG/DOCUMENT_ID(your plugin name)/xxx.page

I hope it works. Try it.


This is what I get:


$HOME/.local/share/help/C/tomboy/my-tomboy-addin.page
                          ^^^^^^
------------------------------------------------------------------------
<page xmlns="..."
      type="topic"
      id="my-tomboy-addin">
<info>
  <link type="guide" xref="index#advanced"/>
  <link type="topic" xref="edit-notes"/>
</info>
------------------------------------------------------------------------

==> Will appear inside tomboy help document, as referenced:

- the 1st <link> inserts my topic into Tomboy's index#advanced section
- the 2nd <link> inserts a link to my topic into Tomboy's edit-notes page,
                 in the "More Information" bottom section




For a new help document:

$HOME/.local/share/help/C/my-own-guide/index.page
                          ^^^^^^^^^^^^
------------------------------------------------------------------------
<page xmlns="..."
      type="guide"
      id="index">
(...)
  <p><link xref="help:gnote"/> </p>
  <p><link xref="help:gnome-help"/></p>
  <p><link xref="help:tomboy"/> fails </p>
------------------------------------------------------------------------

==> will appear in the "All Help Documents" page

- we can link to other documents.
  (Some failed, I am not sure which xref should be used)



Help tools including yelp respect the XDG Help Specification [1] and XDG
Base Directory Specification [2]. See the documents for details.

[1] http://www.freedesktop.org/wiki/Specifications/help-spec

(it is a docbook XML document, not very friendly to read)



Thank you very much for your help!

Luc




[2] http://standards.freedesktop.org/basedir-spec/latest/


On Tue, Apr 30, 2013 at 11:11 PM, Luc Pionchon <pionchon luc gmail com> wrote:
On 30 April 2013 16:04, Petr Kovar <pknbe volny cz> wrote:

Hey Luc,


Hey Petr,


On Mon, 29 Apr 2013 18:19:35 +0300
Luc Pionchon <pionchon luc gmail com> wrote:

Hello,

I am wondering how to install a local help page so that it integrates
with
the system help. Especially in the context of user plugin help page. But
this could be for any user help page with links to/from the system help.

If you only need to link to a page in gnome-help (if that's what you mean
by system help) from your standalone docs, prefix the ID of the page you
want to link to with "help:gnome-help/", for example:

<link xref="help:gnome-help/index">link to gnome-help index page</link>


Yes, the link works in this direction.

With one detail though, if you set your link with no value <link
xref="help:gnome-help/index"/>, then yelp does not get the label from the
referenced page, it just uses "help:gnome-help/index".

How to get the referenced title on the link?



(Another issue, is that "help:gnome-help/index" is a magic value. You have
to look at the source code of the page to get the value. But lets assume
that this one is acceptable for now.)


This will not work for all links in Mallard however, so if you want your
pages to be part of gnome-help so that you can use automatic linking, for


Yes, I want it to work also in that direction.


example, you need to install your pages into the gnome-help installation
directory (which is /usr/share/help/C/gnome-help/ for C locale on Fedora,
and other distros will likely use similar paths). That's what we do with
Getting Started, which is basically a plugin for gnome-help.


I want it to work for a user who does not have administrator rights.

To rephrase the use case,
it is for a user plugin help page (*).
The page is (somewhere) in $HOME.
It is certainly needed to register this page to the help system.
Then the page must show in the Application help, under the specified
page/section.

(*) it could be generalized to any complementary help page that a user feel
needed. Either as a topic of an existing guide, either as a new guide.


How should I proceed?

Luc

_______________________________________________
gnome-doc-list mailing list
gnome-doc-list gnome org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list




--
Jiro Matsuzawa
E-mail:
 jmatsuzawa gnome org
 matsuzawa jr gmail com
GPG Key ID: 0xECC442E9
GPG Key Fingerprint: E086 C14A 869F BB0E 3541 19EB E370 B08B ECC4 42E9


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]