[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Libguestfs] [PATCH 3/3] gobject: Add outline guestfs-gobject(3) manual page.



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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]