[Debian GNUstep maintainers] First version of split gnustep-dl2 at mentors

[Yavor Doganov]

Federico Giménez Nieto wrote:
> > You have to add a @direntry to the .texi file (to have an entry in
> > the DIR file and avoid a warning by install-info's trigger), and a
> > doc-base file would be nice (Section should be
> > Programming/Objective-C).
> 
> Ok, done

I see no doc-base file here?  (OK, it's not strictly necessary,
although IMHO it would be nice to have it as this is a "must read" if
someone wants to use GDL2 -- the API reference manuals look quite
nebulous to me without reading the introduction first.)

The Info file is installed in /usr/share/doc/gnustep-dl2 instead of
/usr/share/info, so of course the reference in the DIR file won't be
generated by install-info's trigger.  TTBOMK gnustep-make does the
right thing for Info manuals; have you verified why this happens?
It's wrong.  (As a wild guess, it might be due to the .install file.)

Furthermore, your add_direntry.patch is wrong; the addition should be
something like:

@dircategory Software libraries
@direntry
* GDL2: (GDL2-Intro).	GNUstep Database Library Introduction.
@end direntry

(Or: Introduction to the GNUstep Database Library.)

See the Texinfo manual for details.  The item after the asterisk is
the name of the reference as displayed by Info browsers.  You
definitely do not want "Texinfo" displayed and being a link to the
GDL2 manual.  The name in the parens is the top-level info file that
resides in $infodir, which is is GDL2-Intro in your case, not
gdl2intro.  It is common to terminate the description with a period
and rewrap it if it is long.

About @dircategory: Our understanding (within the GNU project) has
been that the @dircategory should match the top-level categories of
the Free Software Directory.  However, many packages violate this
convention and it's almost impossible to fix them all (we've been
trying hard for years).  If upstream objects, it's OK to use "GNUstep"
there, just like Emacs manuals use "Emacs".

It is important to have a @dircategory besides @direntry, because many
users do not know the name of the reference and browse the DIR file to
find what they need.

> > API documentation.  These belong in libgnustep-dl2-dev.

> Done, i've also added a doc-base file here.

Oddly, the documentation is again added under /usr/share/doc/<package>
instead of /usr/share/GNUstep/Documentation.  Again a guess, it looks
like they ought to be installed in the right place if you tweak your
.install file.

Slightly related: Why do you introduce a spurious `build' dir and
enforce such a weird (well, at least confusing for me) format for the
.install files?  Debhelper supports multiple binary packages out of
the box, so it looks like unnecessary complication for me.  You just
make your life harder for no apparent benefit.  (I may be missing
something, though.)

> Ok, both not installed. I haven't find a good source for the manpages
> of DBModeler, eoutil and gdlgsdoc, where could i obtain it?

I can feel your pain.  The best place to look at is the source code
that generates these binaries -- it has comments at least, and you can
figure out what the tool does by reading the code.  I know that's
neither encouraging nor very pleasant, but that knwoledge would help
you anyways in the maintenance of the package.

You can also skim through GDL-related articles at wiki.gnustep.org,
although I don't think there's much.

> It seems that there has been a NMU in the meantime, the existent RC
> bug is already fixed.

Yes, you must incorporate the NMU just like you have done [*].  IMHO
it's best to wait a few days for the NMUed version to migrate to
testing before uploading yours, because it fixes a release-critical
bug.

* Feel free to fix the NMU changelog retroactively -- it has invalid
  chars (the quotation marks around NSArray).


(I hope that my comments do not discourage you -- as I mentioned
before, gnustep-dl2 is a complex package, so there's nothing wrong to
take a round or two to bring into shape.  I also do not purport to be
a wizard in Debian packaging or GNUstep knowledge, so feel free to ask
for a second opinion at any time.)