[M3devel] Looking to update cm3 manual page.

[Peter Eiserloh]

Hi all,

It has been more than half a year since I last looked at the
CM3 manual page.  I am now looking at the it in preparation 
for the release of version 5.8, and noticing some deficiencies.

I asking for help in identifying any further places it is lacking.
I can integrate any feedback into a revised manual page, and
submit an updated version back to the archives.


Currently identified deficiencies: 

o The manual page should explicitly state which version of the
  compiler it documents.

o The sub-section "Expected Directory Structure" needs a better
  discussion, especially an introduction.

o The discussion of mode option "-ship" mentions environment
  variable CM3_INSTALL_ROOT, yet in cm3.cfg we set INSTALL_ROOT
  without the  "CM3_" prefix.  This should be resolved.

  ** What is the exact meaning of these two?  Is one recognized
     by the compiler, and the other by the supporting quake
     code?

o The ENVIRONMENT section does not mention CM3_INSTALL_ROOT
  at all.  Add a discussion about both INSTALL_ROOT, and
  CM3_INSTALL_ROOT.

  ** Am I missing any other environment variables?

o Missing command line options for the compiler:

  - I currently have "-g", but no discussion of -gstabs.
    No discussion about not supporting DWARF (or do we?).

o Compiler unique language features, (i.e., pragmas).  The
  reference books (Nelson, and Harbison) give a list of 
  suggested pragmas.  The manual page should list the ones
  supported by the CM3 compiler explicitly, and show their
  syntax.

  ** Can someone list for me the pragmas supported by the
     current (5.8.4) compiler.

o Should list any limitations of either the compiler, or
  the library suite provided with the compiler.  

  For example, the WIDECHAR is limited by its 16-bit size
  to only a portion of the unicode character set 
  (the basic multi lingual plane), whereas a unicode 
  character is 20-bits, and we would need either a 
  24-bit or 32-bit sized type to contain it all.

  ** Are there any other known limitations of the compiler,
     or library suite?
       - length of identifier?
       - length of TEXT (ie, memory)
       - length of filenames, or pathname 
         (some architectures may have differences, 
         ie MS-Windows).

o There should be a discussion of the @m3XXX runtime
  library command line options.

o There should be an EXAMPLE section, with example 
  source code (Hello world), along with supporting 
  m3makefile.


+--------------------------------------------------------+
| Peter P. Eiserloh                                      |
+--------------------------------------------------------+