Take the 2-minute tour ×
Mathematica Stack Exchange is a question and answer site for users of Mathematica. It's 100% free, no registration required.

I am writing several packages in collaboration with others. In order to help the group use my packages, I want to provide them with a simple reference of function names and usage messages. How can I best do this?

Additional information:

Although I didn't originally ask for it, I'd like to be able to do the following:

  1. save the function names with their usage messages
  2. into some text-based file (e.g. LaTeX, HTML, markdown, plain text)
  3. that organizes the functions under section headings that specify which package they came from.

Here's what it might look like in plain text:

PackageName1

function1 :: does something
function2 :: does something else

PackageName2

function3 :: does it do something?
function4 :: does, perhaps, something

Formatted versions like LaTeX that require compiling are, perhaps, less useful to the community, but they just look so nice :)

share|improve this question
4  
If you type in ?Your-package-context`* and evaluate, you will get all your symbols listed as links, which, when clicked, will open usage message for a given symbol. Depending on what you want, this may or may not be sufficient. –  Leonid Shifrin May 11 at 21:00
3  
You could #::usage & /@ Names["context`*"] too. Related topic: 38605 –  Kuba May 11 at 21:17
    
Thank you both. @LeonidShifrin, that's great to know. I still want something more like Kuba's response. It didn't quite work for me, though. Here's how I got it working: (#::usage) & /@ Symbol /@ Names["entropy*"]` (had to convert the heads to Symbol). I'm going to adapt this and answer my question with a one-liner. +1 to you both, and thanks, again. –  Rico Picone May 11 at 22:55
    
@RicoPicone You're right, I should have tried it :P –  Kuba May 11 at 22:57

2 Answers 2

A bit cleaner I believe:

Cases[
  MakeExpression @@ {Names @ "entropy`*"},
  _[s_] :> Row[{HoldForm[s], " :: ", s::usage}]
]
  • If you need a String rather than a Row expression you can use ToString @ Row[ but first try it this way.

  • Unlike your code this will work even if Symbols have OwnValues assignments.

share|improve this answer
    
Wizard, this is great. I'm exporting the result to a file for my collaborators, so I believe I need the String version. –  Rico Picone May 11 at 23:47
    
@Rico What kind of file / format? There may be a more direct way than ToString. –  Mr.Wizard May 11 at 23:48
    
Wizard, I'm still trying to decide. I was considering a nicely formatted LaTeX, but I'm open to anything (html, markdown, plain text). Do you have a good suggestion? I also need to solve the problem of adding sections to the document based-on which package it comes from. –  Rico Picone May 11 at 23:55
    
@Rico No suggestion off hand. Why don't you update your question with an example of the output you'd like (graphically if nothing else). (Normally changing the nature of your question after you receive answers is discouraged, but I'm the only one to answer so far and I'm OK with that.) –  Mr.Wizard May 11 at 23:58
    
Mr. Wizard, I edited my original question. –  Rico Picone May 12 at 0:14

Thanks to the comment by @Kuba, I was able to write this complex "one" line, which is what I wanted.

(#::usage) & /@ Symbol /@ Names["entropy`*"] // 
  MapThread[StringJoin, {(# <> " :: ") & /@ Names["entropy`*"], #}] &

If you have any suggestions to make the solution more elegant solution, please comment and I'll update it. In particular, my method of combining the strings feels clunky, as does calling Names[] twice.

Edit:

I agree that Mr. Wizard's answer is better. Here's how I used it to export the usage messages for a list of packages to a plain text file.

packageNameList = 
  {
    "utility",
    "greenSheet",
    "entropy"
  };
packageList =
  ( # <> "`*") & /@
    packageNameList;
doc = OpenWrite["doc.txt"];
For[i = 1, i <= Length[packageList], i++,
  Export[doc, "\n\nPackage: " <> packageNameList[[i]] <> "\n\n"];
  Cases[
    MakeExpression @@ {Names@packageList[[i]]}, _[s_] :> 
      ToString@Row[{"\n\n", HoldForm[s]," :: ", s::usage}]
  ] //
    Export[doc, #, "List"] &
]
share|improve this answer
1  
# <> ":: " <> (#::usage &@Symbol[#]) & /@ Names["entropy`*"] –  Kuba May 11 at 23:18
    
@Kuba, very nice. –  Rico Picone May 11 at 23:43

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.