[Mono-docs-list] New guy on the list

[Willem J.W. Semmelink]

Hi all
I am a new subscriber on the list, so I can just as well tell who I am. 
I live in Pretoria, South Africa, and I have some 7 years experience as
a software developer, mostly using a 4GL or C++ for development. I got
interested in .Net from last year, and I visit the Mono website
regularly since an article appeared in DrDobs in January.

In a recent MONO for Windows installation package, the following text
appeared in the file Helping.HTM:

>> If you are a programmer you could help the mono project at
go-mono.org
>> Of course not as important, but still cool, I think it would be to
have something like the "Start here" Overview in the .NET Framework. 
>>This would include >>examples, tutorials and Quickstart Guides, a
better README, an overview about the tools, possibly a C# tutorial. 
>> If you have some good ideas and are better in english than I am you
could help ;-)
>> Johannes Roith
>>mail: johannes@jroith.de <mailto:johannes@jroith.de> 

After several e-mails to the above address returned undelivered, I then
decided to subscribe to the list, and air my views here. I think I can
perhaps help with an overview of the tools and the C# tutorial.

An archive of the list focused on an XML format for these external
documents - I am uncertain whether the issue is closed, and whether a
standard format now exists for such documents. The XML examples I saw,
are more relevant to documenting the .NET API than a training manual,
e.g. 
<class name="System.Object"> 
     <method>string ToString ()</method> 
     <method>int GetHashCode ()</method> 
</class> 
After reading the list archives, I can also not exactly determine
whether I should still wait till the GUI tool and browser tool are
finished before contributing. If a standard DTD for a training doc is
set, I can start contributing by typing the raw XML. At the bottom of
this <long> message, I propose an outline of a tutorial page. Perhaps we
can design a DTD specifically for that purpose.
A good starting point would perhaps be to determine a table of contents
for a "start here" document. I propose one below. Hope that my
contribution helps.   
Greetings 
Willem Semmelink

My suggestion for a table of contents:
1. What is the mono project?
	1.1. Overview of Microsoft .NET. <standardisation of the common
language, and C#>
	1.2. Overview of MONO.
	1.3. Tools: compiler, runtime, linker, debugger, etc.. 
	1.4. Other tools available: SharpDevelop IDE, NAnt, NUnit, ...
2. Getting started
	1.1 Installing Mono
		1.1.1 Hardware and software requirements 
		1.1.2 Installation procedure (separate entries for each
operating system)			
		1.1.3 Directory structure of the installed product and
purpose of sub-folders
		1.1.4 List of the installed files and their Purpose 
	1.2. Hello World application
		1.2.1. Illustrate use of the compiler command-line
syntax
		1.2.1. Basic C# program structure: class with main
member function, etc...
	1.3. Running a program: use of the mono run-time
	1.4. Microsoft .NET
		List the Mono files and their corresponding Microsoft
counterparts.
		Describe any differences in usage 
	1.5. Working with Gtk#
		1.5.1. Installing Gtk2 on Linux, Windows ....
		1.5.2 Installing Gtk# 
		1.5.3 Example program
		1.5.4 Errors and possible causes 
		1.5.5 More information (Refer to Gtk manual?)
	1.6. Working with Qt#?
	1.7. Working with Windows.Forms (probably only when Mono classes
were sufficiently implemented )
3. C# tutorial
	3.1 Introduction
		3.1.1. Tutorial conventions
		3.1.2. Where to get assistance: published books,
newsgroups, on-line help
		3.2.3 C# introduction (C - C++ - C# ) (C# and Java)
			(why use C#)?
		3.2.4 C# Hello World application: main language features
			- Application startup
			- Application termination 
				(and mention garbage collector?)
			- 
		3.2.5 Overview of the C# compiler
	3.2. C# Types
		3.2.1 Static versus dynamic memory management
			- Value types versus reference types
			- Boxing and unboxing
		3.2.2 Variables
			- Categories of variables
			- Declarations
			- basic types
			- enums
			- variable assignment
			- type conversion (implicit | explicit)

		3.2.3 Structs
		3.3.3 Classes
			- Class declarations
			- Constructors
			- Destructors
			- Class members
				= Struct, enum, class, interface, array
etc
				= Accessibility: private, protected,
public, internal
				= overloading, 
			- Fields
			- Methods
			- Properties
			- Events (Delegates)
			- Indexers
			- Operators
		3.3.4 Arrays
		3.3.5 Enums
		3.3.6 Interfaces
		3.3.7 Namespaces
			- namespace declarations
			- Compilation units
			- using directives
	3.3. Program structure
		3.3.1 Expressions
			- Defined
			- Operators (presedence, overloading, unary,
binary)
			- Function calls
		3.3.2 Statements
			- Block statements
			- Declaration statements
			- Selection (if, switch)
			- Iteration statements
			- foreach and collection classes
			- Jump statements (break, goto, continue,
return, throw)
			- try, locked, check, using statements
		3.3.3 Line terminators, white space and comments
		3.3.4 Grammar:
			Identifiers, Keywords, Literals		
	3.5 Strings
		3.4.1 Unicode
		3.4.2 Char
		3.4.3 String
		3.4.4 Escape sequences
		3.4.5 StringBuilder class
	3.6 Exceptions
	3.7 Unsafe code
	3.8 Libraries and platform invokes (perhaps illustrate using
GTK# internals as example)
	3.9 GUI programming using Windows.Forms	
	3.10 The C# compiler in detail
		3.10.1. Compiler command-line options
		3.10.2. Compiler errors 
	3.11 Preprocessor directives
	3.12 XML documentation
	3.13 Windows COM / Gnome Bonobo interoperability
	3.14 Threading
	3.15 Security
	3.16 Database access
4. .Net class libraries
	Link to the mcs/docs/apidocs documentation from the current Mono
documentation project	
5. Example applications
--------------------------------------------------------------
A basic tutorial page, in my opinion, should contain the following:
Heading
Description of the topic
C# syntax
More detailed notes, perhaps things that advanced users may be concerned
about, such as possible hidden performance implications such as
automatic boxing that may not be apparent to new users.  
C++ users note: Some notes that C++ developers converting to C# should
be aware of. 
Java users note: Some notes that Java developers converting to C# should
be aware of.
<other languages conversion notes? >
Program example: small example program that illustrates the topic being
described.
See Also:  Links to other topics that are related
---------------------------------------------------------------------
Possible XML format for tutorial page:
<Tutorial>
  <Topic>
    <Heading>      </Heading>	
    <Description>	 </Description>
    <Code>         </Code>	
    <Detail>       </Detail>	
    <OtherLang>
		<Cpp>  </Cpp>
            <Java> </Java>
    </OtherLang>
    <Example>      </Example>
    <SeeAlso>      </SeeAlso> 	
  </Topic>
</Tutorial>
---------------------------------------------------------------------