DocBook: Add rules to auto-generate some media docbooks

RFC PATCH In review Mauro Carvalho Chehab 2 participants 3 messages Oct 25, 2010 – May 25, 2011

Subsystems (2)

Documentation Media (V4L/DVB)

lore

Share & tools

lore

Mauro Carvalho Chehab

author

2010-10-25 20:28 UTC #0 lore raw

RFC PATCH v3 1/1 DocBook: Add rules to auto-generate some media docbooks

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

v3: rebase it to apply over the current tree. Still need to address the issues pointed by Randy of not properly handling make O=dir

PS.: Resent, since some patchwork bug made this message disappear from
patchwork database...

Signed-off-by Mauro Carvalho Chehab <[email protected]>

 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

---
 Documentation/DocBook/Makefile            |  534 ++++++++
 Documentation/DocBook/dvb/frontend.h.xml  |  416 ------
 Documentation/DocBook/media-entities.tmpl |  401 ------
 Documentation/DocBook/media-indices.tmpl  |   89 -
 Documentation/DocBook/v4l/videodev2.h.xml | 1825 ------------------------------
 5 files changed, 515 insertions(+), 2750 deletions(-)

Documentation/DocBook/Makefile +515 ~~-19~~

@@ -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 de
 	    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 drm.xml
+	    tracepoint.xml $(TMPMEDIA)/media.xml drm.xml
 
 ###
 # The build process is as follows (targets):

@@ -32,7 +34,7 @@ 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)

@@ -45,25 +47,13 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)
 pdfdocs: $(PDF)
 
 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
-htmldocs: $(HTML) xmldoclinks
+htmldocs: $(HTML)
 	$(call build_main_index)
 	$(call build_images)
 
 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/

@@ -95,11 +85,11 @@ define rule_docproc
         ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl xmldoclinks FORCE
+%.xml: %.tmpl FORCE
 	$(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),)

@@ -148,7 +138,7 @@ quiet_cmd_db2pdf = PDF     $@
 
 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)

@@ -238,7 +228,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))

@@ -248,3 +238,509 @@ 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)
+
+V4L_SGMLS = \
+	biblio.xml \
+	common.xml \
+	compat.xml \
+	controls.xml \
+	dev-capture.xml \
+	dev-codec.xml \
+	dev-effect.xml \
+	dev-event.xml \
+	dev-osd.xml \
+	dev-output.xml \
+	dev-overlay.xml \
+	dev-radio.xml \
+	dev-raw-vbi.xml \
+	dev-rds.xml \
+	dev-sliced-vbi.xml \
+	dev-teletext.xml \
+	driver.xml \
+	libv4l.xml \
+	remote_controllers.xml \
+	lirc_device_interface.xml \
+	fdl-appendix.xml \
+	func-close.xml \
+	func-ioctl.xml \
+	func-mmap.xml \
+	func-munmap.xml \
+	func-open.xml \
+	func-poll.xml \
+	func-read.xml \
+	func-select.xml \
+	func-write.xml \
+	io.xml \
+	pixfmt-grey.xml \
+	pixfmt-nv12.xml \
+	pixfmt-nv16.xml \
+	pixfmt-packed-rgb.xml \
+	pixfmt-packed-yuv.xml \
+	pixfmt-sbggr16.xml \
+	pixfmt-sbggr8.xml \
+	pixfmt-sgbrg8.xml \
+	pixfmt-sgrbg8.xml \
+	pixfmt-srggb8.xml \
+	pixfmt-uyvy.xml \
+	pixfmt-vyuy.xml \
+	pixfmt-y10.xml \
+	pixfmt-y16.xml \
+	pixfmt-y41p.xml \
+	pixfmt-yuv410.xml \
+	pixfmt-yuv411p.xml \
+	pixfmt-yuv420.xml \
+	pixfmt-yuv422p.xml \
+	pixfmt-yuyv.xml \
+	pixfmt-yvyu.xml \
+	pixfmt-srggb10.xml \
+	pixfmt-srggb8.xml \
+	pixfmt-y10.xml \
+	pixfmt.xml \
+	vidioc-cropcap.xml \
+	vidioc-dbg-g-register.xml \
+	vidioc-dqevent.xml \
+	vidioc-encoder-cmd.xml \
+	vidioc-enum-fmt.xml \
+	vidioc-enum-frameintervals.xml \
+	vidioc-enum-framesizes.xml \
+	vidioc-enumaudio.xml \
+	vidioc-enumaudioout.xml \
+	vidioc-enuminput.xml \
+	vidioc-enumoutput.xml \
+	vidioc-enum-dv-presets.xml \
+	vidioc-g-dv-preset.xml \
+	vidioc-query-dv-preset.xml \
+	vidioc-g-dv-timings.xml \
+	vidioc-enumstd.xml \
+	vidioc-g-audio.xml \
+	vidioc-g-audioout.xml \
+	vidioc-dbg-g-chip-ident.xml \
+	vidioc-g-crop.xml \
+	vidioc-g-ctrl.xml \
+	vidioc-g-enc-index.xml \
+	vidioc-g-ext-ctrls.xml \
+	vidioc-g-fbuf.xml \
+	vidioc-g-fmt.xml \
+	vidioc-g-frequency.xml \
+	vidioc-g-input.xml \
+	vidioc-g-jpegcomp.xml \
+	vidioc-g-modulator.xml \
+	vidioc-g-output.xml \
+	vidioc-g-parm.xml \
+	vidioc-g-priority.xml \
+	vidioc-g-sliced-vbi-cap.xml \
+	vidioc-g-std.xml \
+	vidioc-g-tuner.xml \
+	vidioc-log-status.xml \
+	vidioc-overlay.xml \
+	vidioc-qbuf.xml \
+	vidioc-querybuf.xml \
+	vidioc-querycap.xml \
+	vidioc-queryctrl.xml \
+	vidioc-querystd.xml \
+	vidioc-reqbufs.xml \
+	vidioc-s-hw-freq-seek.xml \
+	vidioc-streamon.xml \
+	vidioc-subscribe-event.xml \
+	capture.c.xml \
+	keytable.c.xml \
+	v4l2grab.c.xml \
+	videodev2.h.xml \
+	v4l2.xml
+
+DVB_SGMLS = \
+	intro.xml \
+	frontend.xml \
+	dvbproperty.xml \
+	demux.xml \
+	video.xml \
+	audio.xml \
+	ca.xml \
+	net.xml \
+	kdapi.xml \
+	examples.xml \
+	frontend.h.xml \
+	dvbapi.xml
+
+MEDIA_SGMLS =   $(addprefix ./,$(V4L_SGMLS)) $(addprefix ./,$(DVB_SGMLS)) $(addprefix ./,$(MEDIA_TEMP))
+
+MEDIA_TEMP =  media-entities.tmpl \
+	      media-indices.tmpl \
+	      videodev2.h.xml \
+	      frontend.h.xml
+
+MEDIA_TEMP_OBJ := $(addprefix $(MEDIA_DIR)/,$(MEDIA_TEMP))
+
+FUNCS = \
+	close \
+	ioctl \
+	mmap \
+	munmap \
+	open \
+	poll \
+	read \
+	select \
+	write \
+
+IOCTLS = \
+	VIDIOC_CROPCAP \
+	VIDIOC_DBG_G_CHIP_IDENT \
+	VIDIOC_DBG_G_REGISTER \
+	VIDIOC_DBG_S_REGISTER \
+	VIDIOC_DQBUF \
+	VIDIOC_DQEVENT \
+	VIDIOC_ENCODER_CMD \
+	VIDIOC_ENUMAUDIO \
+	VIDIOC_ENUMAUDOUT \
+	VIDIOC_ENUMINPUT \
+	VIDIOC_ENUMOUTPUT \
+	VIDIOC_ENUMSTD \
+	VIDIOC_ENUM_DV_PRESETS \
+	VIDIOC_ENUM_FMT \
+	VIDIOC_ENUM_FRAMEINTERVALS \
+	VIDIOC_ENUM_FRAMESIZES \
+	VIDIOC_G_AUDIO \
+	VIDIOC_G_AUDOUT \
+	VIDIOC_G_CROP \
+	VIDIOC_G_CTRL \
+	VIDIOC_G_DV_PRESET \
+	VIDIOC_G_DV_TIMINGS \
+	VIDIOC_G_ENC_INDEX \
+	VIDIOC_G_EXT_CTRLS \
+	VIDIOC_G_FBUF \
+	VIDIOC_G_FMT \
+	VIDIOC_G_FREQUENCY \
+	VIDIOC_G_INPUT \
+	VIDIOC_G_JPEGCOMP \
+	VIDIOC_G_MPEGCOMP \
+	VIDIOC_G_MODULATOR \
+	VIDIOC_G_OUTPUT \
+	VIDIOC_G_PARM \
+	VIDIOC_G_PRIORITY \
+	VIDIOC_G_SLICED_VBI_CAP \
+	VIDIOC_G_STD \
+	VIDIOC_G_TUNER \
+	VIDIOC_LOG_STATUS \
+	VIDIOC_OVERLAY \
+	VIDIOC_QBUF \
+	VIDIOC_QUERYBUF \
+	VIDIOC_QUERYCAP \
+	VIDIOC_QUERYCTRL \
+	VIDIOC_QUERYMENU \
+	VIDIOC_QUERYSTD \
+	VIDIOC_QUERY_DV_PRESET \
+	VIDIOC_REQBUFS \
+	VIDIOC_STREAMOFF \
+	VIDIOC_STREAMON \
+	VIDIOC_S_AUDIO \
+	VIDIOC_S_AUDOUT \
+	VIDIOC_S_CROP \
+	VIDIOC_S_CTRL \
+	VIDIOC_S_DV_PRESET \
+	VIDIOC_S_DV_TIMINGS \
+	VIDIOC_S_EXT_CTRLS \
+	VIDIOC_S_FBUF \
+	VIDIOC_S_FMT \
+	VIDIOC_S_FREQUENCY \
+	VIDIOC_S_HW_FREQ_SEEK \
+	VIDIOC_S_INPUT \
+	VIDIOC_S_JPEGCOMP \
+	VIDIOC_S_MPEGCOMP \
+	VIDIOC_S_MODULATOR \
+	VIDIOC_S_OUTPUT \
+	VIDIOC_S_PARM \
+	VIDIOC_S_PRIORITY \
+	VIDIOC_S_STD \
+	VIDIOC_SUBSCRIBE_EVENT \
+	VIDIOC_S_TUNER \
+	VIDIOC_TRY_ENCODER_CMD \
+	VIDIOC_TRY_EXT_CTRLS \
+	VIDIOC_TRY_FMT \
+	VIDIOC-UNSUBSCRIBE-EVENT \
+
+TYPES = \
+	v4l2_std_id \
+
+ENUMS = \
+	v4l2_buf_type \
+	v4l2_colorspace \
+	v4l2_ctrl_type \
+	v4l2_exposure_auto_type \
+	v4l2_field \
+	v4l2_frmivaltypes \
+	v4l2_frmsizetypes \
+	v4l2_memory \
+	v4l2_mpeg_audio_ac3_bitrate \
+	v4l2_mpeg_audio_crc \
+	v4l2_mpeg_audio_emphasis \
+	v4l2_mpeg_audio_encoding \
+	v4l2_mpeg_audio_l1_bitrate \
+	v4l2_mpeg_audio_l2_bitrate \
+	v4l2_mpeg_audio_l3_bitrate \
+	v4l2_mpeg_audio_mode \
+	v4l2_mpeg_audio_mode_extension \
+	v4l2_mpeg_audio_sampling_freq \
+	v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type \
+	v4l2_mpeg_cx2341x_video_luma_spatial_filter_type \
+	v4l2_mpeg_cx2341x_video_median_filter_type \
+	v4l2_mpeg_cx2341x_video_spatial_filter_mode \
+	v4l2_mpeg_cx2341x_video_temporal_filter_mode \
+	v4l2_mpeg_stream_type \
+	v4l2_mpeg_stream_vbi_fmt \
+	v4l2_mpeg_video_aspect \
+	v4l2_mpeg_video_bitrate_mode \
+	v4l2_mpeg_video_encoding \
+	v4l2_power_line_frequency \
+	v4l2_priority \
+	v4l2_tuner_type \
+	v4l2_preemphasis \
+
+STRUCTS = \
+	v4l2_audio \
+	v4l2_audioout \
+	v4l2_bt_timings \
+	v4l2_buffer \
+	v4l2_capability \
+	v4l2_captureparm \
+	v4l2_clip \
+	v4l2_control \
+	v4l2_crop \
+	v4l2_cropcap \
+	v4l2_dbg_chip_ident \
+	v4l2_dbg_match \
+	v4l2_dbg_register \
+	v4l2_dv_enum_preset \
+	v4l2_dv_preset \
+	v4l2_dv_timings \
+	v4l2_event \
+	v4l2_event_vsync \
+	v4l2_enc_idx \
+	v4l2_enc_idx_entry \
+	v4l2_encoder_cmd \
+	v4l2_ext_control \
+	v4l2_ext_controls \
+	v4l2_fmtdesc \
+	v4l2_format \
+	v4l2_fract \
+	v4l2_framebuffer \
+	v4l2_frequency \
+	v4l2_frmival_stepwise \
+	v4l2_frmivalenum \
+	v4l2_frmsize_discrete \
+	v4l2_frmsize_stepwise \
+	v4l2_frmsizeenum \
+	v4l2_hw_freq_seek \
+	v4l2_input \
+	v4l2_jpegcompression \
+	v4l2_modulator \
+	v4l2_mpeg_vbi_fmt_ivtv \
+	v4l2_output \
+	v4l2_outputparm \
+	v4l2_pix_format \
+	v4l2_queryctrl \
+	v4l2_querymenu \
+	v4l2_rect \
+	v4l2_requestbuffers \
+	v4l2_sliced_vbi_cap \
+	v4l2_sliced_vbi_data \
+	v4l2_sliced_vbi_format \
+	v4l2_standard \
+	v4l2_streamparm \
+	v4l2_timecode \
+	v4l2_tuner \
+	v4l2_vbi_format \
+	v4l2_window \
+
+ERRORS = \
+	EACCES \
+	EAGAIN \
+	EBADF \
+	EBUSY \
+	EFAULT \
+	EIO \
+	EINTR \
+	EINVAL \
+	ENFILE \
+	ENOMEM \
+	ENOSPC \
+	ENOTTY \
+	ENXIO \
+	EMFILE \
+	EPERM \
+	ERANGE \
+
+ESCAPE = \
+	-e "s/&/\\&amp;/g" \
+	-e "s/</\\&lt;/g" \
+	-e "s/>/\\&gt;/g"
+
+FILENAME = \
+	-e s,"^[^\/]*/",, \
+	-e s/"\\.xml"// \
+	-e s/"\\.tmpl"// \
+	-e s/\\\./-/g \
+	-e s/"^func-"// \
+	-e s/"^pixfmt-"// \
+	-e s/"^vidioc-"//
+
+# Generate references to these structs in videodev2.h.xml.
+DOCUMENTED = \
+	-e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
+	-e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
+	-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \
+	-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
+	-e "s/\(linkend\=\"\)v4l2\-mpeg\-vbi\-ITV0/\1v4l2-mpeg-vbi-itv0-1/g"
+
+DVB_DOCUMENTED = \
+	-e "s,\(define \)\([A-Z0-9_]\+\)\(\s\+_IO\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \
+	-e "s/\(linkend\=\"\)FE_SET_PROPERTY/\1FE_GET_PROPERTY/g"
+
+
+#
+# Media targets and dependencies
+#
+
+$(obj)/$(TMPMEDIA)/media.xml: $(obj)/media.tmpl $(MEDIA_TEMP_OBJ) FORCE
+	$(call if_changed_rule,docproc)
+
+$(MEDIA_DIR)/v4l2.xml:
+	@$($(quiet)gen_xml)
+	@(mkdir -p $(MEDIA_DIR))
+	@(cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(MEDIA_DIR)/)
+	@(ln -sf $(srctree)/Documentation/DocBook/v4l/*xml $(MEDIA_DIR)/)
+	@(ln -sf $(srctree)/Documentation/DocBook/dvb/*xml $(MEDIA_DIR)/)
+
+$(MEDIA_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(					\
+	echo "<programlisting>") > $@
+	@(					\
+	expand --tabs=8 < $< |			\
+	  sed $(ESCAPE) $(DOCUMENTED) |		\
+	  sed 's/i\.e\./&ie;/') >> $@
+	@(					\
+	echo "</programlisting>") >> $@
+
+$(MEDIA_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(					\
+	echo "<programlisting>") > $@
+	@(					\
+	expand --tabs=8 < $< |			\
+	  sed $(ESCAPE) $(DVB_DOCUMENTED) |	\
+	  sed 's/i\.e\./&ie;/') >> $@
+	@(					\
+	echo "</programlisting>") >> $@
+
+$(MEDIA_DIR)/media-entities.tmpl: $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(								\
+	echo "<!-- Generated file! Do not edit. -->") >$@
+	@(								\
+	echo -e "\n<!-- Functions -->") >>$@
+	@(								\
+	for ident in $(FUNCS) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  echo "<!ENTITY func-$$entity \"<link"				\
+	    "linkend='func-$$entity'><function>$$ident()</function></link>\">" \
+	  >>$@ ;							\
+	done)
+	@(								\
+	echo -e "\n<!-- Ioctls -->") >>$@
+	@(								\
+	for ident in $(IOCTLS) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  id=`grep "<refname>$$ident" $(MEDIA_DIR)/vidioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \
+	  echo "<!ENTITY $$entity \"<link"				\
+	    "linkend='$$id'><constant>$$ident</constant></link>\">"	\
+	  >>$@ ;							\
+	done)
+	@(								\
+	echo -e "\n<!-- Types -->") >>$@
+	@(								\
+	for ident in $(TYPES) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  echo "<!ENTITY $$entity \"<link"				\
+	    "linkend='$$entity'>$$ident</link>\">" >>$@ ;		\
+	done)
+	@(								\
+	echo -e "\n<!-- Enums -->") >>$@
+	@(								\
+	for ident in $(ENUMS) ; do					\
+	  entity=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -` ; \
+	  echo "<!ENTITY $$entity \"enum&nbsp;<link"			\
+	    "linkend='$$entity'>$$ident</link>\">" >>$@ ;		\
+	done)
+	@(								\
+	echo -e "\n<!-- Structures -->") >>$@
+	@(								\
+	for ident in $(STRUCTS) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  echo "<!ENTITY $$entity \"struct&nbsp;<link"			\
+	    "linkend='$$entity'>$$ident</link>\">" >>$@ ;		\
+	done)
+	@(								\
+	echo -e "\n<!-- Error Codes -->") >>$@
+	@(								\
+	for ident in $(ERRORS) ; do					\
+	  echo "<!ENTITY $$ident \"<errorcode>$$ident</errorcode>"	\
+	    "error code\">" >>$@ ;					\
+	done)
+	@(								\
+	echo -e "\n<!-- Subsections -->") >>$@
+	@(								\
+	for file in $(MEDIA_SGMLS) ; do					\
+	  entity=`echo "$$file" | sed $(FILENAME) -e s/"^([^-]*)"/sub\1/` ; \
+	  if ! echo "$$file" |						\
+	    grep -q -E -e '^(func|vidioc|pixfmt)-' ; then		\
+	    echo "<!ENTITY sub-$$entity SYSTEM \"./$$file\">" >>$@ ;	\
+	  fi ;								\
+	done)
+	@(								\
+	echo -e "\n<!-- Function Reference -->") >>$@
+	@(								\
+	for file in $(MEDIA_SGMLS) ; do					\
+	  if echo "$$file" |						\
+	    grep -q -E -e '(func|vidioc|pixfmt)-' ; then		\
+	    entity=`echo "$$file" |sed $(FILENAME)` ;			\
+	    echo "<!ENTITY $$entity SYSTEM \"./$$file\">" >>$@ ;	\
+	  fi ;								\
+	done)
+
+# Jade can auto-generate a list-of-tables, which includes all structs,
+# but we only want data types, all types, and sorted please.
+$(MEDIA_DIR)/media-indices.tmpl: $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(								\
+	echo "<!-- Generated file! Do not edit. -->") >$@
+	@(								\
+	echo -e "\n<index><title>List of Types</title>") >>$@
+	@(								\
+	for ident in $(TYPES) ; do					\
+	  id=`echo $$ident | tr _ -` ;					\
+	  echo "<indexentry><primaryie><link"				\
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done)
+	@(								\
+	for ident in $(ENUMS) ; do					\
+	  id=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -`; \
+	  echo "<indexentry><primaryie>enum&nbsp;<link"			\
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done)
+	@(								\
+	for ident in $(STRUCTS) ; do					\
+	  id=`echo $$ident | tr _ -` ;					\
+	  echo "<indexentry><primaryie>struct&nbsp;<link"		\
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done)
+	@(								\
+	echo "</index>") >>$@

Documentation/DocBook/media-indices.tmpl deleted +0 ~~-89~~

89 lines not on this page · raw message

Documentation/DocBook/dvb/frontend.h.xml deleted +0 ~~-416~~

416 lines not on this page · raw message

Documentation/DocBook/media-entities.tmpl deleted +0 ~~-401~~

401 lines not on this page · raw message

Documentation/DocBook/v4l/videodev2.h.xml deleted +0 ~~-1825~~

1,506 lines not on this page · raw message

The rest of this diff is not shown. View the raw message.

Part of the diff is not shown here. View the raw message.

Randy Dunlap

2010-10-26 16:52 UTC #1 lore raw

On Mon, 25 Oct 2010 18:28:00 -0200 Mauro Carvalho Chehab wrote:

Hi,
A few comments, interspersed below...

Quoted 101 lines

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

v3: rebase it to apply over the current tree. Still need to address the issues pointed by Randy of not properly handling make O=dir

PS.: Resent, since some patchwork bug made this message disappear from
patchwork database...

Signed-off-by Mauro Carvalho Chehab <[email protected]>

 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

---
 Documentation/DocBook/Makefile            |  534 ++++++++
 Documentation/DocBook/dvb/frontend.h.xml  |  416 ------
 Documentation/DocBook/media-entities.tmpl |  401 ------
 Documentation/DocBook/media-indices.tmpl  |   89 -
 Documentation/DocBook/v4l/videodev2.h.xml | 1825 ------------------------------
 5 files changed, 515 insertions(+), 2750 deletions(-)

Documentation/DocBook/Makefile +7 ~~-17~~

@@ -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 de
 	    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 drm.xml
+	    tracepoint.xml $(TMPMEDIA)/media.xml drm.xml
 
 ###
 # The build process is as follows (targets):

@@ -32,7 +34,7 @@ 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)

@@ -45,25 +47,13 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)
 pdfdocs: $(PDF)
 
 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
-htmldocs: $(HTML) xmldoclinks
+htmldocs: $(HTML)
 	$(call build_main_index)
 	$(call build_images)
 
 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/

@@ -95,11 +85,11 @@ define rule_docproc
         ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl xmldoclinks FORCE
+%.xml: %.tmpl FORCE
 	$(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),)

Documentation/DocBook/Makefile quiet_cmd_db2pdf = PDF $@ · line 141

Quoted 5 lines

Documentation/DocBook/Makefile +1 -1

@@ -148,7 +138,7 @@ quiet_cmd_db2pdf = PDF     $@
 
 index = index.html
 main_idx = Documentation/DocBook/$(index)
-build_main_index = rm -rf $(main_idx) && \
+build_main_index = rm -rf $(main_idx); \

Does this fix a problem?

Documentation/DocBook/Makefile clean-files := $(DOCBOOKS) \ · line 231

Quoted 9 lines

Documentation/DocBook/Makefile +1 -1

 		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
 		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
 		   cat $(HTML) >> $(main_idx)

@@ -238,7 +228,7 @@ clean-files := $(DOCBOOKS) \
 	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
 	$(index)
 
-clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
+clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man $(MEDIADIR)

Where is MEDIADIR defined?
Oh, I see a MEDIA_DIR below.

Documentation/DocBook/Makefile cleandocs: · line 242

Quoted 9 lines

Documentation/DocBook/Makefile +2 -0

 cleandocs:
 	$(Q)rm -f $(call objectify, $(clean-files))

@@ -248,3 +238,509 @@ cleandocs:
 # information in a variable se we can use it in if_changed and friends.
 
 .PHONY: $(PHONY)
+
+

Would it be possible for media to have its own Makefile instead of merging into this one?

Quoted 141 lines

Documentation/DocBook/Makefile +141 -0

+#
+# Media build rules - Auto-generates media contents/indexes and *.h xml's
+#
+
+SHELL=/bin/bash
+
+MEDIA_DIR=$(objtree)/Documentation/DocBook/$(TMPMEDIA)
+
+V4L_SGMLS = \
+	biblio.xml \
+	common.xml \
+	compat.xml \
+	controls.xml \
+	dev-capture.xml \
+	dev-codec.xml \
+	dev-effect.xml \
+	dev-event.xml \
+	dev-osd.xml \
+	dev-output.xml \
+	dev-overlay.xml \
+	dev-radio.xml \
+	dev-raw-vbi.xml \
+	dev-rds.xml \
+	dev-sliced-vbi.xml \
+	dev-teletext.xml \
+	driver.xml \
+	libv4l.xml \
+	remote_controllers.xml \
+	lirc_device_interface.xml \
+	fdl-appendix.xml \
+	func-close.xml \
+	func-ioctl.xml \
+	func-mmap.xml \
+	func-munmap.xml \
+	func-open.xml \
+	func-poll.xml \
+	func-read.xml \
+	func-select.xml \
+	func-write.xml \
+	io.xml \
+	pixfmt-grey.xml \
+	pixfmt-nv12.xml \
+	pixfmt-nv16.xml \
+	pixfmt-packed-rgb.xml \
+	pixfmt-packed-yuv.xml \
+	pixfmt-sbggr16.xml \
+	pixfmt-sbggr8.xml \
+	pixfmt-sgbrg8.xml \
+	pixfmt-sgrbg8.xml \
+	pixfmt-srggb8.xml \
+	pixfmt-uyvy.xml \
+	pixfmt-vyuy.xml \
+	pixfmt-y10.xml \
+	pixfmt-y16.xml \
+	pixfmt-y41p.xml \
+	pixfmt-yuv410.xml \
+	pixfmt-yuv411p.xml \
+	pixfmt-yuv420.xml \
+	pixfmt-yuv422p.xml \
+	pixfmt-yuyv.xml \
+	pixfmt-yvyu.xml \
+	pixfmt-srggb10.xml \
+	pixfmt-srggb8.xml \
+	pixfmt-y10.xml \
+	pixfmt.xml \
+	vidioc-cropcap.xml \
+	vidioc-dbg-g-register.xml \
+	vidioc-dqevent.xml \
+	vidioc-encoder-cmd.xml \
+	vidioc-enum-fmt.xml \
+	vidioc-enum-frameintervals.xml \
+	vidioc-enum-framesizes.xml \
+	vidioc-enumaudio.xml \
+	vidioc-enumaudioout.xml \
+	vidioc-enuminput.xml \
+	vidioc-enumoutput.xml \
+	vidioc-enum-dv-presets.xml \
+	vidioc-g-dv-preset.xml \
+	vidioc-query-dv-preset.xml \
+	vidioc-g-dv-timings.xml \
+	vidioc-enumstd.xml \
+	vidioc-g-audio.xml \
+	vidioc-g-audioout.xml \
+	vidioc-dbg-g-chip-ident.xml \
+	vidioc-g-crop.xml \
+	vidioc-g-ctrl.xml \
+	vidioc-g-enc-index.xml \
+	vidioc-g-ext-ctrls.xml \
+	vidioc-g-fbuf.xml \
+	vidioc-g-fmt.xml \
+	vidioc-g-frequency.xml \
+	vidioc-g-input.xml \
+	vidioc-g-jpegcomp.xml \
+	vidioc-g-modulator.xml \
+	vidioc-g-output.xml \
+	vidioc-g-parm.xml \
+	vidioc-g-priority.xml \
+	vidioc-g-sliced-vbi-cap.xml \
+	vidioc-g-std.xml \
+	vidioc-g-tuner.xml \
+	vidioc-log-status.xml \
+	vidioc-overlay.xml \
+	vidioc-qbuf.xml \
+	vidioc-querybuf.xml \
+	vidioc-querycap.xml \
+	vidioc-queryctrl.xml \
+	vidioc-querystd.xml \
+	vidioc-reqbufs.xml \
+	vidioc-s-hw-freq-seek.xml \
+	vidioc-streamon.xml \
+	vidioc-subscribe-event.xml \
+	capture.c.xml \
+	keytable.c.xml \
+	v4l2grab.c.xml \
+	videodev2.h.xml \
+	v4l2.xml
+
+DVB_SGMLS = \
+	intro.xml \
+	frontend.xml \
+	dvbproperty.xml \
+	demux.xml \
+	video.xml \
+	audio.xml \
+	ca.xml \
+	net.xml \
+	kdapi.xml \
+	examples.xml \
+	frontend.h.xml \
+	dvbapi.xml
+
+MEDIA_SGMLS =   $(addprefix ./,$(V4L_SGMLS)) $(addprefix ./,$(DVB_SGMLS)) $(addprefix ./,$(MEDIA_TEMP))
+
+MEDIA_TEMP =  media-entities.tmpl \
+	      media-indices.tmpl \
+	      videodev2.h.xml \
+	      frontend.h.xml
+
+MEDIA_TEMP_OBJ := $(addprefix $(MEDIA_DIR)/,$(MEDIA_TEMP))
+
+FUNCS = \

Documentation/DocBook/Makefile cleandocs: · line 393

Quoted 10 lines

Documentation/DocBook/Makefile +10 -0

+	close \
+	ioctl \
+	mmap \
+	munmap \
+	open \
+	poll \
+	read \
+	select \
+	write \
+

so the blank line terminates the value setting, here and below?

Quoted 192 lines

Documentation/DocBook/Makefile +192 -0

+IOCTLS = \
+	VIDIOC_CROPCAP \
+	VIDIOC_DBG_G_CHIP_IDENT \
+	VIDIOC_DBG_G_REGISTER \
+	VIDIOC_DBG_S_REGISTER \
+	VIDIOC_DQBUF \
+	VIDIOC_DQEVENT \
+	VIDIOC_ENCODER_CMD \
+	VIDIOC_ENUMAUDIO \
+	VIDIOC_ENUMAUDOUT \
+	VIDIOC_ENUMINPUT \
+	VIDIOC_ENUMOUTPUT \
+	VIDIOC_ENUMSTD \
+	VIDIOC_ENUM_DV_PRESETS \
+	VIDIOC_ENUM_FMT \
+	VIDIOC_ENUM_FRAMEINTERVALS \
+	VIDIOC_ENUM_FRAMESIZES \
+	VIDIOC_G_AUDIO \
+	VIDIOC_G_AUDOUT \
+	VIDIOC_G_CROP \
+	VIDIOC_G_CTRL \
+	VIDIOC_G_DV_PRESET \
+	VIDIOC_G_DV_TIMINGS \
+	VIDIOC_G_ENC_INDEX \
+	VIDIOC_G_EXT_CTRLS \
+	VIDIOC_G_FBUF \
+	VIDIOC_G_FMT \
+	VIDIOC_G_FREQUENCY \
+	VIDIOC_G_INPUT \
+	VIDIOC_G_JPEGCOMP \
+	VIDIOC_G_MPEGCOMP \
+	VIDIOC_G_MODULATOR \
+	VIDIOC_G_OUTPUT \
+	VIDIOC_G_PARM \
+	VIDIOC_G_PRIORITY \
+	VIDIOC_G_SLICED_VBI_CAP \
+	VIDIOC_G_STD \
+	VIDIOC_G_TUNER \
+	VIDIOC_LOG_STATUS \
+	VIDIOC_OVERLAY \
+	VIDIOC_QBUF \
+	VIDIOC_QUERYBUF \
+	VIDIOC_QUERYCAP \
+	VIDIOC_QUERYCTRL \
+	VIDIOC_QUERYMENU \
+	VIDIOC_QUERYSTD \
+	VIDIOC_QUERY_DV_PRESET \
+	VIDIOC_REQBUFS \
+	VIDIOC_STREAMOFF \
+	VIDIOC_STREAMON \
+	VIDIOC_S_AUDIO \
+	VIDIOC_S_AUDOUT \
+	VIDIOC_S_CROP \
+	VIDIOC_S_CTRL \
+	VIDIOC_S_DV_PRESET \
+	VIDIOC_S_DV_TIMINGS \
+	VIDIOC_S_EXT_CTRLS \
+	VIDIOC_S_FBUF \
+	VIDIOC_S_FMT \
+	VIDIOC_S_FREQUENCY \
+	VIDIOC_S_HW_FREQ_SEEK \
+	VIDIOC_S_INPUT \
+	VIDIOC_S_JPEGCOMP \
+	VIDIOC_S_MPEGCOMP \
+	VIDIOC_S_MODULATOR \
+	VIDIOC_S_OUTPUT \
+	VIDIOC_S_PARM \
+	VIDIOC_S_PRIORITY \
+	VIDIOC_S_STD \
+	VIDIOC_SUBSCRIBE_EVENT \
+	VIDIOC_S_TUNER \
+	VIDIOC_TRY_ENCODER_CMD \
+	VIDIOC_TRY_EXT_CTRLS \
+	VIDIOC_TRY_FMT \
+	VIDIOC-UNSUBSCRIBE-EVENT \
+
+TYPES = \
+	v4l2_std_id \
+
+ENUMS = \
+	v4l2_buf_type \
+	v4l2_colorspace \
+	v4l2_ctrl_type \
+	v4l2_exposure_auto_type \
+	v4l2_field \
+	v4l2_frmivaltypes \
+	v4l2_frmsizetypes \
+	v4l2_memory \
+	v4l2_mpeg_audio_ac3_bitrate \
+	v4l2_mpeg_audio_crc \
+	v4l2_mpeg_audio_emphasis \
+	v4l2_mpeg_audio_encoding \
+	v4l2_mpeg_audio_l1_bitrate \
+	v4l2_mpeg_audio_l2_bitrate \
+	v4l2_mpeg_audio_l3_bitrate \
+	v4l2_mpeg_audio_mode \
+	v4l2_mpeg_audio_mode_extension \
+	v4l2_mpeg_audio_sampling_freq \
+	v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type \
+	v4l2_mpeg_cx2341x_video_luma_spatial_filter_type \
+	v4l2_mpeg_cx2341x_video_median_filter_type \
+	v4l2_mpeg_cx2341x_video_spatial_filter_mode \
+	v4l2_mpeg_cx2341x_video_temporal_filter_mode \
+	v4l2_mpeg_stream_type \
+	v4l2_mpeg_stream_vbi_fmt \
+	v4l2_mpeg_video_aspect \
+	v4l2_mpeg_video_bitrate_mode \
+	v4l2_mpeg_video_encoding \
+	v4l2_power_line_frequency \
+	v4l2_priority \
+	v4l2_tuner_type \
+	v4l2_preemphasis \
+
+STRUCTS = \
+	v4l2_audio \
+	v4l2_audioout \
+	v4l2_bt_timings \
+	v4l2_buffer \
+	v4l2_capability \
+	v4l2_captureparm \
+	v4l2_clip \
+	v4l2_control \
+	v4l2_crop \
+	v4l2_cropcap \
+	v4l2_dbg_chip_ident \
+	v4l2_dbg_match \
+	v4l2_dbg_register \
+	v4l2_dv_enum_preset \
+	v4l2_dv_preset \
+	v4l2_dv_timings \
+	v4l2_event \
+	v4l2_event_vsync \
+	v4l2_enc_idx \
+	v4l2_enc_idx_entry \
+	v4l2_encoder_cmd \
+	v4l2_ext_control \
+	v4l2_ext_controls \
+	v4l2_fmtdesc \
+	v4l2_format \
+	v4l2_fract \
+	v4l2_framebuffer \
+	v4l2_frequency \
+	v4l2_frmival_stepwise \
+	v4l2_frmivalenum \
+	v4l2_frmsize_discrete \
+	v4l2_frmsize_stepwise \
+	v4l2_frmsizeenum \
+	v4l2_hw_freq_seek \
+	v4l2_input \
+	v4l2_jpegcompression \
+	v4l2_modulator \
+	v4l2_mpeg_vbi_fmt_ivtv \
+	v4l2_output \
+	v4l2_outputparm \
+	v4l2_pix_format \
+	v4l2_queryctrl \
+	v4l2_querymenu \
+	v4l2_rect \
+	v4l2_requestbuffers \
+	v4l2_sliced_vbi_cap \
+	v4l2_sliced_vbi_data \
+	v4l2_sliced_vbi_format \
+	v4l2_standard \
+	v4l2_streamparm \
+	v4l2_timecode \
+	v4l2_tuner \
+	v4l2_vbi_format \
+	v4l2_window \
+
+ERRORS = \
+	EACCES \
+	EAGAIN \
+	EBADF \
+	EBUSY \
+	EFAULT \
+	EIO \
+	EINTR \
+	EINVAL \
+	ENFILE \
+	ENOMEM \
+	ENOSPC \
+	ENOTTY \
+	ENXIO \
+	EMFILE \
+	EPERM \
+	ERANGE \
+
+ESCAPE = \
+	-e "s/&/\\&amp;/g" \
+	-e "s/</\\&lt;/g" \
+	-e "s/>/\\&gt;/g"
+

Documentation/DocBook/Makefile cleandocs: · line 595

Quoted 10 lines

Documentation/DocBook/Makefile +10 -0

+FILENAME = \
+	-e s,"^[^\/]*/",, \
+	-e s/"\\.xml"// \
+	-e s/"\\.tmpl"// \
+	-e s/\\\./-/g \
+	-e s/"^func-"// \
+	-e s/"^pixfmt-"// \
+	-e s/"^vidioc-"//
+
+# Generate references to these structs in videodev2.h.xml.

[snip]

[snip deleted files]

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Mauro Carvalho Chehab

author

2011-05-25 15:21 UTC #2 lore raw

Hi Randy,

First of all, sorry for taking a long time to handle this. Documentation stuff in general get less priority than other things.

Em 26-10-2010 14:52, Randy Dunlap escreveu:

Quoted 107 lines · On Mon, 25 Oct 2010 18:28:00 -0200 Mauro Carvalho Chehab wrote:

Hi,
A few comments, interspersed below...

Quoted 102 lines

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

v3: rebase it to apply over the current tree. Still need to address the issues pointed by Randy of not properly handling make O=dir

PS.: Resent, since some patchwork bug made this message disappear from
patchwork database...

Signed-off-by Mauro Carvalho Chehab <[email protected]>

 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

---
 Documentation/DocBook/Makefile            |  534 ++++++++
 Documentation/DocBook/dvb/frontend.h.xml  |  416 ------
 Documentation/DocBook/media-entities.tmpl |  401 ------
 Documentation/DocBook/media-indices.tmpl  |   89 -
 Documentation/DocBook/v4l/videodev2.h.xml | 1825 ------------------------------
 5 files changed, 515 insertions(+), 2750 deletions(-)

Documentation/DocBook/Makefile +7 ~~-17~~

@@ -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 de
 	    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 drm.xml
+	    tracepoint.xml $(TMPMEDIA)/media.xml drm.xml
 
 ###
 # The build process is as follows (targets):

@@ -32,7 +34,7 @@ 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)

@@ -45,25 +47,13 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)
 pdfdocs: $(PDF)
 
 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
-htmldocs: $(HTML) xmldoclinks
+htmldocs: $(HTML)
 	$(call build_main_index)
 	$(call build_images)
 
 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/

@@ -95,11 +85,11 @@ define rule_docproc
         ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl xmldoclinks FORCE
+%.xml: %.tmpl FORCE
 	$(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),)

@@ -148,7 +138,7 @@ quiet_cmd_db2pdf = PDF     $@

Quoted 6 lines

Documentation/DocBook/Makefile quiet_cmd_db2pdf = PDF $@ · line 141
Quoted 4 lines
Documentation/DocBook/Makefile +1 -1
 index = index.html
 main_idx = Documentation/DocBook/$(index)
-build_main_index = rm -rf $(main_idx) && \
+build_main_index = rm -rf $(main_idx); \
Does this fix a problem?

Yes. If $(main_idx) doesn't exist, it causes a failure at the script, on some cases. It is probably better to send it as a separate patch, but I can't remember the exact situation where it causes a failure. It is there since the first version of this patch, years ago.

I agree that the better would be to send it as a separate patch, but I doubt I'll have any time soon to re-check when such case happen. I think it happens if you call "make cleandocs htmldocs".

Removing the && is safe, as the main index will be re-generated anyway, on that logic.

Quoted 7 lines

Documentation/DocBook/Makefile +0 -0

 		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
 		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
 		   cat $(HTML) >> $(main_idx)

@@ -238,7 +228,7 @@ clean-files := $(DOCBOOKS) \
 	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
 	$(index)

Quoted 5 lines

Documentation/DocBook/Makefile clean-files := $(DOCBOOKS) \ · line 231
Quoted 2 lines
Documentation/DocBook/Makefile +1 -1
-clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
+clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man $(MEDIADIR)
Where is MEDIADIR defined?
Oh, I see a MEDIA_DIR below.

Ah, yes, thanks for noticing it!

Quoted 11 lines

Documentation/DocBook/Makefile cleandocs: · line 242
Quoted 8 lines
Documentation/DocBook/Makefile +2 -0
 cleandocs:
 	$(Q)rm -f $(call objectify, $(clean-files))
@@ -248,3 +238,509 @@ cleandocs:
 # information in a variable se we can use it in if_changed and friends.
 
 .PHONY: $(PHONY)
+
+
Would it be possible for media to have its own Makefile instead of merging into this one?

Sure, but I may need to re-work on the entire logic. I won't have any time soon for doing it. Well, I could just move this into a Makefile.media and just include it at the main Makefile, but this would probably be dirty.

I just worked on a new version for this patch, fixing the MEDIADIR stuff, and backporting it to work against the current tree.

If you're ok with that, I would love to merge it upstream, as the Makefile build logic helps us to identify some troubles at the DocBook, as the reference links between the auto-generated *.h.xml files and the specs allows to easily detect when something is not properly documented.

-
Subject: [PATCHv4] DocBook: Add rules to auto-generate some media docbooks
From: Mauro Carvalho Chehab <[email protected]>

Auto-generate the videodev2.h.xml,frontend.h.xml and the indexes.

Some logic at the Makefile helps us to identify when a symbol is missing, like for example:

Error: no ID for constraint linkend: V4L2-PIX-FMT-JPGL.

Signed-off-by Mauro Carvalho Chehab <[email protected]>

Documentation/DocBook/Makefile +258 ~~-21~~

index 8436b01..619b943 100644
@@ -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 \
 	    80211.xml debugobjects.xml sh.xml regulator.xml \
 	    alsa-driver-api.xml writing-an-alsa-driver.xml \
-	    tracepoint.xml media.xml drm.xml
+	    tracepoint.xml $(TMPMEDIA)/media.xml drm.xml
 
 ###
 # The build process is as follows (targets):

@@ -32,7 +34,7 @@ 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)

@@ -45,27 +47,13 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
 pdfdocs: $(PDF)
 
 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
-htmldocs: $(HTML) xmldoclinks
+htmldocs: $(HTML)
 	$(call build_main_index)
 	$(call build_images)
 
 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/

@@ -97,11 +85,11 @@ define rule_docproc
         ) > $(dir $@).$(notdir $@).cmd
 endef
 
-%.xml: %.tmpl xmldoclinks FORCE
+%.xml: %.tmpl FORCE
 	$(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),)

@@ -150,7 +138,7 @@ quiet_cmd_db2pdf = PDF     $@
 
 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)

@@ -240,7 +228,7 @@ clean-files := $(DOCBOOKS) \
 	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
 	$(index)
 
-clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
+clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man $(MEDIA_DIR)
 
 cleandocs:
 	$(Q)rm -f $(call objectify, $(clean-files))

@@ -250,3 +238,252 @@ 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)
+
+V4L_SGMLS = \
+	$(shell ls $(srctree)/Documentation/DocBook/v4l/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)') \
+	capture.c.xml \
+	keytable.c.xml \
+	v4l2grab.c.xml
+
+DVB_SGMLS = \
+	$(shell ls $(srctree)/Documentation/DocBook/dvb/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)')
+
+MEDIA_TEMP =  media-entities.tmpl \
+	      media-indices.tmpl \
+	      videodev2.h.xml \
+	      frontend.h.xml
+
+MEDIA_SGMLS =  $(addprefix ./,$(V4L_SGMLS)) $(addprefix ./,$(DVB_SGMLS)) $(addprefix ./,$(MEDIA_TEMP))
+
+MEDIA_TEMP_OBJ := $(addprefix $(MEDIA_DIR)/,$(MEDIA_TEMP))
+
+FUNCS = \
+	close \
+	ioctl \
+	mmap \
+	munmap \
+	open \
+	poll \
+	read \
+	select \
+	write \
+
+IOCTLS = \
+	$(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/videodev2.h) \
+	$(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/media.h) \
+	$(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/v4l2-subdev.h) \
+	VIDIOC_SUBDEV_G_FRAME_INTERVAL \
+	VIDIOC_SUBDEV_S_FRAME_INTERVAL \
+	VIDIOC_SUBDEV_ENUM_MBUS_CODE \
+	VIDIOC_SUBDEV_ENUM_FRAME_SIZE \
+	VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \
+
+TYPES = \
+	$(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h)
+
+ENUMS = \
+	$(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \
+	$(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \
+	$(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h) \
+	$(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h)
+
+STRUCTS = \
+	$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \
+	$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \
+	$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h) \
+	$(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h)
+
+ERRORS = \
+	EACCES \
+	EAGAIN \
+	EBADF \
+	EBUSY \
+	EFAULT \
+	EIO \
+	EINTR \
+	EINVAL \
+	ENFILE \
+	ENOMEM \
+	ENOSPC \
+	ENOTTY \
+	ENXIO \
+	EMFILE \
+	EPERM \
+	ERANGE \
+	EPIPE \
+
+ESCAPE = \
+	-e "s/&/\\&amp;/g" \
+	-e "s/</\\&lt;/g" \
+	-e "s/>/\\&gt;/g"
+
+FILENAME = \
+	-e s,"^[^\/]*/",, \
+	-e s/"\\.xml"// \
+	-e s/"\\.tmpl"// \
+	-e s/\\\./-/g \
+	-e s/"^func-"// \
+	-e s/"^pixfmt-"// \
+	-e s/"^vidioc-"//
+
+# Generate references to these structs in videodev2.h.xml.
+DOCUMENTED = \
+	-e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
+	-e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
+	-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \
+	-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
+	-e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g"
+
+DVB_DOCUMENTED = \
+	-e "s,\(define \)\([A-Z0-9_]\+\)\(\s\+_IO\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \
+	-e "s/\(linkend\=\"\)FE_SET_PROPERTY/\1FE_GET_PROPERTY/g"
+
+
+#
+# Media targets and dependencies
+#
+
+$(obj)/$(TMPMEDIA)/media.xml: $(obj)/media.tmpl $(MEDIA_TEMP_OBJ) FORCE
+	$(call if_changed_rule,docproc)
+
+$(MEDIA_DIR)/v4l2.xml:
+	@$($(quiet)gen_xml)
+	@(mkdir -p $(MEDIA_DIR))
+	@(cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(MEDIA_DIR)/)
+	@(ln -sf $(srctree)/Documentation/DocBook/v4l/*xml $(MEDIA_DIR)/)
+	@(ln -sf $(srctree)/Documentation/DocBook/dvb/*xml $(MEDIA_DIR)/)
+
+$(MEDIA_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(					\
+	echo "<programlisting>") > $@
+	@(					\
+	expand --tabs=8 < $< |			\
+	  sed $(ESCAPE) $(DOCUMENTED) |		\
+	  sed 's/i\.e\./&ie;/') >> $@
+	@(					\
+	echo "</programlisting>") >> $@
+
+$(MEDIA_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(					\
+	echo "<programlisting>") > $@
+	@(					\
+	expand --tabs=8 < $< |			\
+	  sed $(ESCAPE) $(DVB_DOCUMENTED) |	\
+	  sed 's/i\.e\./&ie;/') >> $@
+	@(					\
+	echo "</programlisting>") >> $@
+
+$(MEDIA_DIR)/media-entities.tmpl: $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(								\
+	echo "<!-- Generated file! Do not edit. -->") >$@
+	@(								\
+	echo -e "\n<!-- Functions -->") >>$@
+	@(								\
+	for ident in $(FUNCS) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  echo "<!ENTITY func-$$entity \"<link"				\
+	    "linkend='func-$$entity'><function>$$ident()</function></link>\">" \
+	  >>$@ ;							\
+	done)
+	@(								\
+	echo -e "\n<!-- Ioctls -->") >>$@
+	@(								\
+	for ident in $(IOCTLS) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  id=`grep "<refname>$$ident" $(MEDIA_DIR)/vidioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \
+	  echo "<!ENTITY $$entity \"<link"				\
+	    "linkend='$$id'><constant>$$ident</constant></link>\">"	\
+	  >>$@ ;							\
+	done)
+	@(								\
+	echo -e "\n<!-- Types -->") >>$@
+	@(								\
+	for ident in $(TYPES) ; do					\
+	  entity=`echo $$ident | tr _ -` ;				\
+	  echo "<!ENTITY $$entity \"<link"				\
+	    "linkend='$$entity'>$$ident</link>\">" >>$@ ;		\
+	done)
+	@(								\
+	echo -e "\n<!-- Enums -->") >>$@
+	@(								\
+	for ident in $(ENUMS) ; do					\
+	  entity=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -` ; \
+	  echo "<!ENTITY $$entity \"enum&nbsp;<link"			\
+	    "linkend='$$entity'>$$ident</link>\">" >>$@ ;		\
+	done)
+	@(								\
+	echo -e "\n<!-- Structures -->") >>$@
+	@(								\
+	for ident in $(STRUCTS) ; do					\
+	  entity=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \
+	  echo "<!ENTITY $$entity \"struct&nbsp;<link"			\
+	    "linkend='$$entity'>$$ident</link>\">" >>$@ ;		\
+	done)
+	@(								\
+	echo -e "\n<!-- Error Codes -->") >>$@
+	@(								\
+	for ident in $(ERRORS) ; do					\
+	  echo "<!ENTITY $$ident \"<errorcode>$$ident</errorcode>"	\
+	    "error code\">" >>$@ ;					\
+	done)
+	@(								\
+	echo -e "\n<!-- Subsections -->") >>$@
+	@(								\
+	for file in $(MEDIA_SGMLS) ; do					\
+	  entity=`echo "$$file" | sed $(FILENAME) -e s/"^([^-]*)"/sub\1/` ; \
+	  if ! echo "$$file" |						\
+	    grep -q -E -e '^(func|vidioc|pixfmt)-' ; then		\
+	    echo "<!ENTITY sub-$$entity SYSTEM \"$$file\">" >>$@ ;	\
+	  fi ;								\
+	done)
+	@(								\
+	echo -e "\n<!-- Function Reference -->") >>$@
+	@(								\
+	for file in $(MEDIA_SGMLS) ; do					\
+	  if echo "$$file" |						\
+	    grep -q -E -e '(func|vidioc|pixfmt)-' ; then		\
+	    entity=`echo "$$file" |sed $(FILENAME)` ;			\
+	    echo "<!ENTITY $$entity SYSTEM \"$$file\">" >>$@ ;	\
+	  fi ;								\
+	done)
+
+# Jade can auto-generate a list-of-tables, which includes all structs,
+# but we only want data types, all types, and sorted please.
+$(MEDIA_DIR)/media-indices.tmpl: $(MEDIA_DIR)/v4l2.xml
+	@$($(quiet)gen_xml)
+	@(								\
+	echo "<!-- Generated file! Do not edit. -->") >$@
+	@(								\
+	echo -e "\n<index><title>List of Types</title>") >>$@
+	@(								\
+	for ident in $(TYPES) ; do					\
+	  id=`echo $$ident | tr _ -` ;					\
+	  echo "<indexentry><primaryie><link"				\
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done)
+	@(								\
+	for ident in $(ENUMS) ; do					\
+	  id=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -`; \
+	  echo "<indexentry><primaryie>enum&nbsp;<link"			\
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done)
+	@(								\
+	for ident in $(STRUCTS) ; do					\
+	  id=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \
+	  echo "<indexentry><primaryie>struct&nbsp;<link"		\
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done)
+	@(								\
+	echo "</index>") >>$@

Documentation/DocBook/dvb/frontend.h.xml deleted +0 ~~-428~~

428 lines not on this page · raw message

Documentation/DocBook/media-indices.tmpl deleted +0 ~~-89~~

89 lines not on this page · raw message

Documentation/DocBook/v4l/videodev2.h.xml deleted +0 ~~-1946~~

1,946 lines not on this page · raw message