A question (or three) about linking content between packages

On Sat, 2019-05-04 at 14:55 +0100, Nathan Willis wrote:
> Hi list,
> 
> Thought I might try this again, see if I can catch a different set of
> eyes or something.
> 
> I'm trying to figure out how to link between a Help guide page
> provided by one package and individual pages provided separately.
> 
> My closest attempt was to install a guide page in /usr/share/help/
> and link in subsequent pages from .local/share/help/, but when I
> tried that, opening Yelp would _only_ show the .local page, and lose
> the /usr/ guide entirely.
> 
> I'm really not clear if this is breaking the spec, simply undefined
> behavior (and where), or a Yelp bug.
> 
> Anyone have thoughts?

I'm trying to figure out why this isn't working for you, and it's
tricky without sitting in front of your computer. What you describe is
how Mallard is supposed to work in Yelp. To test this feature, I just
created a file ~/.local/share/help/C/gnome-help/foo.page with this:

<page xmlns="http://projectmallard.org/1.0/" id="foo">
<info>
<link type="guide" xref="index"/>
</info>
<title>Foo</title>
</page>

When I then call `yelp help:gnome-help`, I see the front guide page
with a link to Foo. Does that work for you?

--
Shaun

> 
> Thanks,
> Nate
> 
> On Wed, Sep 5, 2018 at 11:44 PM Nathan Willis <
> nwillis at glyphography.com> wrote:
> > Hello Mallard Nation,
> > 
> > I'm rather new to designing Mallard books and I'm trying to spec
> > out a proposed project. So I've got a couple of questions I'm
> > hoping the community can educate me on.
> > 
> > The core idea is to add help (in the form of individual per-package 
> > topic pages) to a set of desktop Linux packages so that you could
> > visit the guide page and it will show you all the pages from
> > whichever individual packages you happen to have currently
> > installed.
> > 
> > ... 
> > 
> > As I understand it from the manual and a couple of tests, though, I
> > can't have a guide page (e.g., /usr/share/help/installed-system-
> > fonts/index.page) that automatically finds and links to HTML pages.
> > Is that correct? If so, is there some workaround worth exploring?
> > ...
> > The second wrinkle is that, ideally, we'd also be able to do the
> > equivalent for things installed in the user's home directory (that
> > being the use case for a font manager app as well as what you get
> > when downloading from Google Fonts and the like). So, if that user-
> > mode installer copies help files into ~/.local/share/help/fonts-
> > bar/ (from a downloaded .zip file, not via a distro package), what
> > would be the best way to pick that up in the same help guide?
> > ...
> > But with some test files I played around with, I couldn't get that
> > to work at all. Specifically, launching yelp on that guide (as
> > above) shows only the ~/.local/ page, and drops the content in
> > /usr/share/ entirely. That was on a fresh Ubuntu 18.04 machine.
> > It's possible there's something funky going on that I just haven't
> > noticed yet, but I'm more concerned that I'm missing something
> > crucial in the fundamental topic/guide/page/HTML architecture. If
> > so, I'd certainly appreciate some help figuring out what it is.
> 
> 
> _______________________________________________
> mallard-list mailing list
> mallard-list at projectmallard.org
> http://projectmallard.org/mailman/listinfo/mallard-list