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

[Luc Pionchon <pionchon luc gmail com>]

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