[vala/staging] doc: Update man page to include more information on profiles

[Rico Tzschichholz <ricotz src gnome org>]

commit 4c63d52fb24b2b9847c5615c38f8e9f707bddd65
Author: Alistair Thomas <astavale yahoo co uk>
Date:   Sat May 8 12:43:43 2021 +0100

    doc: Update man page to include more information on profiles

 README.md                  |  5 +++++
 compiler/valacompiler.vala | 10 +++++-----
 doc/valac.1                | 12 +++++++++++-
 doc/valac.h2m              | 12 ++++++++++++
 doc/valadoc.1              |  2 +-
 valadoc/valadoc.vala       |  2 +-
 6 files changed, 35 insertions(+), 8 deletions(-)
---
diff --git a/README.md b/README.md
index fe0108802..45a16fd08 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,11 @@ Install the following packages:
  * automake
  * libtool
 
+These additional packages are needed to generate the documentation:
+
+ * help2man when updating the man pages
+ * xsltproc
+ * weasyprint for PDF generation
 
 ### Step Two:
 Decide where the Vala compiler is to be found.
diff --git a/compiler/valacompiler.vala b/compiler/valacompiler.vala
index 222e82d2e..a8ebd084e 100644
--- a/compiler/valacompiler.vala
+++ b/compiler/valacompiler.vala
@@ -153,7 +153,7 @@ class Vala.Compiler {
                { "pkg-config", 0, 0, OptionArg.STRING, ref pkg_config_command, "Use COMMAND as pkg-config 
command", "COMMAND" },
                { "dump-tree", 0, 0, OptionArg.FILENAME, ref dump_tree, "Write code tree to FILE", "FILE" },
                { "save-temps", 0, 0, OptionArg.NONE, ref save_temps, "Keep temporary files", null },
-               { "profile", 0, OptionFlags.OPTIONAL_ARG, OptionArg.CALLBACK, (void*) option_parse_profile, 
"Use the given profile instead of the default, options are 'gobject' or 'posix'", "PROFILE" },
+               { "profile", 0, OptionFlags.OPTIONAL_ARG, OptionArg.CALLBACK, (void*) option_parse_profile, 
"Minimum runtime dependency: 'gobject' (default) or 'posix' (minimal libc)", "PROFILE" },
                { "quiet", 'q', 0, OptionArg.NONE, ref quiet_mode, "Do not print messages to the console", 
null },
                { "verbose", 'v', 0, OptionArg.NONE, ref verbose_mode, "Print additional messages to the 
console", null },
                { "no-color", 0, 0, OptionArg.NONE, ref disable_colored_output, "Disable colored output, 
alias for --color=never", null },
@@ -522,7 +522,7 @@ class Vala.Compiler {
                if (context.report.get_errors () > 0 || (fatal_warnings && context.report.get_warnings () > 
0)) {
                        return quit ();
                }
-               
+
                if (!ccode_only) {
                        var ccompiler = new CCodeCompiler ();
                        if (cc_command == null && Environment.get_variable ("CC") != null) {
@@ -642,7 +642,7 @@ class Vala.Compiler {
                        stdout.printf ("Run '%s --help' to see a full list of available command line 
options.\n", args[0]);
                        return 1;
                }
-               
+
                if (version) {
                        stdout.printf ("Vala %s\n", Vala.BUILD_VERSION);
                        return 0;
@@ -650,12 +650,12 @@ class Vala.Compiler {
                        stdout.printf ("%s\n", Vala.API_VERSION);
                        return 0;
                }
-               
+
                if (sources == null && fast_vapis == null) {
                        stderr.printf ("No source file specified.\n");
                        return 1;
                }
-               
+
                var compiler = new Compiler ();
                return compiler.run ();
        }
diff --git a/doc/valac.1 b/doc/valac.1
index e132074e2..a1c0c3a9f 100644
--- a/doc/valac.1
+++ b/doc/valac.1
@@ -172,7 +172,17 @@ Write code tree to FILE
 Keep temporary files
 .TP
 \fB\-\-profile\fR=\fI\,PROFILE\/\fR
-Use the given profile instead of the default, options are 'gobject' or 'posix'
+Minimum runtime dependency: 'gobject' (default) or 'posix' (minimal libc)
+.RS
+\fIgobject\fR enables GLib's GType runtime type system. The runtime environment
+will usually require libgobject and its small number of dependencies.
+\fIposix\fR removes the dependency on GLib and disables the runtime type
+system. The profile either generates alternative code or errors at compile time
+if a Vala language feature is used that requires the runtime type system. This
+is useful for writing code, for example, that targets microcontrollers or
+for extremely small system utilities or container images. The runtime
+environment will usually require a small subset of the ISO C standard library.
+.RE
 .TP
 \fB\-q\fR, \fB\-\-quiet\fR
 Do not print messages to the console
diff --git a/doc/valac.h2m b/doc/valac.h2m
index 70740811d..97995fa5d 100644
--- a/doc/valac.h2m
+++ b/doc/valac.h2m
@@ -23,6 +23,18 @@ or \fB--no-color\fR are declared then \fB--color\fR=\fIauto\fR is used where
 output is colored when stderr is a terminal.
 .RE
 
+/Minimum runtime dependency/
+.RS
+\fIgobject\fR enables GLib's GType runtime type system. The runtime environment
+will usually require libgobject and its small number of dependencies.
+\fIposix\fR removes the dependency on GLib and disables the runtime type
+system. The profile either generates alternative code or errors at compile time
+if a Vala language feature is used that requires the runtime type system. This
+is useful for writing code, for example, that targets microcontrollers or
+for extremely small system utilities or container images. The runtime
+environment will usually require a small subset of the ISO C standard library.
+.RE
+
 /Enable support for ABI stability/
 .RS
 This changes the current behaviour to output public members of classes and
diff --git a/doc/valadoc.1 b/doc/valadoc.1
index a74d05e36..8e6411e2e 100644
--- a/doc/valadoc.1
+++ b/doc/valadoc.1
@@ -27,7 +27,7 @@ Base source directory
 Define SYMBOL
 .TP
 \fB\-\-profile\fR=\fI\,PROFILE\/\fR
-Use the given profile instead of the default, options are 'gobject' or 'posix'
+Minimum runtime dependency: 'gobject' (default) or 'posix' (minimal libc)
 .TP
 \fB\-\-enable\-experimental\fR
 Enable experimental features
diff --git a/valadoc/valadoc.vala b/valadoc/valadoc.vala
index 0854be157..69642864f 100644
--- a/valadoc/valadoc.vala
+++ b/valadoc/valadoc.vala
@@ -79,7 +79,7 @@ public class ValaDoc : Object {
 
                { "basedir", 'b', 0, OptionArg.FILENAME, ref basedir, "Base source directory", "DIRECTORY" },
                { "define", 'D', 0, OptionArg.STRING_ARRAY, ref defines, "Define SYMBOL", "SYMBOL..." },
-               { "profile", 0, OptionFlags.OPTIONAL_ARG, OptionArg.CALLBACK, (void*) option_parse_profile, 
"Use the given profile instead of the default, options are 'gobject' or 'posix'", "PROFILE" },
+               { "profile", 0, OptionFlags.OPTIONAL_ARG, OptionArg.CALLBACK, (void*) option_parse_profile, 
"Minimum runtime dependency: 'gobject' (default) or 'posix' (minimal libc)", "PROFILE" },
 
                { "enable-experimental", 0, 0, OptionArg.NONE, ref experimental, "Enable experimental 
features", null },
                { "enable-experimental-non-null", 0, 0, OptionArg.NONE, ref experimental_non_null, "Enable 
experimental enhancements for non-null types", null },