1#
2# Handle stuff related to building the manual in various ways
3#
4
5
6# Lookup the asciidoc[tor] bits
7include(find_asciidoc_bits)
8
9
10
11#
12# Setup some vars for the various steps in the process
13#
14
15# The original source.
16set(ADOC_SRC ${MANSRCDIR}/ctwm.1.adoc)
17
18# Where we build stuff.  Because we need to process the ADOC_SRC to
19# replace build paths etc, we need to dump it somewhere.  We could just
20# leave it right in the build dir root, but is cleaner.
21set(MAN_TMPDIR ${CMAKE_BINARY_DIR}/mantmp)
22
23# Where we copy the source to during rewrites, and then do the actual
24# build from.
25set(ADOC_TMPSRC ${MAN_TMPDIR}/ctwm.1.adoc)
26
27# Where the end products wind up
28set(MANPAGE ${CMAKE_BINARY_DIR}/ctwm.1)
29set(MANHTML ${CMAKE_BINARY_DIR}/ctwm.1.html)
30set(MANDBXML ${CMAKE_BINARY_DIR}/ctwm.1.xml)
31set(MANPDF   ${CMAKE_BINARY_DIR}/ctwm.1.pdf)
32
33# How we rewrite vars in the manual.  I decided not to use
34# configure_file() for this, as it opens up too many chances for
35# something to accidentally get sub'd, since we assume people will write
36# pretty freeform in the manual.
37set(MANSED_CMD sed -e \"s,@ETCDIR@,${ETCDIR},\"
38	-e \"s,@ctwm_version_str@,`head -1 ${CMAKE_SOURCE_DIR}/VERSION`,\")
39
40# Pregen'd doc file paths we might have, in case we can't build them
41# ourselves.
42set(MAN_PRESRC ${GENSRCDIR}/ctwm.1)
43set(HTML_PRESRC ${GENSRCDIR}/ctwm.1.html)
44
45
46
47
48
49# Figure what we can build
50#
51# These are both boolean "We can build this type of output" flags, and
52# enums for later code for "What method we use to build this type of
53# output".
54
55# We use the DocBook XML output for PDF (if manually requested), and
56# _can_ use it in very special cases for manpages.  So find out first if
57# we can even build it.
58set(MANUAL_BUILD_DBXML)
59if(ASCIIDOCTOR AND ASCIIDOCTOR_CAN_DBXML)
60	set(MANUAL_BUILD_DBXML asciidoctor)
61elseif(ASCIIDOC AND ASCIIDOC_CAN_DBXML)
62	set(MANUAL_BUILD_DBXML asciidoc)
63endif()
64
65# If we have asciidoctor, use it to build the HTML.  Else, we could use
66# asciidoc, but leave it disabled because it's very slow.
67set(MANUAL_BUILD_HTML)
68if(ASCIIDOCTOR AND ASCIIDOCTOR_CAN_HTML)
69	set(MANUAL_BUILD_HTML asciidoctor)
70elseif(ASCIIDOC)
71	set(MANUAL_BUILD_HTML asciidoc)
72	if(NOT ENABLE_ASCIIDOC_HTML)
73		set(NOAUTO_HTML 1)
74		message(STATUS "Not enabling HTML manual build; asciidoc is slow.")
75	endif()
76endif()
77
78# For the manpage output, asciidoctor has to be of a certain version.  If
79# it's not there or not high enough version, we fall back to asciidoc/a2x
80# (which is very slow at this too, but we need to build a manpage, so eat
81# the expense).  And it's possible to go via the DocBook XML output, but
82# it takes very odd cases to wind up there.
83set(MANUAL_BUILD_MANPAGE)
84if(ASCIIDOCTOR AND ASCIIDOCTOR_CAN_MAN)
85	set(MANUAL_BUILD_MANPAGE asciidoctor)
86elseif(A2X AND ASCIIDOC_CAN_MAN)
87	set(MANUAL_BUILD_MANPAGE a2x)
88elseif(XMLTO AND XMLTO_CAN_STUFF AND MANUAL_BUILD_DBXML)
89	# Should probably never happen in reality
90	set(MANUAL_BUILD_MANPAGE xmlto)
91endif()
92
93# PDF output is not hooked into the build process by default, but is made
94# available by an extra target.
95set(MANUAL_BUILD_PDF)
96if(DBLATEX AND DBLATEX_CAN_PDF AND MANUAL_BUILD_DBXML)
97	set(MANUAL_BUILD_PDF dblatex)
98endif()
99
100
101# Override: allow forcing use of pregen'd files.
102if(FORCE_PREGEN_FILES)
103	set(MANUAL_BUILD_HTML)
104	set(MANUAL_BUILD_MANPAGE)
105	set(MANUAL_BUILD_DBXML)
106endif()
107
108
109# If we can build stuff, prepare bits for it.  Technically unnecessary if
110# we're not building stuff, but doesn't do anything bad to define it in
111# those cases, and it's easier than listing every MANUAL_BUILD_* in the
112# conditions.
113set(SETUP_MAN_REWRITE 1)
114if(SETUP_MAN_REWRITE)
115	# Setup a temp dir under the build for our processing
116	file(MAKE_DIRECTORY ${MAN_TMPDIR})
117
118	# We hop through a temporary file to process in definitions for e.g.
119	# $ETCDIR.
120	add_custom_command(OUTPUT ${ADOC_TMPSRC}
121		DEPENDS ${ADOC_SRC} ${CMAKE_SOURCE_DIR}/VERSION
122		COMMAND ${MANSED_CMD} < ${ADOC_SRC} > ${ADOC_TMPSRC}
123		COMMENT "Processing ctwm.1.adoc -> mantmp/ctwm.1.adoc"
124	)
125
126	# We can't actually make other targets depend just on that generated
127	# source file, because cmake will try to multi-build it in parallel.
128	# To work around, we add a do-nothing custom target that depends on
129	# $ADOC_TMPSRC, that uses of it depend on.
130	#
131	# x-ref http://public.kitware.com/Bug/view.php?id=12311
132	#
133	# Note, however, that this _doesn't_ transmit the dependancy on
134	# ${ADOC_TMPDIR} through; it serves only to serialize the build so it
135	# doesn't try to happen twice at once.  So we still need to include
136	# ${ADOC_TMPSRC} in the DEPENDS for the targets building off it, or
137	# they don't notice when they go out of date.
138	add_custom_target(mk_adoc_tmpsrc DEPENDS ${ADOC_TMPSRC})
139endif(SETUP_MAN_REWRITE)
140
141
142
143
144#
145# Building the manpage variant
146#
147set(HAS_MAN 0)
148if(MANUAL_BUILD_MANPAGE)
149	# Got the tool to build it
150	message(STATUS "Building manpage with ${MANUAL_BUILD_MANPAGE}.")
151	set(HAS_MAN 1)
152
153	if(${MANUAL_BUILD_MANPAGE} STREQUAL "asciidoctor")
154		# We don't need the hoops for a2x here, since asciidoctor lets us
155		# specify the output directly.
156		asciidoctor_mk_manpage(${MANPAGE} ${ADOC_TMPSRC} DEPENDS mk_adoc_tmpsrc)
157	elseif(${MANUAL_BUILD_MANPAGE} STREQUAL "a2x")
158		# a2x has to jump through some stupid hoops
159		a2x_mk_manpage(${MANPAGE} ${ADOC_TMPSRC} DEPENDS mk_adoc_tmpsrc)
160	elseif(${MANUAL_BUILD_MANPAGE} STREQUAL "xmlto")
161		# xmlto does its own hoops too
162		xmlto_mk_manpage(${MANPAGE} ${MANDBXML})
163	else()
164		message(FATAL_ERROR "I don't know what to do with that manpage "
165			"building type!")
166	endif()
167elseif(EXISTS ${MAN_PRESRC})
168	# Can't build it ourselves, but we've got a prebuilt version.
169	message(STATUS "Can't build manpage, using prebuilt version.")
170	set(HAS_MAN 1)
171
172	# We still have to do the substitutions like above, but we're doing
173	# it on the built version now, rather than the source.
174	add_custom_command(OUTPUT ${MANPAGE}
175		DEPENDS ${MAN_PRESRC} ${CMAKE_SOURCE_DIR}/VERSION
176		COMMAND ${MANSED_CMD} < ${MAN_PRESRC} > ${MANPAGE}
177		COMMENT "Processing prebuilt manpage -> ctwm.1"
178	)
179else()
180	# Can't build it, no prebuilt.  Not quite fatal, but very bad.
181	message(WARNING "Can't build manpage, and no prebuilt version "
182		"available.  You won't get one.")
183endif(MANUAL_BUILD_MANPAGE)
184
185
186# Assuming we have it, compress manpage (conditionally).  We could add
187# more magic to allow different automatic compression, but that's
188# probably way more involved than we need to bother with.  Most systems
189# use gzip, and for the few that don't, the packagers can use
190# NOMANCOMPRESS and handle it out of band.
191if(HAS_MAN)
192	if(NOT NOMANCOMPRESS)
193		find_program(GZIP_CMD gzip)
194		add_custom_command(OUTPUT "${MANPAGE}.gz"
195			DEPENDS ${MANPAGE}
196			COMMAND ${GZIP_CMD} -nc ${MANPAGE} > ${MANPAGE}.gz
197			COMMENT "Compressing ctwm.1.gz"
198		)
199		add_custom_target(man ALL DEPENDS "${MANPAGE}.gz")
200		set(INSTMAN "${MANPAGE}.gz")
201	else()
202		add_custom_target(man ALL DEPENDS ${MANPAGE})
203		set(INSTMAN ${MANPAGE})
204	endif(NOT NOMANCOMPRESS)
205endif(HAS_MAN)
206
207
208
209
210#
211# Do the HTML manual
212#
213set(HAS_HTML 0)
214if(MANUAL_BUILD_HTML AND NOAUTO_HTML)
215	message(STATUS "Not autobuilding HTML manual with ${MANUAL_BUILD_HTML}.")
216endif()
217# Separate if() rather than an elseif() so that the above case can still
218# fall into the elseif(EXISTS ${HTML_PRESRC}) below and use the pregen'd
219# version.
220if(MANUAL_BUILD_HTML AND NOT NOAUTO_HTML)
221	# Got the tool to build it
222	message(STATUS "Building HTML manual with ${MANUAL_BUILD_HTML}.")
223	set(HAS_HTML 1)
224
225	if(${MANUAL_BUILD_HTML} STREQUAL "asciidoctor")
226		asciidoctor_mk_html(${MANHTML} ${ADOC_TMPSRC} DEPENDS mk_adoc_tmpsrc)
227	elseif(${MANUAL_BUILD_HTML} STREQUAL "asciidoc")
228		asciidoc_mk_html(${MANHTML} ${ADOC_TMPSRC} DEPENDS mk_adoc_tmpsrc)
229	else()
230		message(FATAL_ERROR "I don't know what to do with that HTML manual "
231			"building type!")
232	endif()
233elseif(EXISTS ${HTML_PRESRC})
234	# Can't build it ourselves, but we've got a prebuilt version.
235	message(STATUS "Can't build HTML manual, using prebuilt version.")
236	set(HAS_HTML 1)
237	set(NOAUTO_HTML) # Clear so ALL target get set below
238
239	# As with the manpage above, we need to do the processing on the
240	# generated version for build options.
241	add_custom_command(OUTPUT ${MANHTML}
242		DEPENDS ${HTML_PRESRC} ${CMAKE_SOURCE_DIR}/VERSION
243		COMMAND ${MANSED_CMD} < ${HTML_PRESRC} > ${MANHTML}
244		COMMENT "Processing prebuilt manual -> ctwm.1.html"
245	)
246
247else()
248	# Can't build it, no prebuilt.
249	# Left as STATUS, since this is "normal" for now.
250	message(STATUS "Can't build HTML manual, and no prebuilt version "
251		"available.")
252endif()  # Variants of building HTML manual
253
254
255# If we have (or are building) the HTML, add an easy target for it, and
256# define a var for the install process to notice.
257if(HAS_HTML)
258	if(NOAUTO_HTML)
259		add_custom_target(man-html DEPENDS ${MANHTML})
260	else()
261		add_custom_target(man-html ALL DEPENDS ${MANHTML})
262		set(INSTHTML ${MANHTML})
263	endif(NOAUTO_HTML)
264endif(HAS_HTML)
265
266
267
268
269#
270# Building DocBook XML
271#
272set(HAS_DBXML 0)
273if(MANUAL_BUILD_DBXML)
274	# Got the tool to build it
275	#message(STATUS "Building DocBook XML with ${MANUAL_BUILD_DBXML}.")
276	set(HAS_DBXML 1)
277
278	if(${MANUAL_BUILD_DBXML} STREQUAL "asciidoctor")
279		# We don't need the hoops for a2x here, since asciidoctor lets us
280		# specify the output directly.
281		asciidoctor_mk_docbook(${MANDBXML} ${ADOC_TMPSRC} DEPENDS mk_adoc_tmpsrc)
282	elseif(${MANUAL_BUILD_DBXML} STREQUAL "asciidoc")
283		# a2x has to jump through some stupid hoops
284		asciidoc_mk_docbook(${MANDBXML} ${ADOC_TMPSRC} DEPENDS mk_adoc_tmpsrc)
285	else()
286		message(FATAL_ERROR "I don't know what to do with that DocBook "
287			"building type!")
288	endif()
289endif(MANUAL_BUILD_DBXML)
290
291
292
293
294#
295# And the PDF output
296#
297set(HAS_PDF 0)
298if(MANUAL_BUILD_PDF)
299	# Got the tool to build it
300	#message(STATUS "Building PDF with ${MANUAL_BUILD_PDF}.")
301	set(HAS_PDF 1)
302
303	if(${MANUAL_BUILD_PDF} STREQUAL "dblatex")
304		dblatex_mk_pdf(${MANPDF} ${MANDBXML})
305	else()
306		message(FATAL_ERROR "I don't know what to do with that PDF "
307			"building type!")
308	endif()
309endif(MANUAL_BUILD_PDF)
310
311if(HAS_PDF)
312	add_custom_target(man-pdf DEPENDS ${MANPDF})
313endif(HAS_PDF)
314
315
316
317
318#
319# Handy target
320#
321set(MAN_TYPES)
322if(HAS_MAN)
323	list(APPEND MAN_TYPES man)
324endif()
325if(HAS_HTML)
326	list(APPEND MAN_TYPES man-html)
327endif()
328if(HAS_PDF)
329	list(APPEND MAN_TYPES man-pdf)
330endif()
331add_custom_target(man-all DEPENDS ${MAN_TYPES})
332