diff options
author | Christoph Reiter <reiter.christoph@gmail.com> | 2018-06-10 11:24:47 +0200 |
---|---|---|
committer | Christoph Reiter <reiter.christoph@gmail.com> | 2018-06-16 11:47:01 +0200 |
commit | 539dfca540759b8a97e6906981d4240ca044af9f (patch) | |
tree | 52562f8e255e8a663ab27e44c8bf1b8d7a9a6cf0 /docs/g-ir-scanner.1 | |
parent | 06660d70e1899d9ad9b3c951073fb9a13652da9d (diff) | |
download | gobject-introspection-539dfca540759b8a97e6906981d4240ca044af9f.tar.gz |
Sphinx based user documentation
The current output (more or less a straight copy of the wiki) is available
here:
https://gi.readthedocs.io
This contains two changes:
* Converts all (not completely outdated) wiki pages to a sphinx based
documentation.
* Converts the man pages to reST and adds a Makefile for building them
using rst2man. So they can be easily exposed in the sphinx docs.
Goals:
* Have a user focused/compact documentation instead of random wiki pages
with various todo/ideas pages.
* Take advantage of the gitlab MR workflow by
* allowing large documentation changes/refactorings with reviews
* allowing to combine features changes with documentation changes in MRs
Diffstat (limited to 'docs/g-ir-scanner.1')
-rw-r--r-- | docs/g-ir-scanner.1 | 251 |
1 files changed, 137 insertions, 114 deletions
diff --git a/docs/g-ir-scanner.1 b/docs/g-ir-scanner.1 index d38241f1..2078d927 100644 --- a/docs/g-ir-scanner.1 +++ b/docs/g-ir-scanner.1 @@ -1,154 +1,177 @@ -.TH "g-ir-scanner" 1 -.nh +.\" Man page generated from reStructuredText. +. +.TH G-IR-SCANNER 1 "" "" "" .SH NAME -g-ir-scanner \- extracting C metadata from sources and headers +g-ir-scanner \- Extracting C metadata from sources and headers +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. .SH SYNOPSIS -.B g-ir-scanner -[OPTION...] FILES... +.sp +\fBg\-ir\-scanner\fP [OPTION...] FILES... .SH DESCRIPTION -g-ir-scanner is a tool which generates GIR XML files by parsing headers -and introspecting GObject based libraries. -It is usually invoked during the normal build step for a project and -the information is saved to disk and later installed, so that language bindings -and other applications can use it. -Header files and source files are passed in as arguments on the command line. -The suffix determines whether a file be treated as a source file (.c) or a -header file (.h). Currently only C based libraries are supported by the scanner. +.sp +g\-ir\-scanner is a tool which generates GIR XML files by parsing headers and +introspecting GObject based libraries. It is usually invoked during the normal +build step for a project and the information is saved to disk and later +installed, so that language bindings and other applications can use it. Header +files and source files are passed in as arguments on the command line. The +suffix determines whether a file be treated as a source file (.c) or a header +file (.h). Currently only C based libraries are supported by the scanner. .SH OPTIONS +.INDENT 0.0 .TP -.B \--help +.B \-\-help Show help options .TP -.B \--quiet +.B \-\-quiet If passed, do not print details of normal operation. .TP -.B \--warn-all +.B \-\-warn\-all Display warnings for public API which is not introspectable. .TP -.B \--warn-error +.B \-\-warn\-error Make warnings be fatal errors. .TP -.B \--format=FORMAT -This parameters decides which the resulting format will be used. -The default value is gir. +.BI \-\-format\fB= FORMAT +This parameters decides which the resulting format will be used. The +default value is gir. .TP -.B \--include=NAME +.BI \-\-include\fB= NAME Add the specified introspection dependency to the scanned namespace. -NAME is of the form NAMESPACE-VERSION, like Gtk-3.0. +NAME is of the form NAMESPACE\-VERSION, like Gtk\-3.0. .TP -.B \--include-uninstalled=PATH +.BI \-\-include\-uninstalled\fB= PATH Add the specified introspection dependency to the scanned namespace. -This differs from \--include in that it takes a file path, and -does not process the pkg-config dependencies (since they may not -be installed yet). +This differs from \fB\-\-include\fP in that it takes a file path, and does not +process the pkg\-config dependencies (since they may not be installed yet). .TP -.B \--add-include-path=PATH -Add a directory to the path which the scanner uses to find GIR files. -Can be used multiple times to specify multiple directories +.BI \-\-add\-include\-path\fB= PATH +Add a directory to the path which the scanner uses to find GIR files. Can +be used multiple times to specify multiple directories .TP -.B \-i, --library=LIBRARY +.BI \-i\fP,\fB \-\-library\fB= LIBRARY Specifies a library that will be introspected. This means that the -*_get_type() functions in it will be called for GObject data types. -The name of the library should not contain the leading lib prefix nor -the ending shared library suffix. +*_get_type() functions in it will be called for GObject data types. The +name of the library should not contain the leading lib prefix nor the +ending shared library suffix. .TP -.B \-L, --library-path=PATH -Include this directory when searching for a library. -This option can be specified multiple times to include more than one -directory to look for libraries in. +.BI \-L\fP,\fB \-\-library\-path\fB= PATH +Include this directory when searching for a library. This option can be +specified multiple times to include more than one directory to look for +libraries in. .TP -.B \-Idirectory +.BI \-I\fB directory Include this directory in the list of directories to be searched for -header files. You need to pass to the scanner all the directories -you'd normally pass to the compiler when using the specified source -files. +header files. You need to pass to the scanner all the directories you\(aqd +normally pass to the compiler when using the specified source files. .TP -.B \-n, --namespace=NAME +.BI \-n\fP,\fB \-\-namespace\fB= NAME The namespace name. This name should be capitalized, eg the first letter should be upper case. Examples: Gtk, Clutter, WebKit. .TP -.B \--no-libtool -Disable usage of libtool for compiling stub introspection binary. Use this +.B \-\-no\-libtool +Disable usage of libtool for compiling stub introspection binary. Use this if your build system does not require libtool. .TP -.B \--libtool -Full path to libtool executable. Typically used for Automake systems. +.B \-\-libtool +Full path to libtool executable. Typically used for Automake systems. .TP -.B \--nsversion=VERSION -The namespace version. For instance 1.0. This is usually the platform version, -eg 2.0 for Gtk+, not 2.12.7. +.BI \-\-nsversion\fB= VERSION +The namespace version. For instance 1.0. This is usually the platform +version, eg 2.0 for Gtk+, not 2.12.7. .TP -.B \-p, --program=PROGRAM +.BI \-p\fP,\fB \-\-program\fB= PROGRAM Specifies a binary that will be introspected. This means that the -*_get_type() functions in it will be called for GObject data types. -The binary must be modified to take a --introspect-dump= option, and -to pass the argument to this function to g_irepository_dump. +*_get_type() functions in it will be called for GObject data types. The +binary must be modified to take a \fB\-\-introspect\-dump=\fP option, and to pass +the argument to this function to g_irepository_dump. .TP -.B \--program-arg=ARG +.BI \-\-program\-arg\fB= ARG Additional argument to pass to program for introspection. .TP -.B \--identifier-prefix=PREFIX -This option may be specified multiple times. Each one -gives a prefix that will be stripped from all C identifiers. -If none specified, the namespace will be used. -Eg, an identifier prefix of -.B Foo -will export the identifier -.B typdef struct _FooBar FooBar; -as -.B Foo.Bar. -.TP -.B \--symbol-prefix=PREFIX -This option may be specified multiple times. Each one -gives a prefix that will be stripped from all C symbols. -Eg, an symbol prefix of -.B foo -will export the symbol -.B foo_bar_do_something -as -.B Foo.Bar.do_something. -.TP -.B \--accept-unprefixed -If specified, the scanner will accept identifiers and symbols which -do not match the namespace prefix. Try to avoid using this if possible. -.TP -.B \--output=FILENAME -Name of the file to output. Normally namespace + format extension. -Eg, GLib-2.0.gir. -.TP -.B \--pkg=PACKAGE -List of pkg-config packages to get compiler and linker flags from. -This option can be specified multiple times to include flags from -several pkg-config packages. -.TP -.B \--pkg-export=PACKAGE -List of pkg-config packages that are provided by the generated gir. -This option can be specified multiple times if the gir provides more -packages. -If not specified, the packages specified with --pkg= will be used. -.TP -.B \--verbose +.BI \-\-identifier\-prefix\fB= PREFIX +This option may be specified multiple times. Each one gives a prefix that +will be stripped from all C identifiers. If none specified, the namespace +will be used. Eg, an identifier prefix of Foo will export the identifier +typdef struct _FooBar FooBar; as Foo.Bar. +.TP +.BI \-\-symbol\-prefix\fB= PREFIX +This option may be specified multiple times. Each one gives a +prefix that will be stripped from all C symbols. Eg, an symbol +prefix of foo will export the symbol foo_bar_do_something as +Foo.Bar.do_something. +.TP +.B \-\-accept\-unprefixed +If specified, the scanner will accept identifiers and symbols which do not +match the namespace prefix. Try to avoid using this if possible. +.TP +.BI \-\-output\fB= FILENAME +Name of the file to output. Normally namespace + format extension. Eg, +GLib\-2.0.gir. +.TP +.BI \-\-pkg\fB= PACKAGE +List of pkg\-config packages to get compiler and linker flags from. This +option can be specified multiple times to include flags from several +pkg\-config packages. +.TP +.BI \-\-pkg\-export\fB= PACKAGE +List of pkg\-config packages that are provided by the generated gir. This +option can be specified multiple times if the gir provides more packages. +If not specified, the packages specified with \fB\-\-pkg=\fP will be used. +.TP +.B \-\-verbose Be verbose, include some debugging information. -.TP +.UNINDENT .SH ENVIRONMENT VARIABLES -The g-ir-scanner uses the XDG_DATA_DIRS variable to check for dirs, -the girs are located in XDG_DATA_DIRS/gir-1.0. It is normally -set on a distribution so you shouldn't need to set it yourself. - -The variable GI_SCANNER_DISABLE_CACHE ensures that the scanner will -not write cache data to $HOME. - -The variable GI_SCANNER_DEBUG can be used to debug issues in the build-system that -involve g-ir-scanner. When it is set to 'save-temps', then g-ir-scanner will not remove -temporary files and directories after it terminates. - -The variable GI_HOST_OS can be used to control the OS name on the -host that runs the scanner. It has the same semantics as the Python -os.name property. +.sp +The g\-ir\-scanner uses the \fBXDG_DATA_DIRS\fP variable to check for dirs, the +girs are located in \fBXDG_DATA_DIRS/gir\-1.0\fP\&. It is normally set on a +distribution so you shouldn\(aqt need to set it yourself. +.sp +The variable \fBGI_SCANNER_DISABLE_CACHE\fP ensures that the scanner will not +write cache data to \fB$HOME\fP\&. +.sp +The variable \fBGI_SCANNER_DEBUG\fP can be used to debug issues in the +build\-system that involve g\-ir\-scanner. When it is set to \fBsave\-temps\fP, then +g\-ir\-scanner will not remove temporary files and directories after it +terminates. +.sp +The variable \fBGI_HOST_OS\fP can be used to control the OS name on the host +that runs the scanner. It has the same semantics as the Python \fBos.name\fP +property. .SH BUGS -Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues. -.SH HOMEPAGE and CONTACT -http://live.gnome.org/GObjectIntrospection +.sp +Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP +.SH HOMEPAGE AND CONTACT +.sp +\fI\%http://live.gnome.org/GObjectIntrospection\fP .SH AUTHORS +.sp Johan Dahlin - +.\" Generated by docutils manpage writer. +. |