Re: [PATCHv2 2/4] DocBook: Add rules to auto-generate some media docbooks

[Randy Dunlap <randy.dunlap@oracle.com>]

On 02/25/10 09:33, Mauro Carvalho Chehab wrote:
> There are some files that are automatically generated by the old
> subsystem Makefile. Move those rules to kernel DocBook Makefile, in
> order to autogenerate the media cross-reference files:
> 	media-entities.tmpl
> 	media-indices.tmpl
> 	dvb/frontend.h.xml
> 	v4l/videodev2.h.xml
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
> 
> Fix makefile
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
> 
>  delete mode 100644 Documentation/DocBook/dvb/frontend.h.xml
>  delete mode 100644 Documentation/DocBook/media-entities.tmpl
>  delete mode 100644 Documentation/DocBook/media-indices.tmpl
>  delete mode 100644 Documentation/DocBook/v4l/videodev2.h.xml
> 
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index 7c590ef..36068db 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -6,6 +6,8 @@
>  # To add a new book the only step required is to add the book to the
>  # list of DOCBOOKS.
>  
> +TMPMEDIA=.tmpmedia
> +
>  DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
>  	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
>  	    writing_usb_driver.xml networking.xml \
> @@ -14,7 +16,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
>  	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
>  	    mac80211.xml debugobjects.xml sh.xml regulator.xml \
>  	    alsa-driver-api.xml writing-an-alsa-driver.xml \
> -	    tracepoint.xml media.xml
> +	    tracepoint.xml $(TMPMEDIA)/media.xml
>  
>  ###
>  # The build process is as follows (targets):
> @@ -32,10 +34,10 @@ PS_METHOD	= $(prefer-db2x)
>  
>  ###
>  # The targets that may be used.
> -PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs xmldoclinks
> +PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs mediaprep
>  
>  BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
> -xmldocs: $(BOOKS) xmldoclinks
> +xmldocs: $(BOOKS)
>  sgmldocs: xmldocs
>  
>  PS := $(patsubst %.xml, %.ps, $(BOOKS))
> @@ -47,24 +49,11 @@ pdfdocs: $(PDF)
>  HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
>  htmldocs: $(HTML)
>  	@$($(quiet)cmd_build_main_index)
> -	@$($(call build_main_index))
> -	@($(call build_images))
> +	@($(call build_main_index))
>  
>  MAN := $(patsubst %.xml, %.9, $(BOOKS))
>  mandocs: $(MAN)
>  
> -build_images = mkdir -p $(objtree)/Documentation/DocBook/media/ && \
> -	       cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(objtree)/Documentation/DocBook/media/
> -
> -xmldoclinks:
> -ifneq ($(objtree),$(srctree))
> -	for dep in dvb media-entities.tmpl media-indices.tmpl v4l; do \
> -		rm -f $(objtree)/Documentation/DocBook/$$dep \
> -		&& ln -s $(srctree)/Documentation/DocBook/$$dep $(objtree)/Documentation/DocBook/ \
> -		|| exit; \
> -	done
> -endif
> -
>  installmandocs: mandocs
>  	mkdir -p /usr/local/man/man9/
>  	install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
> @@ -100,7 +89,7 @@ endef
>  	$(call if_changed_rule,docproc)
>  
>  ###
> -#Read in all saved dependency files 
> +#Read in all saved dependency files
>  cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
>  
>  ifneq ($(cmd_files),)
> @@ -151,7 +140,7 @@ quiet_cmd_build_main_index = echo '  BUILD   $@'
>  
>  index = index.html
>  main_idx = Documentation/DocBook/$(index)
> -build_main_index = rm -rf $(main_idx) && \
> +build_main_index = rm -rf $(main_idx); \
>  		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
>  		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
>  		   cat $(HTML) >> $(main_idx)
> @@ -241,7 +230,7 @@ clean-files := $(DOCBOOKS) \
>  	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
>  	$(index)
>  
> -clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
> +clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man $(MEDIADIR)
>  
>  cleandocs:
>  	$(Q)rm -f $(call objectify, $(clean-files))
> @@ -251,3 +240,498 @@ cleandocs:
>  # information in a variable se we can use it in if_changed and friends.
>  
>  .PHONY: $(PHONY)
> +
> +
> +#
> +# Media build rules - Auto-generates media contents/indexes and *.h xml's
> +#
> +
> +SHELL=/bin/bash
> +
> +MEDIA_DIR=$(objtree)/Documentation/DocBook/$(TMPMEDIA)


1/  The top-level html documentation index file now begins with "media".
They are supposed to be in alphabetical order.
(This is minor, won't hold up the merge.)

Linux Kernel HTML Documentation
Kernel Version: 2.6.33
media

alsa-driver-api

debugobjects

device-drivers

deviceiobook

filesystems

etc.

2/  Clicking on "media" in the index list above gets a "file not found" error,
I think because TMPMEDIA=.tmpmedia and it's never copied to the correct output
directory.

Ah, there is a media/ dir under .tmpmedia and it contains index.html.
Note quite correct directory structure there.


Well, it's better, but it's not quite ready...

Yes, when I ack the patches, you can merge them thru the media tree.

-- 
~Randy