Yes, it has been discussed a bit, e.g. in bug 165963.

For now, you just need to add a single tmpl/dummy.sgml to cvs, and everything
works OK. (It is working for me, at least.) You can just ignore all the tmpl/*
files.

*** Bug 357628 has been marked as a duplicate of this bug. ***

Created attachment 93379 [details]
template free build

Does this look good. If so I will add a parameter to gtkdocize to select this variant.

Looking at Gwyddion's gtk-doc.mk, I would be considerably more radical.  I mean, this is something people -- people following modern conventions in writing the documentation -- will willfully and explicitly switch to.  Shouldn't we try harder to get rid of all the legacy stuff?

tmpl has to be cleaned in distclean since it is not distributed now.

Unlike the final HTML, XML is (a) cheap to rebuild (b) useless when you don't have gtk-doc installed/enabled.

Consequently, there's no need to package it.  Make you software greener by not distributing waste to developing countries.  Why would someone perform only the last XML -> HTML build step?  So, stop distributing it and clean it on distclean.

Get rid of types.  Just get rid of them.  AFAIK there is no known case of hand-written types file being actually useful for anything.   Technically this means, implicitly add --rebuild-types, don't distribute types file, clean it on distclean.

In fact, if the --master-dir patch is going to be accepted (in one form or another), I would prefer if we finally got rid of the

@-chmod -R u+w $(srcdir)

crap and built in builddir, not in srcdir.

So, it's a reasonable start, but no, it does not look good ;-)

Regarding --master-dir/VPATH I fogrot to add that things like templates with unclear source/target role are the main causes of VPATH build issues, and possibly the source of confusion between sources and targets generally.

Without templates and types, only one problematic file remains: sections.  We cannot get rid of it as not everyone's headers make enough sense for --rebuild-sections.  Still, one such file is more manageable then a whole directory of these.

I tried to change the makefile only to clean tmpl, xml and get rid of types.  However, it breaks VPATH builds even more badly than they are now.

For me, VPATH builds are currently broken enough for not to care about breaking them more in other patches (and fix them properly separately).   Things like

SCANOBJ_FILES = 		 \
	$(DOC_MODULE).args 	 \
	$(DOC_MODULE).hierarchy  \
	$(DOC_MODULE).interfaces \
	$(DOC_MODULE).prerequisites \
	$(DOC_MODULE).signals

CLEANFILES = $(SCANOBJ_FILES) ...
...

	    cd $(srcdir) ; \
	    for i in $(SCANOBJ_FILES) ; do \
               test -f $$i || touch $$i ; \
	    done \

in the suggested (as well as in the current) makefile don't work: SCANOBJ_FILES are created in srcdir but cleaned in builddir.  All the chmods making srcdir writeable are just wrong.

So, should I can attach a makefile that addresses the points above but does not try to do with anything else, i.e. is even more broken for VPATH builds?  Or what do you suggest?  These issues are distinct, but connected implementation-wise.

Regarding cleaning the tmpl dir. In the *new* gstkdoc.make I would not clean the tmpl dir. If one switches to the new one, he/she could also remove that dir (and ask developers to do the same).

Regarding the types file. I don't think we're redy to get rid of it. E.g. in gstreamer we have gstreamer.type.in that has:
gst_implements_interface_get_type
@GST_INDEX_DOC_TYPES@gst_index_factory_get_type
@GST_INDEX_DOC_TYPES@gst_index_get_type
gst_registry_get_type

where @GST_INDEX_DOC_TYPES@ evaluates to % if that subsystem is not build. This is only a partial solution (the page for the file would still be build as a non-gobject and be included :/ ).
Additionally the types file also contains the get_type functions for enum types. I'll post some more thoughts on the list.

(In reply to comment #7)
> Regarding cleaning the tmpl dir. In the *new* gstkdoc.make I would not clean
> the tmpl dir. If one switches to the new one, he/she could also remove that dir
> (and ask developers to do the same).

OK.

> Regarding the types file. I don't think we're redy to get rid of it. E.g. in
> gstreamer we have gstreamer.type.in that has:
> gst_implements_interface_get_type
> @GST_INDEX_DOC_TYPES@gst_index_factory_get_type
> @GST_INDEX_DOC_TYPES@gst_index_get_type
> gst_registry_get_type
> 
> where @GST_INDEX_DOC_TYPES@ evaluates to % if that subsystem is not build. This
> is only a partial solution (the page for the file would still be build as a
> non-gobject and be included :/ ).

Is the goal to support builds of incomplete documentation, or to figure out how to build the complete documentation even if some optional parts are mutually exclusive (e.g. interfaces to things existing only on Solaris and to things existing only on Win32)?

IMO it is not unreasonable to always build the complete documentation, the question is how to get something good enough for inspection from parts that cannot be built [properly].

> Additionally the types file also contains the get_type functions for enum
> types. I'll post some more thoughts on the list.

Non-object types are excluded by the C code gtkdoc-scangobj generates.  What exactly is the problem with enum types?  If you want to exclude them, it already works this way.  If you want to extend scangobj to generate descriptions of the string values and nicks, no problem either.

(In reply to comment #8)
> OK.

Not OK, I misread the makefile originally.

It does not just consider templates auxiliary cleanable files, it does not build them at all.  How is it supposed to work that you don't get

File doesn't exist: ./tmpl/foo.sgml

from ReadTemplateFile() gtkdoc-mkdb?

(In reply to comment #7)
> E.g. in gstreamer we have gstreamer.type.in that has:
> gst_implements_interface_get_type
> @GST_INDEX_DOC_TYPES@gst_index_factory_get_type
> @GST_INDEX_DOC_TYPES@gst_index_get_type
> gst_registry_get_type

One more remark.  Customizing gtk-doc.make will be always an option, making types manually edited is quite an easy thing to do (and honestly, are you going to use the stock gtk-doc.make?).

Whether the benefits of supporting this particular optional-build setup overweight the benefits of automated types generation, I won't judge.

However, the proposed makefile does not work with automatically rebuilt types, for instance after a fresh checkout you don't have foo.types file and therefore rule

scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) $(srcdir)/$(DOC_MODULE).types

immediately fails.  In addition, this condition

	if test -f $(srcdir)/$(DOC_MODULE).types; then \
	  cp $(srcdir)/$(DOC_MODULE).types $(distdir)/$(DOC_MODULE).types; \
	fi

does not differentiate between generated and human-written types file: if srcdir == builddir, the condition is always true.  Therefore, unless you make dist in a VPATH build, types are always distributed.

Even if generated types as the norm is too radical, the default gtk-doc.make should at least support it.

I've reverted the $(srcdir)/$(DOC_MODULE).types addition to the scan-build.stamp: rule. Also my conclusion was too quick. Without the tmpl-run, the docs miss atleast the gobject-property docs.

And yes keep improvments to the makefile comming. Maybe open a separate bug to discuss the changes needed to get rid of making srcdir writable.

Oh my, this is more work that I thought. ommitting the tmpl build would work for non-gobject code. It would miss all the info that gtkdoc-scangobj retrieves. gtkdoc-mktmpl integrates that into the template file. When we don't read the tmpl file we miss the typeinfo in $SymbolTypes{$symbol}.

Does it make sense to you to do -- for now -- what I was originally thinking we were doing, i.e. just making templates auxiliary, cleanable, non-distributed files (in the modern makefile)?  The original bug report can be read both ways.  The information in templates has to be stored somewhere.  While it could be stored in a considerably more compact form (or perhaps merged directly from scanner output), I don't think this is a sufficient reason for large-scale changes.

It seems to work now. I've build the gtk-doc checks and buzztard docs tmpl-free. Some more testing would be good though. I am not yet sure it it updates all those -undocumented,-unused,-undeclared files properly in this mode.

*** Bug 474385 has been marked as a duplicate of this bug. ***

Created attachment 95185 [details] [review]
proposed patch

gtk-doc.notmpl.make improvements:

1) distclean xml/ and do not distribute it
2) move removal of non-distributed files from maintainer-clean to distclean where they belong
3) handle distribution and cleaning of foo.type properly, i.e. depending on whether --rebuild-types is given in SCAN_OPTIONS
4) ditto for foo-section.txt and --rebuild-sections

Is there anything from that that should also be applied to the normal gtk-doc.make (e.g. conditionally copying .types)?

Everything except cleaning of xml/ and its exclusion from distribution.

Well, the old-style makefile is probably already too different to apply the patch to it too.  But it should be easy to copy the relevant bits there manually.

Committed and applied changes to gtk-doc.make.

Hmm, this is actually fixed. Am I missing something?