Re: Recipes documentation questions

On Wed, 22 Mar 2017 01:13:33 +0000
Paul Cutler <[email protected]> wrote:

> Hi all,
> 
> I've finished a first draft of user help for the new Recipes app.  Thanks
> to Michael Hill for reviewing it and giving me some feedback, which I've
> incorporated.  If anyone would like to review the help, it's in the recipes
> git repo in the wip/pcutler branch.
> 
> I have two questions:
> 
> 1 - Recipes may be one of the first apps to ship using a Flatpak that
> contains Yelp.  Yelp will be sandboxed like the app is thanks to the work
> of Matthias Clasen.  In share.page I've documented how to print a recipe
> and used gedit as a template, which has a note that links to
> gnome-user-docs for setting up a printer:
> 
>     <note style="important">
>       <p>Printing a recipe requires that you have connected and
>       configured your printer. If you have not done this, please consult the
>       <link href="help:gnome-help/printing">printing help for
> GNOME</link>.</p>
> 
> Matthias mentioned that the link will not work for users using Recipes
> installed by Flatpak as Yelp is sandboxed.  Do I include the link?  I'm
> leaning towards including it - users using Flatpak are more advanced and
> probably don't need another note telling them to open Yelp manually.  That
> way more inexperienced reading the help will have the link and it will work
> when distros ship Recipes.

Cross-referencing is always a good idea. So, this is just a workaround, but
if Flatpak prevents you from referencing other documents, maybe using
a web site link would work? 

https://help.gnome.org/users/gnome-help/stable/printing.html.en

A translators comment should be added to make sure that translators change
the link to https://help.gnome.org/users/gnome-help/stable/printing.html.LL
if the translation exists.

Cheers,
pk