[cairo] [RFC] [PATCH cairo] doc: Drop tmpl support

Bryce Harrington bryce at bryceharrington.org
Fri Sep 14 20:01:25 UTC 2018


On Tue, Sep 04, 2018 at 09:35:40AM -0700, Bryce Harrington wrote:
> On Sat, Aug 25, 2018 at 08:11:39AM +0200, Uli Schlachter wrote:
> > Hi,
> > 
> > Well... thanks for taking a look, but sorry, I have never interacted
> > with gtkdoc in any way. A quick Google search lead me to
> > 
> > https://github.com/felixonmars/archlinux-community/commit/dff49ea7a08b6a3c8b21d6c4771051f1431fccf8
>
> > and
> > 
> > https://gitlab.gnome.org/GNOME/gtk-doc/commit/46df4354abed5724697fd5e39630c5bbc6637cc4
> > 
> > neither of which is really helpful. The best information is in
>
> > https://gitlab.gnome.org/GNOME/gtk-doc/commit/46df4354abed5724697fd5e39630c5bbc6637cc4#2cab36722f4ba2911d461a424bcb995df066860f_264_264
> > 
> > which claims... I don't know, that nothing should actually break?
>
> > You write below that this "probably regresses" something. Is there any
> > indiciation of this? The link above says "If you have never changed file
> > in tmpl by hand, please remove the directory", which I interpret as
> > "nothing should actually change, right?
> 
> Yeah I've only interacted with gtkdoc as part of the release process,
> never really dug into it.  But the code in the Makefile looks
> like it builds indexes and stuff.  I also noted the comments that
> nothing should break, guess I'm just skeptical; maybe it'd be easiest to
> land the patch and just see what breaks on the website (guessing it'll
> be pretty obvious), but I'll check those links out (thanks) and dig a
> bit more.  I don't want to expend a huge amount of time on it but maybe
> if it does regress, there's a simple fix.

Yeah, the links are simply removing the functionality, essentially the
same as what I've done.  I think I'll go ahead with the plan of landing
this for now, and getting another snapshot release out, and then keep an
eye out for regressions.

I don't know how much time is worth expending on this; if we want to
move to meson I suspect much of this will need to be scrapped and redone
anyway.  But if anyone does have time and interest to find if there are
cleaner solutions, it'd be appreciated.

Bryce

> > Cheers & sorry,
> > Uli
> > 
> > On 24.08.2018 19:17, Bryce Harrington wrote:
> > > Fix distcheck by dropping use of the now-obsolete gtkdoc-mktmpl.
> > > 
> > > In preparation for the upcoming 1.16 release, I've made a few changes to
> > > get distcheck to pass.  I also updated it to run on Ubuntu 18.04, but
> > > found that on newer distros distcheck won't run due to missing
> > > gtkdoc-mktmpl, which has been deprecated upstream for some time.  The
> > > patch below disables everything that references it, and enables
> > > distcheck to finish successfully.
> > > 
> > > Unfortunately, this probably regresses portions of our document
> > > generation, and thus will need some reimplementation work.  Anyone got
> > > time to investigate a better solution for this?
> > > 
> > > ---
> > >  build/Makefile.am.gtk-doc | 25 ++++---------------------
> > >  doc/public/Makefile.am    |  3 ---
> > >  2 files changed, 4 insertions(+), 24 deletions(-)
> > > 
> > > diff --git a/build/Makefile.am.gtk-doc b/build/Makefile.am.gtk-doc
> > > index d3fb686a7..56aa4957d 100644
> > > --- a/build/Makefile.am.gtk-doc
> > > +++ b/build/Makefile.am.gtk-doc
> > > @@ -42,8 +42,8 @@ EXTRA_DIST += 				\
> > >  	$(DOC_MODULE)-sections.txt	\
> > >  	$(DOC_MODULE)-overrides.txt
> > >  
> > > -DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
> > > -	   $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp
> > > +DOC_STAMPS=scan-build.stamp sgml-build.stamp html-build.stamp \
> > > +	   $(srcdir)/sgml.stamp $(srcdir)/html.stamp
> > >  
> > >  SCANOBJ_FILES = 		 \
> > >  	$(DOC_MODULE).args 	 \
> > > @@ -88,26 +88,11 @@ scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) $(EXTRA_HFILES)
> > >  $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp
> > >  	@true
> > >  
> > > -#### templates ####
> > > -
> > > -tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt
> > > -	@echo 'gtk-doc: Rebuilding template files'
> > > -	@-chmod -R u+w $(srcdir)
> > 
> > Urgh. I'm glad this has to go. O.o
> > 
> > > -	cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS)
> > > -	touch tmpl-build.stamp
> > > -
> > > -tmpl.stamp: tmpl-build.stamp
> > > -	@true
> > > -
> > > -tmpl/*.sgml:
> > > -	@true
> > > -
> > > -
> > >  #### xml ####
> > >  
> > >  # gtkdoc-mkdb is broken and requires a --root-dir=$(srcdir) option
> > >  # The _srcdir diversion is fragile but works for make check; make distcheck
> > > -sgml-build.stamp: tmpl.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files)
> > > +sgml-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(expand_content_files)
> > >  	@echo 'gtk-doc: Building XML'
> > >  	@-chmod -R u+w $(srcdir)
> > >  	_srcdir="`pwd`/$(DOC_SOURCE_DIR)"; \
> > > @@ -127,7 +112,7 @@ html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files)
> > >  	cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
> > >  	test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html )
> > >  	@echo 'gtk-doc: Fixing cross-references'
> > > -	cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
> > > +	cd $(srcdir) && gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS)
> > >  	touch html-build.stamp
> > >  
> > >  ##############
> > > @@ -176,10 +161,8 @@ dist-check-gtkdoc:
> > >  endif
> > >  
> > >  dist-hook: dist-check-gtkdoc dist-hook-local
> > > -	mkdir $(distdir)/tmpl
> > >  	mkdir $(distdir)/xml
> > >  	mkdir $(distdir)/html
> > > -	-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
> > >  	-cp $(srcdir)/xml/*.xml $(distdir)/xml
> > >  	cp $(srcdir)/html/* $(distdir)/html
> > >  	-cp $(srcdir)/$(DOC_MODULE).types $(distdir)/
> > > diff --git a/doc/public/Makefile.am b/doc/public/Makefile.am
> > > index 11f9e7b72..33bccabb7 100644
> > > --- a/doc/public/Makefile.am
> > > +++ b/doc/public/Makefile.am
> > > @@ -30,9 +30,6 @@ IGNORE_HFILES= \
> > >  # Extra options to supply to gtkdoc-mkdb
> > >  MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=cairo
> > >  
> > > -# Extra options to supply to gtkdoc-mktmpl
> > > -MKTMPL_OPTIONS=
> > > -
> > >  # Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
> > >  content_files =	\
> > >  	language-bindings.xml \
> > > 
> > 
> > 
> > -- 
> > “Cold. Cold. Cold. Cold. Cold. Cold. Cold. Cold. Cold. Cold.” – Anna
> -- 
> cairo mailing list
> cairo at cairographics.org
> https://lists.cairographics.org/mailman/listinfo/cairo


More information about the cairo mailing list