From 89a5513e1169730ae13d826026b5ce8e86b917f8 Mon Sep 17 00:00:00 2001 From: Kjell Ahlstedt Date: Sun, 19 Sep 2021 15:54:27 +0200 Subject: docs/docs/manual: Upgrade from DocBook 4.1 to DocBook 5.0 --- docs/docs/manual/libsigc_manual.xml | 114 +++++++++++++++++++----------------- docs/docs/manual/meson.build | 13 ++-- meson.build | 4 +- tools/tutorial-custom-cmd.py | 63 ++++++++++++-------- 4 files changed, 106 insertions(+), 88 deletions(-) diff --git a/docs/docs/manual/libsigc_manual.xml b/docs/docs/manual/libsigc_manual.xml index f78b8f7..2fed5ae 100644 --- a/docs/docs/manual/libsigc_manual.xml +++ b/docs/docs/manual/libsigc_manual.xml @@ -1,26 +1,26 @@ - - - - - - libsigc++ - - Ainsley - Pereira - - + + + + + libsigc++ + + Ainsley + Pereira + + September 2002 September 2002. Updated January 2004 and March 2016 by Murray Cumming + + libsigc++ is a C++ template library implementing typesafe callbacks. This is an intro to libsigc++. + + - - libsigc++ is a C++ template library implementing typesafe callbacks. This is an intro to libsigc++. - - - - -Introduction + +Introduction - -Motivation +
+Motivation There are many situations in which it is desirable to decouple code that 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); For the other side of the fence, libsigc++ provides signals, to which the client can attach slots. When the signal is emitted, all the connected slots are called. - +
 - -Connecting your code to signals + +Connecting your code to signals + +
+A simple example - -A simple example So to get some experience, lets look at a simple example... Lets say you and I are writing an application which informs the user when @@ -138,10 +139,10 @@ int main() ./example1 (Try not to panic when the aliens land!) - +
- -Using a member function +
+Using a member function Suppose you found a more sophisticated alien alerter class on the web, such as this: @@ -187,10 +188,10 @@ int main() With a lambda expression you would lose the automatic disconnection that the combination of sigc::trackable and sigc::mem_fun() offers. - +
- -Signals with parameters +
+Signals with parameters Functions taking no parameters and returning void are quite useful, especially when they're members of classes that can store unlimited amounts of @@ -253,10 +254,10 @@ int main() Easy. - +
- -Disconnecting +
+Disconnecting If you decide you no longer want your code to be called whenever a signal is emitted, you must remember the return value of connect(), which we've been @@ -264,14 +265,15 @@ int main() connect() returns a sigc::connection object, which has a disconnect() member method. This does just what you think it does. - +
 - -Writing your own signals + +Writing your own signals + +
+Quick recap - -Quick recap If all you want to do is use gtkmm, and connect your functionality to its signals, you can probably stop reading here. @@ -316,10 +318,11 @@ void AlienDetector::run() // they landed in the carpark after all. } - +
+ +
+What about return values? - -What about return values? If you only ever have one slot connected to a signal, or if you only care about the return value of the last registered one, it's quite straightforward: @@ -329,14 +332,15 @@ int a_return_value; a_return_value = somesignal.emit(); - +
 - -Advanced topics + +Advanced topics + +
+Rebinding - -Rebinding Suppose you already have a function that you want to be called when a signal is emitted, but it takes the wrong argument types. For example, lets try to attach the warn_people(std::string) function to the detected signal @@ -399,10 +403,11 @@ myaliendetector.signal_detected.connect( sigc::hide<std::string>( sigc::pt hide the first argument of 3, for example, only the last). sigc::hide_return effectively makes the return type void. - +
+ +
+Retyping - -Retyping A similar topic is retyping. Perhaps you have a signal that takes an int, but you want to connect a function that takes a double. @@ -421,11 +426,12 @@ asignal.connect( sigc::retype( sigc::ptr_fun(&dostuff) ) ); If you only want to change the return type, you can use sigc::retype_return(). retype_return() needs one template argument, the new return type. - +
 - -Reference - See the reference documentation online + +Reference + + See the reference documentation online diff --git a/docs/docs/manual/meson.build b/docs/docs/manual/meson.build index 59e67e4..e3e9531 100644 --- a/docs/docs/manual/meson.build +++ b/docs/docs/manual/meson.build @@ -1,21 +1,18 @@ # docs/docs/manual # input: install_datadir, sigcxx_pcname, tutorial_custom_cmd, python3, -# build_documentation, book_name, can_add_dist_script +# build_documentation, book_name, can_add_dist_script, xsltproc # output: can_parse_and_validate, build_pdf_by_default, can_build_pdf, # install_tutorialdir -# xsltproc is required by tutorial_custom_cmd html. -xsltproc = find_program('xsltproc', required: build_documentation) xmllint = find_program('xmllint', required: false) - can_parse_and_validate = xmllint.found() validate = get_option('validation') ? 'true' : 'false' dblatex = find_program('dblatex', required: false) -can_build_pdf = dblatex.found() or (xmllint.found() and \ - find_program('docbook2pdf', required: false).found()) +can_build_pdf = dblatex.found() or (xsltproc.found() and \ + find_program('fop', required: false).found()) build_pdf_by_default = get_option('build-pdf') # Installation directories are relative to {prefix}. @@ -63,13 +60,13 @@ endif if can_build_pdf # Create a PDF file of the DocBook. - # Prefer dblatex, if both dblatex and docbook2pdf are available. + # Prefer dblatex, if both dblatex and fop are available. custom_target('manual_pdf', input: sigc_manual_xml, output: sigc_manual_pdf, command: [ python3, tutorial_custom_cmd, - dblatex.found() ? 'dblatex' : 'docbook2pdf', + dblatex.found() ? 'dblatex' : 'fop', '@INPUT@', '@OUTPUT@' ], diff --git a/meson.build b/meson.build index 343ccd2..cf93d48 100644 --- a/meson.build +++ b/meson.build @@ -294,11 +294,9 @@ endif build_pdf = build_pdf_by_default and can_build_pdf explain_pdf = '' if build_pdf_by_default and not build_pdf - explain_pdf = ' (requires dblatex or (xmllint and docbook2pdf))' + explain_pdf = ' (requires dblatex or (xsltproc and fop))' endif - - summary = [ '', '------', diff --git a/tools/tutorial-custom-cmd.py b/tools/tutorial-custom-cmd.py index f0a8a18..50b6a5b 100755 --- a/tools/tutorial-custom-cmd.py +++ b/tools/tutorial-custom-cmd.py @@ -8,7 +8,6 @@ import os import sys import subprocess -from pathlib import Path import shutil subcommand = sys.argv[1] @@ -29,7 +28,7 @@ def html(): '--stringparam', 'chunker.output.indent', 'yes', '--stringparam', 'chunker.output.encoding', 'UTF-8', '--stringparam', 'toc.list.type', 'ul', - '--stringparam', 'use.id.as.filename', '1', + '--param', 'use.id.as.filename', '1', ] xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl' @@ -56,6 +55,8 @@ def html(): return result.returncode def xmllint(): + from pathlib import Path + # argv[2] argv[3] argv[4] # @@ -63,6 +64,8 @@ def xmllint(): input_xml_file = sys.argv[3] stamp_file_path = sys.argv[4] + relax_ng_schema = 'http://docbook.org/xml/5.0/rng/docbook.rng' + cmd = [ 'xmllint', '--noout', @@ -70,7 +73,7 @@ def xmllint(): '--xinclude', ] if validate == 'true': - cmd += ['--postvalid'] + cmd += ['--relaxng', relax_ng_schema] cmd += [input_xml_file] result = subprocess.run(cmd) if result.returncode: @@ -79,6 +82,9 @@ def xmllint(): Path(stamp_file_path).touch(exist_ok=True) return 0 +# dblatex and xsltproc+fop generate a PDF file. +# docbook2pdf can generate PDF files from DocBook4 files, but not from DocBook5 files. +# xsltproc+xmlroff (version 0.6.3) does not seem to work acceptably. def dblatex(): # argv[2] argv[3] # @@ -89,40 +95,51 @@ def dblatex(): # For a list of available parameters, see http://dblatex.sourceforge.net/doc/manual/ dblatex_params = [ - '-P', 'toc.section.depth=2', + '-P', 'toc.section.depth=1', '-P', 'paper.type=a4paper', + '-P', 'doc.collab.show=1', + '-P', 'latex.output.revhistory=0', ] cmd = [ 'dblatex', ] + dblatex_params + [ '-o', output_pdf_file, - '--pdf', input_xml_file, + '--pdf', + input_xml_file, ] return subprocess.run(cmd).returncode -def docbook2pdf(): +def fop(): # argv[2] argv[3] # - # Create a PDF file, using docbook2pdf. + # Create a PDF file, using fop. input_xml_file = sys.argv[2] output_pdf_file = sys.argv[3] - output_dir = os.path.dirname(output_pdf_file) - if not output_dir: - output_dir = '.' - output_basename = os.path.basename(output_pdf_file) - if output_basename.endswith('.pdf'): - output_basename = output_basename[:-4] - xml_file = os.path.join(output_dir, output_basename + '.xml') + fo_file = os.path.splitext(output_pdf_file)[0] + '.fo' + + # For a list of available parameters, see http://docbook.sourceforge.net/release/xsl/current/doc/fo/ + # For a list of available paper types, see the description of the page.width.portrait parameter. + xslt_params = [ + '--param', 'toc.section.depth', '1', + '--stringparam', 'fop1.extensions', '1', + '--stringparam', 'page.orientation', 'portrait', + '--stringparam', 'paper.type', 'A4', + ] + + xslt_stylesheet = 'http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl' - # We need to produce an XML file with all of the XIncludes done. + # Generate a .fo (formatting object) file. + # fop can take an xslt stylesheet parameter, but it can only read local files. + # xsltproc is necessary if you want to read the stylesheet from the internet. cmd = [ - 'xmllint', + 'xsltproc', + ] + xslt_params + [ + '-o', fo_file, '--xinclude', - '--postvalid', - '--output', xml_file, + xslt_stylesheet, input_xml_file, ] result = subprocess.run(cmd) @@ -130,9 +147,9 @@ def docbook2pdf(): return result.returncode cmd = [ - 'docbook2pdf', - '--output', output_dir, - xml_file, + 'fop', + '-fo', fo_file, + '-pdf', output_pdf_file, ] return subprocess.run(cmd).returncode @@ -177,8 +194,8 @@ if subcommand == 'xmllint': sys.exit(xmllint()) if subcommand == 'dblatex': sys.exit(dblatex()) -if subcommand == 'docbook2pdf': - sys.exit(docbook2pdf()) +if subcommand == 'fop': + sys.exit(fop()) if subcommand == 'dist_doc': sys.exit(dist_doc()) print(sys.argv[0], ': illegal subcommand,', subcommand) -- cgit v1.2.1