Date: Mon, 19 Jun 2006 09:51:20 -0500 (CDT)
From: Dan Grayson <dan@math.uiuc.edu>
To: Amelia Taylor <ataylor@stolaf.edu>
CC: Michael Stillman <mike@math.cornell.edu>, dan@math.uiuc.edu
In-reply-to: <83F19922-5120-4BEB-AA8B-6120730E2CEF@math.cornell.edu> (message
	from Michael Stillman on Mon, 19 Jun 2006 09:42:28 -0400)
Subject: Re: Fwd: installing packages
Reply-to: dan@math.uiuc.edu


Dear Amelia,

I can offer a few hints about documentation writing that may help.

Here is a node.

document {
     Key => (universalEmbedding,Matrix),
     Headline => "compute the universal embedding of a module.",
     Usage =>  "g = universalEmbedding(I,f)", 
     Inputs => { 
     "I" => {"an ", TO Ideal},
     "f" => {"a ", TO Matrix, " over the same ring as I."}
     },
     Outputs => {"g" => {"a ", TO Matrix, " defining the universal ", 
	       " embedding of the image of f into a free module over R/I"}},
     "Stuff."
     }

Change

     Headline => "compute the universal embedding of a module.",

to

     Headline => "compute the universal embedding of a matrix.",

gibe with the type of the method.  Also, eliminate periods from headlines and
inputs:

     Headline => "compute the universal embedding of a matrix",

i.e., change

     "f" => {"a ", TO Matrix, " over the same ring as I."}

to

     "f" => {"a ", TO Matrix, " over the same ring as I"}


One way to save time is to not use redundant quotation marks.  M2 does a good
job now of eliminating redundant spaces from documentation, so

     Outputs => {"g" => {"a ", TO Matrix, " defining the universal ", 
	       " embedding of the image of f into a free module over R/I"}},

could be replaced by

     Outputs => {"g" => {"a ", TO Matrix, " defining the universal
	       embedding of the image of f into a free module over R/I"}},

Also, the function ofClass can be used to make clickable phrases like "a
matrix" which will link to the page for Matrix, which looks even better than "a
Matrix".  Use it this way:

     Outputs => {"g" => { ofClass Matrix, " defining the universal
	       embedding of the image of f into a free module over R/I"}},

But actually, M2 is already doing that for you (because this is the
documentation node of (universalEmbedding,Matrix), so M2 knows the first
argument is a matrix.  So you can shorten that to 

     Outputs => {"g" => { " defining the universal
	       embedding of the image of f into a free module over R/I"}},

Now that the thing inside the list is a single string (which doesn't
happen often) we can eliminate the braces and write this:

     Outputs => {"g" => " defining the universal
	       embedding of the image of f into a free module over R/I"},

Another hint is that the name "g" is sort of irrelevant, once the users
understand the notion of value or return value or output.  So change

     Usage =>  "g = universalEmbedding(I,f)", 

to

     Usage =>  "universalEmbedding(I,f)", 

and change

     Outputs => {" defining the universal
	       embedding of the image of f into a free module over R/I"},

Now I would like R/I to be in TT font, so I put the braces back and do this:

     Outputs => {{" defining the universal
	       embedding of the image of f into a free module over ", TT "R/I"}},

I have a handy emacs macro that does that for me.  I position the cursor over
the x in 

      " if x is a real number "

press M-C-Y and I get this:

      " if ", TT "x", " is a real number "

If I select the region sin(x) in the following 

      " the value sin(x) is "

and then press M-C-y I get this:

      " the value ", TT "sin(x)", " is "

That saves me a lot of time.


Here it is:

    (global-set-key [ (meta control y ) ] 'M2-text-to-TT)

    (defun M2-text-to-TT (arg)
      "Convert the region to TT mode."
      (interactive "p")
      (save-excursion
	(if (not mark-active) (mark-sexp arg))
	(let ((i (point)) (j (mark)) (k))
	  (if (> i j)
	      (let ((k i)) (setq i j) (setq j k)))
	  (goto-char j)
	  (insert "\", \"")
	  (goto-char i)
	  (insert "\", TT \"")
	  )))

Put that in your .emacs file somewhere.

Let me know if that all helps.

