Skip to content

Commit 89a5513

Browse files
kjellahlkjellahl
committed
docs/docs/manual: Upgrade from DocBook 4.1 to DocBook 5.0
1 parent 722a82b commit 89a5513

File tree

4 files changed

+106
-88
lines changed

4 files changed

+106
-88
lines changed

‎docs/docs/manual/libsigc_manual.xml

Lines changed: 60 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,26 @@
1-
<?xml version="1.0"?>
2-
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" >
3-
<book id="index" lang="en">
4-
5-
<bookinfo>
6-
<title>libsigc++</title>
7-
<author>
8-
<firstname>Ainsley</firstname>
9-
<surname>Pereira</surname>
10-
</author>
11-
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<book xmlns="http://docbook.org/ns/docbook"
3+
xmlns:xlink="http://www.w3.org/1999/xlink"
4+
version="5.0" xml:id="index" xml:lang="en">
5+
6+
<info>
7+
<title>libsigc++</title>
8+
<author><personname>
9+
<firstname>Ainsley</firstname>
10+
<surname>Pereira</surname>
11+
</personname></author>
12+
<date>September 2002</date>
1213
<pubdate>September 2002. Updated January 2004 and March 2016 by Murray Cumming</pubdate>
14+
<abstract>
15+
<para>libsigc++ is a C++ template library implementing typesafe callbacks. This is an intro to libsigc++.</para>
16+
</abstract>
17+
</info>
1318

14-
<abstract>
15-
<para>libsigc++ is a C++ template library implementing typesafe callbacks. This is an intro to libsigc++.</para>
16-
</abstract>
17-
</bookinfo>
18-
19-
<chapter id="chapter-introduction">
20-
<title>Introduction</title>
19+
<chapter xml:id="chapter-introduction">
20+
<info><title>Introduction</title></info>
2121

22-
<sect1 id="sect-motivation">
23-
<title>Motivation</title>
22+
<section xml:id="sect-motivation">
23+
<info><title>Motivation</title></info>
2424

2525
<para>There are many situations in which it is desirable to decouple code that
2626
detects an event, and the code that deals with it. This is especially common in
@@ -69,14 +69,15 @@ register_click_handler(okbutton, clicked, somedata);
6969
<para>For the other side of the fence, libsigc++ provides <literal remap="tt">signal</literal>s, to which the
7070
client can attach <literal remap="tt">slot</literal>s. When the <literal remap="tt">signal</literal> is emitted, all the connected
7171
<literal remap="tt">slot</literal>s are called.</para>
72-
</sect1>
72+
</section>
7373
</chapter>
7474

75-
<chapter id="chapter-connecting">
76-
<title>Connecting your code to signals</title>
75+
<chapter xml:id="chapter-connecting">
76+
<info><title>Connecting your code to signals</title></info>
77+
78+
<section xml:id="sect-simple-ex">
79+
<info><title>A simple example</title></info>
7780

78-
<sect1 id="sect-simple-ex">
79-
<title>A simple example</title>
8081
<para>So to get some experience, lets look at a simple example...</para>
8182

8283
<para>Lets say you and I are writing an application which informs the user when
@@ -138,10 +139,10 @@ int main()
138139
<programlisting>./example1</programlisting>
139140
<para>(Try not to panic when the aliens land!)</para>
140141

141-
</sect1>
142+
</section>
142143

143-
<sect1 id="sect-using-mem-func">
144-
<title>Using a member function</title>
144+
<section xml:id="sect-using-mem-func">
145+
<info><title>Using a member function</title></info>
145146

146147
<para>Suppose you found a more sophisticated alien alerter class on the web,
147148
such as this:</para>
@@ -187,10 +188,10 @@ int main()
187188
With a lambda expression you would lose the automatic disconnection that the
188189
combination of <literal remap="tt">sigc::trackable</literal> and sigc::mem_fun()
189190
offers.</para>
190-
</sect1>
191+
</section>
191192

192-
<sect1 id="sect-signals-with-pars">
193-
<title>Signals with parameters</title>
193+
<section xml:id="sect-signals-with-pars">
194+
<info><title>Signals with parameters</title></info>
194195

195196
<para>Functions taking no parameters and returning void are quite useful,
196197
especially when they're members of classes that can store unlimited amounts of
@@ -253,25 +254,26 @@ int main()
253254
</programlisting>
254255

255256
<para>Easy.</para>
256-
</sect1>
257+
</section>
257258

258-
<sect1 id="sect-disconnecting">
259-
<title>Disconnecting</title>
259+
<section xml:id="sect-disconnecting">
260+
<info><title>Disconnecting</title></info>
260261

261262
<para>If you decide you no longer want your code to be called whenever a signal is
262263
emitted, you must remember the return value of <literal remap="tt">connect()</literal>, which we've been
263264
ignoring until now.</para>
264265

265266
<para><literal remap="tt">connect()</literal> returns a <literal remap="tt">sigc::connection</literal> object, which has a <literal remap="tt">disconnect()</literal> member method. This does just what you think it does.</para>
266267

267-
</sect1>
268+
</section>
268269
</chapter>
269270

270-
<chapter id="chapter-writing">
271-
<title>Writing your own signals</title>
271+
<chapter xml:id="chapter-writing">
272+
<info><title>Writing your own signals</title></info>
273+
274+
<section xml:id="sect-quick-recap">
275+
<info><title>Quick recap</title></info>
272276

273-
<sect1 id="sect-quick-recap">
274-
<title>Quick recap</title>
275277
<para>If all you want to do is use gtkmm, and connect your functionality to its
276278
signals, you can probably stop reading here.</para>
277279

@@ -316,10 +318,11 @@ void AlienDetector::run()
316318
// they landed in the carpark after all.
317319
}
318320
</programlisting>
319-
</sect1>
321+
</section>
322+
323+
<section xml:id="sect-return-values">
324+
<info><title>What about return values?</title></info>
320325

321-
<sect1 id="sect-return-values">
322-
<title>What about return values?</title>
323326
<para>If you only ever have one slot connected to a signal, or if you only care
324327
about the return value of the last registered one, it's quite straightforward:</para>
325328

@@ -329,14 +332,15 @@ int a_return_value;
329332

330333
a_return_value = somesignal.emit();
331334
</programlisting>
332-
</sect1>
335+
</section>
333336
</chapter>
334337

335-
<chapter id="chapter-advanced">
336-
<title>Advanced topics</title>
338+
<chapter xml:id="chapter-advanced">
339+
<info><title>Advanced topics</title></info>
340+
341+
<section xml:id="sect-rebinding">
342+
<info><title>Rebinding</title></info>
337343

338-
<sect1 id="sect-rebinding">
339-
<title>Rebinding</title>
340344
<para>Suppose you already have a function that you want to be called when a
341345
signal is emitted, but it takes the wrong argument types. For example, lets try
342346
to attach the <literal remap="tt">warn_people(std::string)</literal> function to the detected signal
@@ -399,10 +403,11 @@ myaliendetector.signal_detected.connect( sigc::hide&lt;std::string&gt;( sigc::pt
399403
hide the first argument of 3, for example, only the last).</para>
400404

401405
<para><literal remap="tt">sigc::hide_return</literal> effectively makes the return type void.</para>
402-
</sect1>
406+
</section>
407+
408+
<section xml:id="sect-retyping">
409+
<info><title>Retyping</title></info>
403410

404-
<sect1 id="sect-retyping">
405-
<title>Retyping</title>
406411
<para>A similar topic is retyping. Perhaps you have a signal that takes an <literal remap="tt">int</literal>, but
407412
you want to connect a function that takes a <literal remap="tt">double</literal>.</para>
408413

@@ -421,11 +426,12 @@ asignal.connect( sigc::retype( sigc::ptr_fun(&amp;dostuff) ) );
421426

422427
<para>If you only want to change the return type, you can use <literal remap="tt">sigc::retype_return()</literal>.
423428
<literal remap="tt">retype_return()</literal> needs one template argument, the new return type.</para>
424-
</sect1>
429+
</section>
425430
</chapter>
426431

427-
<chapter id="chapter-reference">
428-
<title>Reference</title>
429-
<para>See the reference documentation <ulink url="http://library.gnome.org/devel/libsigc++/unstable/">online</ulink></para>
432+
<chapter xml:id="chapter-reference">
433+
<info><title>Reference</title></info>
434+
435+
<para>See the reference documentation <link xlink:href="http://library.gnome.org/devel/libsigc++/unstable/">online</link></para>
430436
</chapter>
431437
</book>

‎docs/docs/manual/meson.build

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
11
# docs/docs/manual
22

33
# input: install_datadir, sigcxx_pcname, tutorial_custom_cmd, python3,
4-
# build_documentation, book_name, can_add_dist_script
4+
# build_documentation, book_name, can_add_dist_script, xsltproc
55
# output: can_parse_and_validate, build_pdf_by_default, can_build_pdf,
66
# install_tutorialdir
77

8-
# xsltproc is required by tutorial_custom_cmd html.
9-
xsltproc = find_program('xsltproc', required: build_documentation)
108
xmllint = find_program('xmllint', required: false)
11-
129
can_parse_and_validate = xmllint.found()
1310

1411
validate = get_option('validation') ? 'true' : 'false'
1512

1613
dblatex = find_program('dblatex', required: false)
17-
can_build_pdf = dblatex.found() or (xmllint.found() and \
18-
find_program('docbook2pdf', required: false).found())
14+
can_build_pdf = dblatex.found() or (xsltproc.found() and \
15+
find_program('fop', required: false).found())
1916
build_pdf_by_default = get_option('build-pdf')
2017

2118
# Installation directories are relative to {prefix}.
@@ -63,13 +60,13 @@ endif
6360

6461
if can_build_pdf
6562
# Create a PDF file of the DocBook.
66-
# Prefer dblatex, if both dblatex and docbook2pdf are available.
63+
# Prefer dblatex, if both dblatex and fop are available.
6764
custom_target('manual_pdf',
6865
input: sigc_manual_xml,
6966
output: sigc_manual_pdf,
7067
command: [
7168
python3, tutorial_custom_cmd,
72-
dblatex.found() ? 'dblatex' : 'docbook2pdf',
69+
dblatex.found() ? 'dblatex' : 'fop',
7370
'@INPUT@',
7471
'@OUTPUT@'
7572
],

‎meson.build

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -294,11 +294,9 @@ endif
294294
build_pdf = build_pdf_by_default and can_build_pdf
295295
explain_pdf = ''
296296
if build_pdf_by_default and not build_pdf
297-
explain_pdf = ' (requires dblatex or (xmllint and docbook2pdf))'
297+
explain_pdf = ' (requires dblatex or (xsltproc and fop))'
298298
endif
299299

300-
301-
302300
summary = [
303301
'',
304302
'------',

‎tools/tutorial-custom-cmd.py

Lines changed: 40 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@
88
import os
99
import sys
1010
import subprocess
11-
from pathlib import Path
1211
import shutil
1312

1413
subcommand = sys.argv[1]
@@ -29,7 +28,7 @@ def html():
2928
'--stringparam', 'chunker.output.indent', 'yes',
3029
'--stringparam', 'chunker.output.encoding', 'UTF-8',
3130
'--stringparam', 'toc.list.type', 'ul',
32-
'--stringparam', 'use.id.as.filename', '1',
31+
'--param', 'use.id.as.filename', '1',
3332
]
3433

3534
xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl'
@@ -56,21 +55,25 @@ def html():
5655
return result.returncode
5756

5857
def xmllint():
58+
from pathlib import Path
59+
5960
# argv[2] argv[3] argv[4]
6061
# <validate> <input_xml_file> <stamp_file_path>
6162

6263
validate = sys.argv[2]
6364
input_xml_file = sys.argv[3]
6465
stamp_file_path = sys.argv[4]
6566

67+
relax_ng_schema = 'http://docbook.org/xml/5.0/rng/docbook.rng'
68+
6669
cmd = [
6770
'xmllint',
6871
'--noout',
6972
'--noent',
7073
'--xinclude',
7174
]
7275
if validate == 'true':
73-
cmd += ['--postvalid']
76+
cmd += ['--relaxng', relax_ng_schema]
7477
cmd += [input_xml_file]
7578
result = subprocess.run(cmd)
7679
if result.returncode:
@@ -79,6 +82,9 @@ def xmllint():
7982
Path(stamp_file_path).touch(exist_ok=True)
8083
return 0
8184

85+
# dblatex and xsltproc+fop generate a PDF file.
86+
# docbook2pdf can generate PDF files from DocBook4 files, but not from DocBook5 files.
87+
# xsltproc+xmlroff (version 0.6.3) does not seem to work acceptably.
8288
def dblatex():
8389
# argv[2] argv[3]
8490
# <input_xml_file> <output_pdf_file>
@@ -89,50 +95,61 @@ def dblatex():
8995

9096
# For a list of available parameters, see http://dblatex.sourceforge.net/doc/manual/
9197
dblatex_params = [
92-
'-P', 'toc.section.depth=2',
98+
'-P', 'toc.section.depth=1',
9399
'-P', 'paper.type=a4paper',
100+
'-P', 'doc.collab.show=1',
101+
'-P', 'latex.output.revhistory=0',
94102
]
95103

96104
cmd = [
97105
'dblatex',
98106
] + dblatex_params + [
99107
'-o', output_pdf_file,
100-
'--pdf', input_xml_file,
108+
'--pdf',
109+
input_xml_file,
101110
]
102111
return subprocess.run(cmd).returncode
103112

104-
def docbook2pdf():
113+
def fop():
105114
# argv[2] argv[3]
106115
# <input_xml_file> <output_pdf_file>
107-
# Create a PDF file, using docbook2pdf.
116+
# Create a PDF file, using fop.
108117

109118
input_xml_file = sys.argv[2]
110119
output_pdf_file = sys.argv[3]
111120

112-
output_dir = os.path.dirname(output_pdf_file)
113-
if not output_dir:
114-
output_dir = '.'
115-
output_basename = os.path.basename(output_pdf_file)
116-
if output_basename.endswith('.pdf'):
117-
output_basename = output_basename[:-4]
118-
xml_file = os.path.join(output_dir, output_basename + '.xml')
121+
fo_file = os.path.splitext(output_pdf_file)[0] + '.fo'
122+
123+
# For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/fo/
124+
# For a list of available paper types, see the description of the page.width.portrait parameter.
125+
xslt_params = [
126+
'--param', 'toc.section.depth', '1',
127+
'--stringparam', 'fop1.extensions', '1',
128+
'--stringparam', 'page.orientation', 'portrait',
129+
'--stringparam', 'paper.type', 'A4',
130+
]
131+
132+
xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl'
119133

120-
# We need to produce an XML file with all of the XIncludes done.
134+
# Generate a .fo (formatting object) file.
135+
# fop can take an xslt stylesheet parameter, but it can only read local files.
136+
# xsltproc is necessary if you want to read the stylesheet from the internet.
121137
cmd = [
122-
'xmllint',
138+
'xsltproc',
139+
] + xslt_params + [
140+
'-o', fo_file,
123141
'--xinclude',
124-
'--postvalid',
125-
'--output', xml_file,
142+
xslt_stylesheet,
126143
input_xml_file,
127144
]
128145
result = subprocess.run(cmd)
129146
if result.returncode:
130147
return result.returncode
131148

132149
cmd = [
133-
'docbook2pdf',
134-
'--output', output_dir,
135-
xml_file,
150+
'fop',
151+
'-fo', fo_file,
152+
'-pdf', output_pdf_file,
136153
]
137154
return subprocess.run(cmd).returncode
138155

@@ -177,8 +194,8 @@ def dist_doc():
177194
sys.exit(xmllint())
178195
if subcommand == 'dblatex':
179196
sys.exit(dblatex())
180-
if subcommand == 'docbook2pdf':
181-
sys.exit(docbook2pdf())
197+
if subcommand == 'fop':
198+
sys.exit(fop())
182199
if subcommand == 'dist_doc':
183200
sys.exit(dist_doc())
184201
print(sys.argv[0], ': illegal subcommand,', subcommand)

0 commit comments

Comments
 (0)