This is an intended description of the Ultra64 documentation style guide and
structure.

Style Guide
-------------------------------------------------------------------------------

Use template u64template, you can even use this template to convert your
current documentation in whatever framemaker format. Eventually, this template
becomes the master character/paragraph/document format archive. We will add
new unanticipated formats in here and convert all our docs.

Most documents will use the following typical paragraph and character formats

	paragraph
		BulletInd
		ChapTitle
		Text
		List1st
		Heading1
		Heading2
		FigTitle
		FigBody		These are for paragraphs in a figure
		TableHead
		TableTitle
		TableText
		Note

	character
		FigText		These are for single line text in a figure
		
		All paragraphs have default character fonts. So single line
		text within figures are the only text you need to explicitly 
		set the character format.

Figures
	Choose a right aligned figure and set the paragraph above the figure
	to FigTitle. Drag the left margin to align with the right margin of
	the text. Be sure to use the template format to begin with. If not,
	the left margin of the text may be different.

	Our documentation format leaves the left 2.5-3 inches blank. This makes
	complex picture hard to draw. The easiest way is to use the zoom
	buttons on the bottom of the frame and zoom up to 200%. Draw your
	picture, than zoom back down to your desired proportion.

	Fonts: For paragraphs, use FigBody, for single line text, use Character
	format FigText.

	Arrows: There are no automatic way of keeping arrow/line style
	consistent. In general, use 90/30/6 pt arrow and 0.5 pt lines widths.

Tables
	Choose Table Format Table2col. Keep in mind that the 1st row is a
	heading row and describes what is the purpose of each column. This
	row uses a different font. Of course, if you need TableNcol, go ahead.

	To insert the table name, put a space after the table index (Table X-Y)
	to separate the table name from table index.

Sections
	Use Heading1 and Heading2 to separate each section

Links
	It would be cool to provide properly cross referencing links to other
	parts of the documentation. If within your own part of the
	documentation, use ChapRef1st w/o end punct under the
	Special/Cross-Reference menu. Bound the cross-ref with () to dilineate
	it from the other text. If referencing a section that does not
	exist yet, put XXX LINK for cross linking later. CROSS-REFERENCE does
	not work across books.

Books
	Overview book
	Graphics book
	Audio book
	OS book
	Development Env book
	Man pages book

Documentation Structure Outline for release 3.x of Ultra64
-------------------------------------------------------------------------------

Roadmap to the following documentation

Softwar Bringup Top 10 Gotchas
	addressing - pointers pointers pointers (KSEG0, segmented, physical)
		Matrix + Viewport + c/z fb.
	RSP/RDP state initialization
	more?

Capabilities - brief teaser outline

System Architecture

	hardware architecture
		- describe all parallel processors + IO + memory: from the apps
			point of view. eg. RSP DMA engine may not be exposed
		- typical data type and flow for audio and graphics
		- describe each hw subcomponent and their basic functionality
		- processor addressing scheme CPU/IO/SP/DP (memory map)
		- raw bandwidth and derated typical bandwidth

	software architecture
		- run time env
X			- resource access vs. resource mgmt
X				draw app/mgmt layer/access diagram
X			- CPU access: threads + message pass + intr handler
X				tlb + cache access
X			- IO access: device lib + device mgr + timers
X			- MEM access: static alloc + region lib
X			- gfx access: processor config/gbi/ucode/rdp commands
				what processor does what.
			- audio access: processor config/seq + audio player +
				driver + ucode. stream paging memory. feature
				set. what processor does what.
			- typical app thread structure, coarse description
X			- debugger, arch, workshop, rmon, CPU+RSP debug
		- compile time env
X			- gfx tool path: ningen/alias/other/flt2c/rgb2c
			- audio tool path: composition/wavetable building
X			- common tool path: cc/makerom

Programmer's Guide - OS services
X	overall architecture/components
X	threads
X	message queues
X	exception handling
	storage allocation - region
	time management (TBD)
X	I/O subsystem
	system initialization (bootup sequence)

Programmer's Guide - graphics
	graphics pipeline
	sp/dp graphics DL
	2D vs 3D graphics support (2D libs, 3D api/abi gu etc)
	ucode types + functionality for each ucode type
S	RSP state machine + overview command description (no man page)
X	RDP state machine + overview command description (no man page)
X	Texture document
	Color combiner document
	Blender document

X Programmer's Guide - sprite library

Programmer's Guide - audio
X	overall architecture/components
X	sequences
X	sounds
X	sequence player
X	sound player
S	format

Programmer's Guide - application integration
	- memory map: full map + optimal placements (c/z buffer + 64b alignment)
	- components of the application framework
		- maximize sp/dp utilization: audio/graphics timeslicing
		- cpu/pipeline processing parallelization
		- execution overruns: gfx/cntx sw
		- XXX other important components ???
	- typical app thread structure, sample app, detailed description

Development Environment
	development hardware architecture
	development software architecture
	Debugger Users Guide - use cvd book, gvd delta doc, rsp debugger.
		getting started on CPU/RSP debugging.

RSP Programmers Guide
	RSP Programmer's guide

Appendix A
	Manual pages for tools
		flt2c
		rgb2c
		makerom
		gvd
		dbgif
X	Command Description + Manual pages for RSP graphics commands
		each command documentated in bit field defn + cpp mbi.h
X	Command Description + Manual pages for RDP commands
		each command documentated in bit field defn + cpp mbi.h
X	Manual pages for graphics utility functions
X	Manual pages for OS functions
	Manual pages for region lib functions
X	Manual pages for audio functions

Appendix B
	Register Map

Appendix C
	Summary of HW performance numbers - w/cautions
		SP graphics ucode
		DP graphics fill
		data moving (ROM/RAM ...)