prompt <- function(object, ...) UseMethod("prompt")

## Later, we may want  a data.frame method ..

prompt.default <-
function(object, filename = paste0(name, ".Rd"), force.function = FALSE)
{
	paste0 <- function(...) paste(..., sep = "")
	is.missing.arg <- function(arg)
	  mode(arg) == "symbol" && deparse(arg) == ""
	name <- substitute(object)
	if(is.language(name) && !is.name(name)) name <- eval(name)
	name <- as.character(name)
	fn <- get(name)
	##-- 'file' will contain the "lines" to be put in the  manual file
	if(is.function(fn) || force.function) {
		argls <- formals(fn)
		s <- seq(length = n <- length(argls))
		if(n > 0) {
			arg.names <- arg.n <- names(argls)
			arg.n[arg.n == "..."] <- "DOTS"
		}
		file <- paste0("TITLE(", name, " @@ ~~function to do ... ~~)")

		##-- Construct the 'call':
		call <- paste0(name, "(")
		for(i in s) {
			n.i <- arg.n[i]
			call <- paste0(call, n.i,
				       if(!is.missing.arg(argls[[i]]))
				       paste0("=",deparse(argls[[i]])))
			if(i != n) call <- paste0(call, ", ")
		}
		file <- c(file, "USAGE(", paste0(call, ")"),
			  ")", paste0("ALIAS(", name, ")"))

		if(length(s))
		  file <- c(file, "ARGUMENTS(",
			    paste0("ARG(", arg.n, " @@",
				   " ~~Describe ", arg.names, " here~~	)"),")")
		fn.def <- deparse(fn)
		if(any(br <- substr(fn.def,1,1) == ")"))
		  fn.def[br] <- paste(" ", fn.def[br])
		file <- c(file,
			  "DESCRIPTION(",
			  "~~ a precise description of what the function does. ~~",
			  ")",
			  "VALUE(",
			  "~Describe the value returned",
			  ")",
			  "~~~~~~~ For	multiple values (list), use 'VALUES' INSTEAD !",
			  "		---------------		     ------",
			  "VALUES(",
			  "A description of the LIST of values returned.  Use",
			  "@@",
			  "ARG(comp1 @@ Description of `comp1')",
			  "ARG(comp2 @@ Description of `comp2')",
			  "...",
			  ")",

			  "REFERENCES(",
			  "~put references to the literature / web site here,...",
			  ")",
			  "NOTE(",
			  "~further notes~",
			  ")",
			  "~make other sections like WARNING with SECTION(WARNING @@....)~",

			  "SEEALSO(", "~ functions to SEE ALSO as  LANG(LINK(~~fun~~))",
			  ")",

			  "EXAMPLES(",
			  "##---- Should be DIRECTLY executable !! ----",
			  "##-- ==>  Define data, use random,",
			  "##--	     or do  help(data=index)  for the standard data sets.",
			  "BLANK", "## The function is currently defined as",
			  fn.def,
			  ")",
			  "KEYWORD( ~keyword )"
			  )
	} else {#-- not function --
		file <- c("NON_FUNCTION()",
			  paste("TITLE(", name, "@@ ~~data-name / kind ...  )"),
			  "DESCRIPTION(",
			  "~~ a precise description of what the function does. ~~",
			  ")")
	}
	cat(file, file = filename, sep = "\n")
	RHOME <- system("printenv RHOME", intern = TRUE)
	if(substr(RHOME,1,8) == "/tmp_mnt") RHOME <- substr(RHOME,9,1000)
	cat("created file named ", filename, " in the current directory.\n",
	    " Edit the file and move it to the appropriate directory,\n",
	    paste(RHOME,"src/manual/man/",sep="/"),"dropping the ending '.Rd'\n"
	    )
	invisible(file)
}

