[GenABEL-dev] [Genabel-commits] r730 - in pkg/ProbABEL: . doc

Fri May 27 15:36:31 CEST 2011

Dear all,

On Wed, 2011-05-25 at 20:55 +0200, Yurii Aulchenko wrote:
> I understand this is another step in the direction 'no generated files
> on SVN'? Great!
Well, partly. Indeed as you say there should only be source in SVN.
However, for the PDF of ProbABEL I'm a bit in limbo. Should the
distributed packages contain the PDF? I think they should since not
everyone wants/has LaTeX installed. Up until this change the package
only contained the TeX source, not the PDF. So having the PDF in SVN was
the only way to ensure that it would be incorporated in the package.

With this change I wanted to fix/implement two things: 
- A makefile for the LaTeX docs so they are easy to generate (and thus
to distribute)
- Move towards a Makefile in each directory, instead of one top-level
Makefile. This greatly simplifies Makefile maintenance (e.g. less
$(DOCDIR)-like variables) and makes it easier to relocate files and
dirs. Also, have a Makefile in each directory is the way that autotools
(autoconf and automake, used for the ./configure;make;make install steps
of many projects) works. At the moment I'm trying my hand at these
tools, and, hopefully, I'll be able to implement ProbABEL along these
lines. 

This and your next point bring me to a question:
Should I be more verbose in my SVN log messages? Explaining in the
changes in more detail? What's your opinion (see also the next
paragraph)?

> 
> I see that you did not modify the version and changes.log. 
What is our policy on this? My idea was to only write major
changes/additions and bug fixes in that file. I guess the question is:
Which changes are important enough to add to this list? 
Furthermore, I don't think this change is big enough to warrant a
version bump, especially since it has no user impact. It's one of
(hopefully many more) changes before a new release. 

> Not a big
> deal I think - surely we do not want "perfectionism" stopping us from
> doing important staff (your changes = important; versioning =
> perfectionism), 
It is still good you pointed it out. Now we can have a discussion and
set some guidelines on this.

> but probably reflects the fact we are still struggling
> with the idea of the tag... 
I don't think so. 

> For the latest release of GenABEL I just
> made sure the SVN version of release is mentioned in Changes.log.
Excellent, this way I can add tags in the coming days. I haven't
received much feedback on it, but I propose to implement the tags soon. 

> Re-iterating on this - do we need 'tags' at all if we just keep an
> accurate record of what 'public' releases correspond to in SVN
> notation?
I think so. 
- It saves time in case we want to branch for e.g. a bugfix release
without having the latest development code integrated.
- It provides a quick and clean overview. In case anyone wants an older
version because we broke something for example, we could simply use the
tags dir. 

I guess this implementation of tags a simple copies of directories is an
SVN quirk. In bzr tags are more like log messages instead of full
copies. I guess git is similar. In both these distributed VCS's
branching is completely central to the development model, whereas SVN is
more about having a central development point. Having a tag as a 'label'
instead of a full copy seems more logical in such a model.

>  If we keep it, we can also generate changes.log at the
> release time, by looking at the commit comments. 
This is IMHO the way to go. Changes.log should be generated at release
time. In level of detail it is located between the SVN logs and the
highlighted changes as mentioned on website and forum (release notes). 

> Makes life easier for
> a committer, more difficult for release builder, but that is probably
> quite fine.
I fully agree.

Thanks for the feedback,

Lennart

> 
> Best wishes,
> Yurii
> 
> On 5/23/11, noreply at r-forge.wu-wien.ac.at <noreply at r-forge.wu-wien.ac.at> wrote:
> > Author: lckarssen
> > Date: 2011-05-23 17:25:55 +0200 (Mon, 23 May 2011)
> > New Revision: 730
> >
> > Added:
> >    pkg/ProbABEL/doc/Makefile
> > Modified:
> >    pkg/ProbABEL/Makefile
> > Log:
> > Added Makefile for the LaTeX documentation of ProbABEL and use this from the
> > main ProbABEL Makefile.
> >
> >
> >
> > Modified: pkg/ProbABEL/Makefile
> > ===================================================================
> > --- pkg/ProbABEL/Makefile	2011-05-21 12:16:39 UTC (rev 729)
> > +++ pkg/ProbABEL/Makefile	2011-05-23 15:25:55 UTC (rev 730)
> > @@ -15,7 +15,7 @@
> >  CPP = g++
> >  CFLAGS = -I $(SRCDIR)/include -O2
> >
> > -all: $(EXECUTABLES)
> > +all: $(EXECUTABLES) doc
> >  	cp $(SRCDIR)/extIDS.pl $(BINDIR)/.
> >  	cp $(SRCDIR)/prepare_data.R $(BINDIR)/.
> >  	cp $(SRCDIR)/probabel.pl $(BINDIR)/probabel.pl_example
> > @@ -30,12 +30,15 @@
> >  $(COXREG): $(COXSRC) $(REGFILES)
> >  	$(CPP) $(CFLAGS) -DCOXPH $(COXSRC) $(SRCDIR)/main.cpp
> > $(SRCDIR)/fvlib/*.cpp -o $(COXREG)
> >
> > +doc:
> > +	$(MAKE) -C $(DOCDIR)/
> > +
> >  clean: clean_doc
> >  	rm -f $(BINDIR)/* $(SRCDIR)/*~ $(SRCDIR)/*.o *.zip *.tar.gz
> > examples/*.out.txt examples/*out
> > +	$(MAKE) clean -C $(DOCDIR)/
> >
> >  clean_doc:
> > -	rm -f $(DOCDIR)/*~ $(DOCDIR)/*.log $(DOCDIR)/*.idx $(DOCDIR)/*.out
> > $(DOCDIR)/*.toc $(DOCDIR)/*.aux
> > -	rm -rf $(DOCDIR)/auto
> > +	$(MAKE) clean_doc -C $(DOCDIR)/
> >
> >  linux_distrib: clean
> >  	cd .. ; tar -czvf ProbABEL_$(VERSION).tar.gz ProbABEL
> > @@ -45,4 +48,4 @@
> >
> >  distrib: linux_distrib clean win_distrib clean
> >
> > -.PHONY:	distrib linux_distrib win_distrib clean clean_doc
> > +.PHONY:	distrib linux_distrib win_distrib clean clean_doc doc
> >
> > Added: pkg/ProbABEL/doc/Makefile
> > ===================================================================
> > --- pkg/ProbABEL/doc/Makefile	                        (rev 0)
> > +++ pkg/ProbABEL/doc/Makefile	2011-05-23 15:25:55 UTC (rev 730)
> > @@ -0,0 +1,45 @@
> > +MANNAME = ProbABEL_manual
> > +MANTEXSRC = $(MANNAME).tex
> > +MANAUX = $(patsubst %.tex, %.aux, $(MANTEXSRC))
> > +MANPDF =  $(patsubst %.tex, %.pdf, $(MANTEXSRC))
> > +
> > +.PHONY:	clean clean_doc
> > +
> > +$(MANPDF): $(MANTEXSRC) $(MANAUX)
> > +	@echo === Making final PDF ===
> > +	pdflatex $(MANTEXSRC)
> > +	@while ( grep "Rerun to " 			\
> > +		$(MANNAME).log > /dev/null ); do		\
> > +		echo '** Re-running LaTeX **';		\
> > +		pdflatex $(MANTEXSRC);		\
> > +	done
> > +	pdflatex $(MANTEXSRC)
> > +
> > +
> > +# A target needed to keep track of the nr. of LaTeX runs
> > +.btmp:
> > +
> > +
> > +clean_doc:
> > +	rm -f *~ *.log *.idx *.out *.toc *.aux
> > +	rm -rf auto
> > +
> > +clean: clean_doc
> > +	rm -f $(MANPDF)
> > +	rm -f .btmp
> > +
> > +%.aux:	%.tex $(MANSRC)
> > +	@echo === Making $< file ===
> > +	pdflatex $(MANTEXSRC)
> > +# Look for citations. Make sure grep never returns an error code.
> > +	@grep "^\\\\citation" $(MANAUX) > .btmp.new || true
> > +# If the citations are not changed, don't do anything. Otherwise replace
> > +# the .btmp file to make sure Bibtex will be run.
> > +	@if ( diff .btmp.new .btmp  > /dev/null ); then \
> > +		rm .btmp.new; \
> > +	else \
> > +		mv .btmp.new .btmp; \
> > +	fi
> > +
> > +# $(DOCS): $()
> > +# 	cd $(DOCDIR); pdflatex $(DOCSRC)
> >
> > _______________________________________________
> > Genabel-commits mailing list
> > Genabel-commits at lists.r-forge.r-project.org
> > https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/genabel-commits
> >
> 

-- 
-----------------------------------------------
L.C. Karssen
Erasmus MC
Department of Epidemiology
Room Ee 2224

Postbus 2040
3000 CA Rotterdam
The Netherlands

phone: +31-10-7044217
fax: +31-10-7044657
e-mail: l.karssen at erasmusmc.nl
GPG key ID: 0E1D39E3
-----------------------------------------------
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://lists.r-forge.r-project.org/pipermail/genabel-devel/attachments/20110527/2e7cee40/attachment.pgp>