Document .target_debug and .pregen.

doc/user_guide.texi

@@ -1516,14 +1516,80 @@ and is compatible only with them.
 @node Grade modifiers for target language debugging
 @subsection Grade modifiers for target language debugging
 
-ZZZ TODO
+Mercury programs intended to be debugged
+using @command{mdb}, the Mercury debugger.
+However, @command{mdb} treats non-Mercury code as a black box,
+and cannot give any insights into its behavior.
+
+@table @code
+@item .target_debug
+Compiling programs in a grade that
+includes the @code{.target_debug} grade modifier
+generates executables that are intended to be debuggable
+with usual debuggers for the target language selected by the base grade.
+
+This grade modifier is intended mainly
+to help the implementors of Mercury itself debug interactions
+between compiler-generated target code and the Mercury runtime system.
+However, in certain rare cases, it may also be useful to other users
+in debugging interactions between compiler-generated target code
+and the contents of @code{foreign_proc} and/or @code{foreign_code} pragmas.
+
+This grade modifier could be applicable to all base grades,
+but is intentionally restricted to MLDS grades.
+This is because in LLDS grades,
+the assembler-like C code generated by @command{mmc}
+will probably confuse debuggers such as @command{gdb},
+and it will definitely confuse
+any Mercury programmer whose is not a Mercury implementor.
+The more idiomatic target language code
+that @command{mmc} generates in MLDS grades
+is still far from trivial for non-implementors to understand,
+but at least they have a fighting chance.
+@end table
 
 @c ----------------------------------------------------------------------------
 
 @node Grade modifiers for pregenerated source distributions
 @subsection Grade modifiers for pregenerated source distributions
 
-ZZZ TODO
+There is one grade modifier that users will probably encounter
+that they will propably never need to use themselves.
+This the grade modifier that the Mercury team itself
+uses only for a single purpose: making source distributions.
+Such distributions include not just the code of the Mercury system,
+which is mostly written in Mercury itself.
+but also the C code generated for each Mercury module.
+This allows people
+who do not have a working Mercury installation on their machine to create one.
+
+@table @code
+@item .pregen
+Compiling programs in a grade that
+includes the @code{.pregen} grade modifier
+switches off all optional features,
+and tells the compiler to make the fewest possible assumptions
+about the platform on which the generated code will run.
+(For example, the generated code will work
+on both 32-bit and 64-bit platforms.)
+
+Source distributions use grades that include this modifier
+(the grade usually being @code{hlc.gc.pregen})
+because it makes the C code in them portable to as many platforms as possible.
+However, it has no advantages beyond this,
+and, on 64-bit machines,
+the requirement to use a data representation scheme
+that also works on 32-bit platforms
+imposes a nontrivial cost in performance.
+This is why for pretty much any purpose other than source distributions,
+other grades are a better choice.
+
+This grade modifier is applicable
+only to the base grades @code{hlc} and @code{none}.
+@c Actually, grade_lib/grade_structure.m also allows it
+@c for the reg and asm_fast base grades as well, but that conflicts with
+@c the whole "make as few assumptions about the platform as possible" thing.
+@end table
 
 @c ----------------------------------------------------------------------------