refdb-devel

[Refdb-devel] refdb-elisp

[David N. <dav...@sw...>]

Hi Markus,

I just made a first pass at packaging refdb-elisp as a Debian package 
and have some feedback:


1.  Makefile document directory

I had to alter Makefile.am: change
    docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
to
    docdir = $(datadir)/doc/$(PACKAGE)

If you do not do this the documentation is split between 
/usr/share/doc/refdb-elisp and /usr/share/doc/refdb-elisp-1.0.  Further, 
the debian (dwww) document registration script gets confused.


2.  Install directory

AM_PATH_LISPDIR gives the install directory /usr/share/emacs/site-lisp 
which is where the *.el and resulting *.elc files are installed.  
Unfortunately, the buildpackage emacsen install scripts expect these 
files to be installed in /usr/share/emacs/site-lisp/${PACKAGE}.

I used the --with-lispdir configure option to force the install into 
that subdirectory.


3.  Compile error

The following error occurs at compile time:
--------------------------------------------------------------------------------
While compiling refdb-getnote-by-field-on-region in file 
/usr/share/emacs21/site-lisp/refdb-elisp/refdb-mode.el:
  ** Malformed let binding: `(concat refdb-regexp-query-string (value 
(buffer-substring (mark) (point))) refdb-regexp-query-string)'
--------------------------------------------------------------------------------


4.  Persistence of /usr/local

There is the usual Debian trouble with /usr/local and /usr.  Although I 
configured with 'prefix=/usr' I get the following warnings twice during 
emacs package install:
--------------------------------------------------------------------------------
Warning: Lisp directory `/usr/local/share/emacs/21.4/site-lisp' does not 
exist.
Warning: Lisp directory `/usr/local/share/emacs/site-lisp' does not exist.
--------------------------------------------------------------------------------


5.  Inappropriate hard-coded values in refdb-mode

95:   ;;    load path (e.g. /usr/local/share/emacs/site-lisp), or add
to:   ;;    load path (e.g. /usr/share/emacs/site-lisp), or add

877:  (defcustom refdb-rtf-view-program 
"/usr/local/OpenOffice.org1.1.4/program/swriter"
to:   (defcustom refdb-rtf-view-program "/usr/bin/oowriter"

5125: (let* ((globalconfig-localpath (format "/usr/local/etc/refdb/%s" 
globalconfig-file))
to:   (let* ((globalconfig-localpath (format "/etc/refdb/%s" 
globalconfig-file))

5205: (refdbdrc-localpath "/usr/local/etc/refdb/refdbdrc")
to:   (refdbdrc-localpath "/etc/refdb/refdbdrc")

5446: (let* ((refdbdrc-localpath "/usr/local/etc/refdb/refdbdrc")
to:   (let* ((refdbdrc-localpath "/etc/refdb/refdbdrc")

5618: (refdbdrc-localpath "/usr/local/etc/refdb/refdbdrc")
to:   (refdbdrc-localpath "/etc/refdb/refdbdrc")


6.  ?? Failure

After installation of the package I was unable to load either mode.  
This could easily be due to my _complete_ ignorance of emacs.


I'll send you the package off-list.  Please try it on your Debian system 
and let me know if it works.

Regards,
David.

[Refdb-devel] refdb-elisp

[Markus H. <mar...@mh...>]

Hi David,

David Nebauer writes:
 > 1.  Makefile document directory
 > 
 > I had to alter Makefile.am: change
 >     docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
 > to
 >     docdir = $(datadir)/doc/$(PACKAGE)
 > 
 > If you do not do this the documentation is split between 
 > /usr/share/doc/refdb-elisp and /usr/share/doc/refdb-elisp-1.0.  Further, 
 > the debian (dwww) document registration script gets confused.
 > 

Why is it "split"? What does end up in /usr/share/doc/refdb-elisp? I
thought this install directory is safe to use as we use the same in
libdbi and in RefDB.

 > 3.  Compile error
 > 
 > The following error occurs at compile time:
 > --------------------------------------------------------------------------------
 > While compiling refdb-getnote-by-field-on-region in file 
 > /usr/share/emacs21/site-lisp/refdb-elisp/refdb-mode.el:
 >   ** Malformed let binding: `(concat refdb-regexp-query-string (value 
 > (buffer-substring (mark) (point))) refdb-regexp-query-string)'
 > --------------------------------------------------------------------------------

Thanks for catching this. I didn't notice this between all those
harmless warnings.

 > 5.  Inappropriate hard-coded values in refdb-mode
 > 
 > 95:   ;;    load path (e.g. /usr/local/share/emacs/site-lisp), or add
 > to:   ;;    load path (e.g. /usr/share/emacs/site-lisp), or add
 > 
 > 877:  (defcustom refdb-rtf-view-program 
 > "/usr/local/OpenOffice.org1.1.4/program/swriter"
 > to:   (defcustom refdb-rtf-view-program "/usr/bin/oowriter"
 > 
 > 5125: (let* ((globalconfig-localpath (format "/usr/local/etc/refdb/%s" 
 > globalconfig-file))
 > to:   (let* ((globalconfig-localpath (format "/etc/refdb/%s" 
 > globalconfig-file))
 > 
 > 5205: (refdbdrc-localpath "/usr/local/etc/refdb/refdbdrc")
 > to:   (refdbdrc-localpath "/etc/refdb/refdbdrc")
 > 
 > 5446: (let* ((refdbdrc-localpath "/usr/local/etc/refdb/refdbdrc")
 > to:   (let* ((refdbdrc-localpath "/etc/refdb/refdbdrc")
 > 
 > 5618: (refdbdrc-localpath "/usr/local/etc/refdb/refdbdrc")
 > to:   (refdbdrc-localpath "/etc/refdb/refdbdrc")
 > 

Yeah, I was a bit lazy at this point to get refdb-mode done in time. I
think it's best to let configure check for the appropriate paths and
apps (e.g. I can check for either swriter, oowriter, abiword, or kword
as a rtf viewer, and use whichever is found first) and let the
Makefile preconfigure refdb-configure.el from an .in file.

 > 
 > 6.  ?? Failure
 > 
 > After installation of the package I was unable to load either mode.  
 > This could easily be due to my _complete_ ignorance of emacs.
 > 

Did you try to handle refdb-configure.el automatically? This needs to
be inserted into your site-lisp.el file, or into ~/.emacs. I believe
Debian has a site-lisp.d directory where apps can dump these startup
code fragments. Without the code in refdb-configure.el emacs does not
load the modes.
 > 
 > I'll send you the package off-list.  Please try it on your Debian system 
 > and let me know if it works.
 > 

I'll do this weekend. And thanks a lot for touching Emacs in the first
place.

regards,
Markus

-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de

[Refdb-devel] refdb-elisp

[Markus H. <mar...@mh...>]

Markus Hoenicka writes:
 > Did you try to handle refdb-configure.el automatically? This needs to
 > be inserted into your site-lisp.el file, or into ~/.emacs. I believe
 > Debian has a site-lisp.d directory where apps can dump these startup
 > code fragments. Without the code in refdb-configure.el emacs does not
 > load the modes.
 >  > 

Just checked. It's actually /etc/emacs/site-start.d. This directory
contains the code fragments in files whose names start with two
digits, e.g. 50refdb-mode-config.el. That is your package would have
to install refdb-mode-config.el as
/etc/emacs/site-start.d/50refdb-mode-config.el.


regards,
Markus

-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de

Re: [Refdb-devel] refdb-elisp

[David N. <dav...@sw...>]

Hi Markus,

> > If you do not do this the documentation is split between 
> > /usr/share/doc/refdb-elisp and /usr/share/doc/refdb-elisp-1.0.  Further, 
> > the debian (dwww) document registration script gets confused.
> > 
>
>Why is it "split"? What does end up in /usr/share/doc/refdb-elisp? I
>thought this install directory is safe to use as we use the same in
>libdbi and in RefDB.
>

 From memory, the pdf and html manual files ended up in 
refdb-elisp-1.0.  Other doc files such as changelog.Debian.gz, NEWS.gz, 
changelog.gz, README and copyright ended up in refdb-elisp.  It looks 
silly and, as I mentioned, appeared to confuse the Debian document 
registration script.

> > 6.  ?? Failure
> > 
> > After installation of the package I was unable to load either mode.  
> > This could easily be due to my _complete_ ignorance of emacs.
> > 
>
>Did you try to handle refdb-configure.el automatically? This needs to
>be inserted into your site-lisp.el file, or into ~/.emacs. I believe
>Debian has a site-lisp.d directory where apps can dump these startup
>code fragments. Without the code in refdb-configure.el emacs does not
>load the modes.
>

I presume you meant 'refdb-mode-config.el'?  Turns out the emacsen build 
scripts expect to find that file in the /debian subdirectory and called 
'emacsen-startup'.  The build process then installs the startup file in 
/etc/emacs/site-start.d as '50<PACKAGE>', in this case '50refdb-elisp'.

After doing this the refdb and ris modes work correctly in emacs.  The 
debian package now appears to be usable.  I'll send it to you off list.

I'll now automate the build process.  Unless and until you incorporate 
the changes to refdb-mode.el and the makefile, the build process will 
include a fair bit of search-and-replacing.  If you want to take over as 
maintainer of the refdb-elisp debian package I can email you the 
relevant files.  The debian build process would then be as simple as 
running the build script.  If I recall correctly the 'dpkg-dev' package 
includes all the tools needed by the build script.

Finally, there is one other problem with the current autotools distribution:


7.  No ChangeLog file

Debian policy requires a 'ChangeLog' file that tracks changes to the 
original sources -- not to be confused with the 'changelog' file in the 
/debian subdirectory which tracks packaging-related changes.  The dummy 
ChangeLog file I've added simply contains the following:
--------------------------------------------------------------------------
2005-11-15  Markus Hoenicka <mho...@us...>

<TAB>* Initial autotools packaging

--------------------------------------------------------------------------

>And thanks a lot for touching Emacs in the first place.
>

I'll shower afterwards ;-) .

Regards,
David.

Re: [Refdb-devel] refdb-elisp

[Markus H. <mar...@mh...>]

Hi,

David Nebauer writes:
 >  From memory, the pdf and html manual files ended up in 
 > refdb-elisp-1.0.  Other doc files such as changelog.Debian.gz, NEWS.gz, 
 > changelog.gz, README and copyright ended up in refdb-elisp.  It looks 
 > silly and, as I mentioned, appeared to confuse the Debian document 
 > registration script.
 > 

Ah, I see. Something Debian-specific.

 > I presume you meant 'refdb-mode-config.el'?

Yes. Sorry about that.

 > Turns out the emacsen build 
 > scripts expect to find that file in the /debian subdirectory and called 
 > 'emacsen-startup'.  The build process then installs the startup file in 
 > /etc/emacs/site-start.d as '50<PACKAGE>', in this case '50refdb-elisp'.
 > 

I suspected there is some automatism for this. I don't know whether it
makes things more complicated, but I've changed Makefile.am to install
refdb-mode-config.el as a configuration file in sysconfdir (usually
/etc or /usr/local/etc). This is probably the most logical place as it
now contains the locations of the viewing programs. If the Debian
policy allows this, you could simply create a symlink in
/etc/emacs/site-start.d pointing to that file.

 > After doing this the refdb and ris modes work correctly in emacs.  The 
 > debian package now appears to be usable.  I'll send it to you off list.
 > 

Thanks, I'll try it here as well.

 > I'll now automate the build process.  Unless and until you incorporate 
 > the changes to refdb-mode.el and the makefile, the build process will 
 > include a fair bit of search-and-replacing.  If you want to take over as 
 > maintainer of the refdb-elisp debian package I can email you the 
 > relevant files.  The debian build process would then be as simple as 
 > running the build script.  If I recall correctly the 'dpkg-dev' package 
 > includes all the tools needed by the build script.
 > 

If that is all it takes, I should be able to handle this. I'll let you
know.

 > 7.  No ChangeLog file
 > 

I'll create it using cvs2cl from now on.

 > 
 > >And thanks a lot for touching Emacs in the first place.
 > >
 > 
 > I'll shower afterwards ;-) .
 > 

Did showering help?

regards,
Markus

-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de

Re: [Refdb-devel] refdb-elisp

[David N. <dav...@sw...>]

Hi Markus,

>I suspected there is some automatism for this. I don't know whether it
>makes things more complicated, but I've changed Makefile.am to install
>refdb-mode-config.el as a configuration file in sysconfdir (usually
>/etc or /usr/local/etc). This is probably the most logical place as it
>now contains the locations of the viewing programs. If the Debian
>policy allows this, you could simply create a symlink in
>/etc/emacs/site-start.d pointing to that file.
>
>  
>

Not sure about the policy, but I did it anyway.  With the new package 
you will see it initially installs the startup file as a regular file.  
In post-processing this file is deleted and re-created as a symlink to 
/etc/refdb-mode-manual.el.

The package is now built from cvs source rather than the downloadable 
archive.  The main difference this causes is in the html manual.  Rather 
than the single page html file included in the archive, the html help 
files built from cvs are modular.  This makes for a rather messy 
document directory (/usr/share/doc/refdb-elisp) as the html files are 
mixed in with the AUTHOR, NEWS, changelog, pdf help and other document 
files.  It would be nicer if the html files were collected in their own 
subdirectory but it's not a major problem, especially since the html 
help index file and help pdf file are directly linked from the Debian 
documentation system (e.g. dwww).

I'll send the updated deb off list.

Regards,
David.

Re: [Refdb-devel] refdb-elisp

[David N. <dav...@sw...>]

Hi Markus,

> > 5.  Inappropriate hard-coded values in refdb-mode
> > 
>
>Yeah, I was a bit lazy at this point to get refdb-mode done in time. I
>think it's best to let configure check for the appropriate paths and
>apps (e.g. I can check for either swriter, oowriter, abiword, or kword
>as a rtf viewer, and use whichever is found first) and let the
>Makefile preconfigure refdb-configure.el from an .in file.
>


Don't forget Ted <http://www.nllgg.nl/Ted/> for those who want to edit 
RTF without the bloat of a full-fledged office suite.

Regards,
David.

Re: [Refdb-devel] refdb-elisp

[Markus H. <mar...@mh...>]

David Nebauer writes:
 > Don't forget Ted <http://www.nllgg.nl/Ted/> for those who want to edit 
 > RTF without the bloat of a full-fledged office suite.
 > 

Thanks for the hint. I've had a look at Ted years ago but it slipped
my mind.

regards,
Markus

-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de

Re: [Refdb-devel] refdb-elisp

[David N. <dav...@sw...>]

Hi Markus,

Two points:

1.  Manual xml source file missing from cvs

The cvs repository for elisp doesn't contain refdb-mode-manual.xml.  
When building from the cvs download, 'make' complains it has no rule for 
refdb-mode-manual.xml.


2.  Paper size of PDF manual

This one is nitpicky.  The docbook stylesheets default to US letter 
size.  Can I suggest you add '--stringparam paper.type A4' to the 
Makefile xsltproc command for the refdb-mode-manual.pdf target to force 
production of an A4 pdf file.

Regards,
David.

Re: [Refdb-devel] refdb-elisp

[Markus H. <mar...@mh...>]

Hi,

David Nebauer writes:
 > 1.  Manual xml source file missing from cvs
 > 

My fault. I've checked in that file.

 > 
 > 2.  Paper size of PDF manual
 > 
 > This one is nitpicky.  The docbook stylesheets default to US letter 
 > size.  Can I suggest you add '--stringparam paper.type A4' to the 
 > Makefile xsltproc command for the refdb-mode-manual.pdf target to force 
 > production of an A4 pdf file.
 > 

I really don't know what to use here. I absolutely agree that A4 is
preferable over the weird formats used in the US. However, it is
possible to print a letter-sized document on both letter and A4 paper,
but if you try to print an A4-formatted document on letter paper, the
printouts often lack the page numbers. So if I switched to A4, I'd
have to fix the page margins too. I'll see what I can do.

regards,
Markus

-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de