summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/Makefile
blob: 595bdd3acb6d1d069eb8c773dd311d7603795570 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
###
# This makefile is used to generate the kernel documentation,
# primarily based on in-line comments in various source files.
# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
# to document the SRC - and how to read it.
# 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 \
	    kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.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 $(TMPMEDIA)/media.xml drm.xml

###
# The build process is as follows (targets):
#              (xmldocs) [by docproc]
# file.tmpl --> file.xml +--> file.ps   (psdocs)   [by db2ps or xmlto]
#                        +--> file.pdf  (pdfdocs)  [by db2pdf or xmlto]
#                        +--> DIR=file  (htmldocs) [by xmlto]
#                        +--> man/      (mandocs)  [by xmlto]


# for PDF and PS output you can choose between xmlto and docbook-utils tools
PDF_METHOD	= $(prefer-db2x)
PS_METHOD	= $(prefer-db2x)


###
# The targets that may be used.
PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs mediaprep

BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
xmldocs: $(BOOKS)
sgmldocs: xmldocs

PS := $(patsubst %.xml, %.ps, $(BOOKS))
psdocs: $(PS)

PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
pdfdocs: $(PDF)

HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
htmldocs: $(HTML)
	$(call build_main_index)
	$(call build_images)

MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN)

installmandocs: mandocs
	mkdir -p /usr/local/man/man9/
	install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/

###
#External programs used
KERNELDOC = $(srctree)/scripts/kernel-doc
DOCPROC   = $(objtree)/scripts/docproc

XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
XMLTOFLAGS += --skip-validation

###
# DOCPROC is used for two purposes:
# 1) To generate a dependency list for a .tmpl file
# 2) To preprocess a .tmpl file and call kernel-doc with
#     appropriate parameters.
# The following rules are used to generate the .xml documentation
# required to generate the final targets. (ps, pdf, html).
quiet_cmd_docproc = DOCPROC $@
      cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
define rule_docproc
	set -e;								\
        $(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';) 	\
        $(cmd_$(1)); 							\
        ( 								\
          echo 'cmd_$@ := $(cmd_$(1))'; 				\
          echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; 		\
        ) > $(dir $@).$(notdir $@).cmd
endef

%.xml: %.tmpl FORCE
	$(call if_changed_rule,docproc)

###
#Read in all saved dependency files
cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))

ifneq ($(cmd_files),)
  include $(cmd_files)
endif

###
# Changes in kernel-doc force a rebuild of all documentation
$(BOOKS): $(KERNELDOC)

# Tell kbuild to always build the programs
always := $(hostprogs-y)

notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
		   exit 1
db2xtemplate = db2TYPE -o $(dir $@) $<
xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<

# determine which methods are available
ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
	use-db2x = db2x
	prefer-db2x = db2x
else
	use-db2x = notfound
	prefer-db2x = $(use-xmlto)
endif
ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
	use-xmlto = xmlto
	prefer-xmlto = xmlto
else
	use-xmlto = notfound
	prefer-xmlto = $(use-db2x)
endif

# the commands, generated from the chosen template
quiet_cmd_db2ps = PS      $@
      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
%.ps : %.xml
	$(call cmd,db2ps)

quiet_cmd_db2pdf = PDF     $@
      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
%.pdf : %.xml
	$(call cmd,db2pdf)


index = index.html
main_idx = Documentation/DocBook/$(index)
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)

quiet_cmd_db2html = HTML    $@
      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@

%.html:	%.xml
	@(which xmlto > /dev/null 2>&1) || \
	 (echo "*** You need to install xmlto ***"; \
	  exit 1)
	@rm -rf $@ $(patsubst %.html,%,$@)
	$(call cmd,db2html)
	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi

quiet_cmd_db2man = MAN     $@
      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
%.9 : %.xml
	@(which xmlto > /dev/null 2>&1) || \
	 (echo "*** You need to install xmlto ***"; \
	  exit 1)
	$(Q)mkdir -p $(obj)/man
	$(call cmd,db2man)
	@touch $@

###
# Rules to generate postscripts and PNG images from .fig format files
quiet_cmd_fig2eps = FIG2EPS $@
      cmd_fig2eps = fig2dev -Leps $< $@

%.eps: %.fig
	@(which fig2dev > /dev/null 2>&1) || \
	 (echo "*** You need to install transfig ***"; \
	  exit 1)
	$(call cmd,fig2eps)

quiet_cmd_fig2png = FIG2PNG $@
      cmd_fig2png = fig2dev -Lpng $< $@

%.png: %.fig
	@(which fig2dev > /dev/null 2>&1) || \
	 (echo "*** You need to install transfig ***"; \
	  exit 1)
	$(call cmd,fig2png)

###
# Rule to convert a .c file to inline XML documentation
       gen_xml = :
 quiet_gen_xml = echo '  GEN     $@'
silent_gen_xml = :
%.xml: %.c
	@$($(quiet)gen_xml)
	@(                            \
	   echo "<programlisting>";   \
	   expand --tabs=8 < $< |     \
	   sed -e "s/&/\\&amp;/g"     \
	       -e "s/</\\&lt;/g"      \
	       -e "s/>/\\&gt;/g";     \
	   echo "</programlisting>")  > $@

###
# Help targets as used by the top-level makefile
dochelp:
	@echo  ' Linux kernel internal documentation in different formats:'
	@echo  '  htmldocs        - HTML'
	@echo  '  pdfdocs         - PDF'
	@echo  '  psdocs          - Postscript'
	@echo  '  xmldocs         - XML DocBook'
	@echo  '  mandocs         - man pages'
	@echo  '  installmandocs  - install man pages generated by mandocs'
	@echo  '  cleandocs       - clean all generated DocBook files'

###
# Temporary files left by various tools
clean-files := $(DOCBOOKS) \
	$(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
	$(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
	$(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
	$(patsubst %.xml, %.log,  $(DOCBOOKS)) \
	$(patsubst %.xml, %.out,  $(DOCBOOKS)) \
	$(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
	$(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
	$(patsubst %.xml, %.html, $(DOCBOOKS)) \
	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
	$(index)

clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man $(MEDIA_DIR)

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

# Declare the contents of the .PHONY variable as phony.  We keep that
# 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>") >>$@