Re: HELP_ID doesn't point to a real file, probably a macro

[Shaun McCance <shaunm gnome org>]

On Fri, 2013-03-08 at 21:35 +0100, Mario Blättermann wrote:
> Am 08.03.2013 20:19, schrieb Petr Kovar:
> > Hi,
> >
> > The issue seems to be fixed now after committing a dummy index.page file
> > needed by DL to recognize Mallard documentation. Thanks to Claude for
> > pointing me in the right direction!
> >
> >
> > On Fri, 08 Mar 2013 18:05:43 +0100
> > Mario Blättermann <mario blaettermann gmail com> wrote:
> >
> > > Am 08.03.2013 17:58, schrieb Petr Kovar:
> > > > Hey list,
> > > >
> > > > DL currently seems to error out with "HELP_ID doesn't point to a real
> > > > file, probably a macro" when updating a POT for:
> > > >
> > > > https://l10n.gnome.org/module/gnome-getting-started-docs/
> > > >
> > > > Looks like it might be related to the directory structure being different
> > > > from the HELP_ID. We share the HELP_ID with gnome-help from gnome-user-docs
> > > > so that we can install the getting-started files in the same installation
> > > > directory (normally /usr/share/help/C/gnome-help/).
> > > >
> > > > Would it help to move the files in the getting-started git repo from the
> > > > getting-started subdirectory to the gnome-help subdirectory?
> > > Could be... Well, it's a good idea to provide the getting-starting-docs
> > > as part of the user manual, but this way it is difficult to handle. It
> > > causes problems with creating the pot files as seen here. Moreover, when
> > > I check out the module and try to run "yelp ." as usual from the folder
> > > containing the *.page files, Yelp doesn't show anything because the file
> > > index.page is missing.
> >
> > I fixed this by committing the index.page file that will not be
> > distributed in the tarball (similarly to the legal.xml file, also present
> > in the same subdirectory).
> OK, thanks. This solves the problem for me. As a translator, I need to 
> have a look at the content in Yelp, both for the original and translated 
> versions. It would be annoying if I had to checkout all the depending 
> Git modules for a documentation and place the appropriate files/folders 
> into the right locations manually.

The approach I usually use for plugin sets like this is to have a
.page.stub file for every page I plug into in the main document.
Then I run yelp with --editor-mode, and it picks those up.

You can have normal .page files that aren't in HELP_FILES, but I
personally find that really confusing. It makes it harder to keep
track of actual omissions in HELP_FILES, and just begs for someone
to come along and "fix" it incorrectly.

At any rate, I don't think DL should require an index.page file.
This is a valid use-case that yelp.m4 was explicitly designed to
support.

--
Shaun