Procedure/Module description

I write a lot of maple code that my advisor uses, and I'm wanting to make it easier for him to use with as little extra work on my side as possible. Most recently I've started using modules to hold the procedures that go together. For example, I may have something like this

 

Resultants := module()
  description "This uses various methods to find resultants.":
  export UResultant, MacaulayResultant:

  MacaulayResultant := proc(F,vars)
    -- description and code
  end proc:

  UResultant := proc(F, vars)
 --description and code
  end proc:
end module:
print("Resultants"):
print(op([1,1], Resultants)):

This way whenever my advisor includes the file I send him ("resultants.maple") it tells him the name of the module and the names of the exported procedures from the module. Then he can type Describe(Resultants:-UResultant): to get the parameter list and the description, or just Describe(Resultants) to get everything. My only problem is that I can't seem to figure out how to get the description lines to not be ugly, when they are long. I've found the following options work (but are ugly):

description "One big long line of description that is annoying to view in any editor, esp. vi because wrapping is just plain ugly to me":

description "The first line goes here",
  "then there is a second line",
  "and so on.",
  "call me lazy but there are too many \"'s and it's still ugly to me":

description "
  Alternatively I can just totally ignore closing
  the string until the very end. This has the
  problem of reporting a warning for each procedure
  or module that contains it.":

So anyway, are there any other ideas to how I can construct my description with the least headache and still looking pretty?

Thanks, Korben

alec's picture

\n and Describe

\n in a string should start a new line when it is printed using Describe. For example,

a:=proc() description "a\nb\nc\n"; end:
Describe(a);

# a
# b
# c
# 
a( )

Alec

I realize this

Yes, I realize this, but the problem is that that code is way too ugly. The next best solution I've found is to use \ before each actual line break, which produces no warnings or errors.

proc()
  description "This is the first\
    \nThis is the second.":
end proc:

 

Alternatively I could turn off warnings at the beginning of my file and turn them back on at the end. Maybe I'm anal, but the only goal here is to find a more asthetically pleasing way to write my descriptions.

asthetics

That is I want both the code and the Describe to be asthetically pleasing.

alec's picture

Typing in different lines

What about just typing in different lines,

a:=proc() description 
"a        
b        
c"; 
end:
Describe(a);

# a        
# b        
# c
a( )

I didn't get any warnings.

Personally, I prefer series of strings in the description - for indentation purposes (in the code). Indenting code as in this example would lead to indenting it in the display given by Describe, which is not desirable usually.

Alec

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
}