Skip to content

Commit 12d6c14

Browse files
kjellahlkjellahl
committed
docs/manual: Upgrade from DocBook 4.1 to DocBook 5.0
1 parent 40d7695 commit 12d6c14

File tree

4 files changed

+109
-92
lines changed

4 files changed

+109
-92
lines changed

‎docs/manual/libsigc_manual.xml

Lines changed: 63 additions & 57 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-
12-
<pubdate>September 2002. Updated January 2004 by Murray Cumming</pubdate>
13-
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>
21-
22-
<sect1 id="sect-motivation">
23-
<title>Motivation</title>
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>
13+
<pubdate>September 2002. Updated January 2004 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>
18+
19+
<chapter xml:id="chapter-introduction">
20+
<info><title>Introduction</title></info>
21+
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
@@ -252,25 +253,26 @@ int main()
252253
</programlisting>
253254

254255
<para>Easy.</para>
255-
</sect1>
256+
</section>
256257

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

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

264265
<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>
265266

266-
</sect1>
267+
</section>
267268
</chapter>
268269

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

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

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

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

@@ -328,14 +331,15 @@ int a_return_value;
328331

329332
a_return_value = somesignal.emit();
330333
</programlisting>
331-
</sect1>
334+
</section>
332335
</chapter>
333336

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

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

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

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

@@ -420,11 +425,12 @@ asignal.connect( sigc::retype( sigc::ptr_fun(&amp;dostuff) ) );
420425

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

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

‎docs/manual/meson.build

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

33
# input: install_datadir, sigcxx_pcname, tutorial_custom_cmd, python3,
4-
# build_documentation, install_docdir, can_add_dist_script
4+
# build_documentation, install_docdir, 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}.
@@ -68,13 +65,13 @@ endif
6865

6966
if can_build_pdf
7067
# Create a PDF file of the DocBook.
71-
# Prefer dblatex, if both dblatex and docbook2pdf are available.
68+
# Prefer dblatex, if both dblatex and fop are available.
7269
custom_target('manual_pdf',
7370
input: sigc_manual_xml,
7471
output: sigc_manual_pdf,
7572
command: [
7673
python3, tutorial_custom_cmd,
77-
dblatex.found() ? 'dblatex' : 'docbook2pdf',
74+
dblatex.found() ? 'dblatex' : 'fop',
7875
'@INPUT@',
7976
'@OUTPUT@'
8077
],

‎meson.build

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,6 @@ sys.exit(os.path.isfile("@0@"))
141141
endif
142142

143143
# Check if perl is required and available.
144-
# Done now, when the doc_reference script is available.
145144
doc_perl_prop = run_command(
146145
python3, doc_reference, 'get_script_property',
147146
'', # MMDOCTOOLDIR is not used
@@ -298,11 +297,9 @@ endif
298297
build_pdf = build_pdf_by_default and can_build_pdf
299298
explain_pdf = ''
300299
if build_pdf_by_default and not build_pdf
301-
explain_pdf = ' (requires dblatex or (xmllint and docbook2pdf))'
300+
explain_pdf = ' (requires dblatex or (xsltproc and fop))'
302301
endif
303302

304-
305-
306303
summary = [
307304
'',
308305
'------',

0 commit comments

Comments
 (0)