A question (or three) about linking content between packages

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.

So far, that's pretty simple.

The first wrinkle is that I'm anticipating that the package maintainers
will not necessarily want to maintain .page files, so I'm trying to figure
out how close to the automatic-linking bliss you can get using HTML.

(In practice, if this clarifies anything, we're talking about font packages
here. They will often come with some HTML documentation from upstream and,
on top of that, distro package maintainers may feel reluctant to adopt an
application-specific file format that would potentially not be readable in
some environments. Perhaps you disagree with that assessment, but that's
where we're starting from.)

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?

For instance, if installing the distro's fonts-foo package copies its help
files into /usr/share/help/fonts-foo/index.html (et al), would appending
installed-system-fonts/index.page with an explicit href link to the new
fonts-foo page do the trick? Over time, you'd have to worry about that
installed-system-fonts/index.page getting corrupted by malformed packages,
I suppose; I'm only wanting to understand the linking possibilities.
Post-install scripts do a lot; I don't want to shortchange them.

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?

My initial thought was that you could keep another tally list running in
(.e.g.) ~/.local/share/help/installed-system-fonts/local.page, and insist
that the installer add a new direct link to that file for each new install.
So that launching 'yelp help:installed-system-fonts" would show you *both*
the list of distro packages linked to underneath /usr/share/help/ and the
list that the installer has handled under ~/.local/share/help/.

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.

Thanks,
Nate
-- 
nathan.p.willis
nwillis at glyphography.com <http://identi.ca/n8>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20180905/5d0500c6/attachment.html>