[Libguestfs] [PATCH v6 3/3] gobject: Add outline guestfs-gobject(3) manual page.
Richard W.M. Jones
rjones at redhat.com
Fri Jul 7 11:47:37 UTC 2017
Since we removed gtk doc, we might as well replace it with a
manual page explaining the basics of how to run gjs.
---
.gitignore | 2 ++
docs/guestfs-recipes.pod | 1 +
erlang/examples/guestfs-erlang.pod | 1 +
gobject/Makefile.am | 19 +++++++++++
gobject/guestfs-gobject.pod | 64 ++++++++++++++++++++++++++++++++++++++
golang/examples/guestfs-golang.pod | 1 +
java/examples/guestfs-java.pod | 1 +
lib/guestfs.pod | 5 ++-
lua/examples/guestfs-lua.pod | 1 +
ocaml/examples/guestfs-ocaml.pod | 1 +
perl/examples/guestfs-perl.pod | 1 +
python/examples/guestfs-python.pod | 1 +
ruby/examples/guestfs-ruby.pod | 1 +
13 files changed, 98 insertions(+), 1 deletion(-)
diff --git a/.gitignore b/.gitignore
index 7ccc928bb..774043501 100644
--- a/.gitignore
+++ b/.gitignore
@@ -283,6 +283,8 @@ Makefile.in
/gobject/bindtests.js
/gobject/Guestfs-1.0.gir
/gobject/Guestfs-1.0.typelib
+/gobject/guestfs-gobject.3
+/gobject/stamp-guestfs-gobject.pod
/golang/bindtests.go
/golang/examples/guestfs-golang.3
/golang/examples/stamp-guestfs-golang.pod
diff --git a/docs/guestfs-recipes.pod b/docs/guestfs-recipes.pod
index 7d772b8f2..11eb96ad7 100644
--- a/docs/guestfs-recipes.pod
+++ b/docs/guestfs-recipes.pod
@@ -722,6 +722,7 @@ L<guestfs(3)>,
L<guestfish(1)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
diff --git a/erlang/examples/guestfs-erlang.pod b/erlang/examples/guestfs-erlang.pod
index 89cbda15b..2f03b8281 100644
--- a/erlang/examples/guestfs-erlang.pod
+++ b/erlang/examples/guestfs-erlang.pod
@@ -96,6 +96,7 @@ C<Arg> is the name of the unknown argument.
L<guestfs(3)>,
L<guestfs-examples(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
diff --git a/gobject/Makefile.am b/gobject/Makefile.am
index 677d7a3d2..ddedd5b51 100644
--- a/gobject/Makefile.am
+++ b/gobject/Makefile.am
@@ -31,6 +31,7 @@ EXTRA_DIST = \
TODO.txt \
.gitignore \
bindtests-retvalues.js \
+ guestfs-gobject.pod \
tests-misc.js \
run-tests \
run-tests-retvalues \
@@ -88,6 +89,8 @@ gir_DATA = $(INTROSPECTION_GIRS)
typelibdir = $(libdir)/girepository-1.0
typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib)
+# Tests.
+
TESTS = \
run-tests \
run-tests-retvalues
@@ -103,3 +106,19 @@ $(TESTS): $(typelib_DATA)
CLEANFILES += $(gir_DATA) $(typelib_DATA)
endif HAVE_INTROSPECTION
+
+# Documentation.
+
+man_MANS = guestfs-gobject.3
+noinst_DATA = $(top_builddir)/website/guestfs-gobject.3.html
+
+guestfs-gobject.3 $(top_builddir)/website/guestfs-gobject.3.html: stamp-guestfs-gobject.pod
+
+stamp-guestfs-gobject.pod: guestfs-gobject.pod
+ $(PODWRAPPER) \
+ --section 3 \
+ --man guestfs-gobject.3 \
+ --html $(top_builddir)/website/guestfs-gobject.3.html \
+ --license examples \
+ $<
+ touch $@
diff --git a/gobject/guestfs-gobject.pod b/gobject/guestfs-gobject.pod
new file mode 100644
index 000000000..c0c6839fb
--- /dev/null
+++ b/gobject/guestfs-gobject.pod
@@ -0,0 +1,64 @@
+=head1 NAME
+
+guestfs-gobject - How to use libguestfs with the GObject bindings
+
+=head1 SYNOPSIS
+
+From Javascript using gjs:
+
+ const Guestfs = imports.gi.Guestfs;
+ var g = new Guestfs.Session();
+ g.add_drive('disk.img', null);
+ g.launch();
+ g.close();
+
+=head1 DESCRIPTION
+
+This manual page documents how to call libguestfs using GObject
+bindings, especially from Javascript.
+
+Note that the GObject bindings have problems handling 64 bit values.
+You should not use the GObject bindings if there are native bindings
+for your language. For example, to use libguestfs from Python you are
+strongly advised to use the Python native bindings instead (see
+L<guestfs-python(3)>).
+
+This page just documents the differences from the C API and gives some
+examples. If you are not familiar with using libguestfs, you also
+need to read L<guestfs(3)>.
+
+=head1 JAVASCRIPT
+
+Using gjs, you can write a C<.js> file containing:
+
+ const Guestfs = imports.gi.Guestfs;
+ var g = new Guestfs.Session();
+ g.add_drive('disk.img', null);
+ g.launch();
+ g.close();
+
+and then run it using:
+
+ gjs program.js
+
+=head1 SEE ALSO
+
+L<guestfs(3)>,
+L<guestfs-examples(3)>,
+L<guestfs-erlang(3)>,
+L<guestfs-golang(3)>,
+L<guestfs-java(3)>,
+L<guestfs-lua(3)>,
+L<guestfs-perl(3)>,
+L<guestfs-python(3)>,
+L<guestfs-recipes(1)>,
+L<guestfs-ruby(3)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones (C<rjones at redhat dot com>)
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012-2017 Red Hat Inc.
diff --git a/golang/examples/guestfs-golang.pod b/golang/examples/guestfs-golang.pod
index c2de45ece..7b9c80ab4 100644
--- a/golang/examples/guestfs-golang.pod
+++ b/golang/examples/guestfs-golang.pod
@@ -78,6 +78,7 @@ UUIDs are not returned in structures.
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
L<guestfs-ocaml(3)>,
diff --git a/java/examples/guestfs-java.pod b/java/examples/guestfs-java.pod
index bcff3889f..2d5627f62 100644
--- a/java/examples/guestfs-java.pod
+++ b/java/examples/guestfs-java.pod
@@ -161,6 +161,7 @@ on the class path, as well as the path of your program. For example:
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-lua(3)>,
L<guestfs-ocaml(3)>,
diff --git a/lib/guestfs.pod b/lib/guestfs.pod
index f2a54a1fd..b87210e65 100644
--- a/lib/guestfs.pod
+++ b/lib/guestfs.pod
@@ -1141,7 +1141,9 @@ See L<guestfs-erlang(3)>.
=item B<GObject>
Experimental GObject bindings (with GObject Introspection support) are
-available. See the C<gobject> directory in the source.
+available.
+
+See L<guestfs-gobject(3)>.
=item B<Go>
@@ -3393,6 +3395,7 @@ L<guestfs-examples(3)>.
Language bindings:
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
diff --git a/lua/examples/guestfs-lua.pod b/lua/examples/guestfs-lua.pod
index 36ea297ba..09de8d4a8 100644
--- a/lua/examples/guestfs-lua.pod
+++ b/lua/examples/guestfs-lua.pod
@@ -138,6 +138,7 @@ returned when you registered the callback:
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-ocaml(3)>,
diff --git a/ocaml/examples/guestfs-ocaml.pod b/ocaml/examples/guestfs-ocaml.pod
index 523a60466..2fa3d53c1 100644
--- a/ocaml/examples/guestfs-ocaml.pod
+++ b/ocaml/examples/guestfs-ocaml.pod
@@ -82,6 +82,7 @@ function that you called.
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
diff --git a/perl/examples/guestfs-perl.pod b/perl/examples/guestfs-perl.pod
index 1042f6948..6a9cb0ab5 100644
--- a/perl/examples/guestfs-perl.pod
+++ b/perl/examples/guestfs-perl.pod
@@ -41,6 +41,7 @@ L<Sys::Guestfs(3)>,
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
diff --git a/python/examples/guestfs-python.pod b/python/examples/guestfs-python.pod
index 0891827f6..8d4c2e51a 100644
--- a/python/examples/guestfs-python.pod
+++ b/python/examples/guestfs-python.pod
@@ -65,6 +65,7 @@ You can use it like this:
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
diff --git a/ruby/examples/guestfs-ruby.pod b/ruby/examples/guestfs-ruby.pod
index 5e4e1879a..bd8bb3108 100644
--- a/ruby/examples/guestfs-ruby.pod
+++ b/ruby/examples/guestfs-ruby.pod
@@ -36,6 +36,7 @@ string).
L<guestfs(3)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
+L<guestfs-gobject(3)>,
L<guestfs-golang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
--
2.13.2
More information about the Libguestfs
mailing list