[m-rev.] for review: stseg grades documentation

[Julien Fischer]

For review by PeterW.

Estimated hours taken: 0.5
Branches: main

compiler/options.m
doc/user_guide.texi:
 	Address some of PeterW's comments regarding the documentation
 	of the .stseg grades

 	Comment out the documentation for the `--extend-stack-when-needed'
 	option, since this it is still experimental.

Julien.

Index: compiler/options.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/compiler/options.m,v
retrieving revision 1.599
diff -u -r1.599 options.m
--- compiler/options.m	6 Nov 2007 05:25:08 -0000	1.599
+++ compiler/options.m	6 Nov 2007 05:52:07 -0000
@@ -3833,13 +3833,11 @@
          "--single-prec-float\t\t(grade modifier: `.spf')",
          "\tUse single precision floats so that, on 32-bit machines,",
          "\tfloating point values don't need to be boxed.  Double",
-        "\tprecision floats are used by default.",
-        "--extend-stacks-when-needed",
-        "\tSpecify that code that increments a stack pointer must",
-        "\textend the stack when this is needed.",
-        "--stack-segments\t\t(grade modifier: `.stseg')",
-        "\tSpecify that code that increments a stack pointer must allocate",
-        "\ta new stack segment when the limit on the old one is reached."
+        "\tprecision floats are used by default."
+        % This is commented out as this feature is still experimental.
+        %"--extend-stacks-when-needed",
+        %"\tSpecify that code that increments a stack pointer must",
+        %"\textend the stack when this is needed.",
          % RBMM is undocumented since it is still experimental.
          % should also document rbmmd rbmmp rbmmdp
          %"--use-regions\t\t(grade modifier: `.rbmm')",
@@ -3872,7 +3870,13 @@
          "\tSelect a register usage convention that is compatible,",
          "\twith position-independent code (gcc's `-fpic' option).",
          "\tThis is necessary when using shared libraries on Intel x86",
-        "\tsystems running Unix.  On other systems it has no effect."
+        "\tsystems running Unix.  On other systems it has no effect.",
+        "--stack-segments\t\t(grade modifier: `.stseg')",
+        "\tSpecify whether to use dynamically sized stacks that are",
+        "\tcomposed of small segments.  This can help to avoid stack",
+        "\texhaustion at the cost of increased execution time.",
+        "\tThis option is ignored if the `--high-level-code' option is",
+        "\tenabled."
      ]),

      io.write_string("\n    MLDS back-end compilation model options:\n"),
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.550
diff -u -r1.550 user_guide.texi
--- doc/user_guide.texi	6 Nov 2007 05:25:09 -0000	1.550
+++ doc/user_guide.texi	6 Nov 2007 05:52:08 -0000
@@ -7169,8 +7169,8 @@
  @item Whether to use single-precision representation of floating point values:
  @samp{spf} (the default is to use double-precision floats)

- at item Whether to allocate a new stack segment when the limit on the old one
-is reached: @samp{stseg} (the default is not to allocate a new stack segment)
+ at item Whether to use dynamically sized stacks that are composed of
+small segments: @samp{stseg} (the default is to used fixed size stacks)

  @item What debugging features to enable:
  @samp{debug} and @samp{decldebug} (the default is no debugging features).
@@ -7423,6 +7423,15 @@
  running Unix.  On other systems it has no effect.
  This option is also ignored if the @samp{--high-level-code} option is enabled.

+ at sp 1
+ at item @code{--stack-segments} (grades: any grade containing `.stseg')
+ at findex --stack-segments
+ at cindex Stack segments
+Specify whether use dynamically sized stacks that are composed of small
+segments.
+This can help to avoid stack exhaustion at the cost of increased
+execution time.
+This option is ignored if the @samp{--high-level-code} option is enabled.
  @end table

  @node MLDS back-end compilation model options

--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------